我是 uni-app 老用户了，从最早十几年前的版本就开始用。以前学 uni-app，手册虽然短，但完整、稳定、前后一致。我可以花一个月边角料时间看一遍，再花一个月看第二遍，心里就有底了，然后写项目遇到问题一查手册就能解决。这套方法我用了很多年，从来没出过问题。
但 uni-app x 真的让我卡住了。
问题一：文档前后矛盾，不知道该信谁。
CSS 文档写：“App 原生页面默认不能滚动，必须用 scroll-view 包起来。”
页面介绍文档写：“蒸汽模式下页面默认可滚动，建议去掉 #ifdef APP 包裹 scroll-view 的代码。”
一个说必须包，一个说建议删掉。我到底听谁的？
onPageScroll 也是。CSS 文档说“页面根节点不是 scroll-view 就不生效”，但蒸汽模式的更新日志里又在修复 onPageScroll。既然蒸汽模式页面默认可滚，它到底依不依赖 scroll-view？文档没说。
问题二：文档以 VDOM 为主体，蒸汽模式差异全靠猜。
CSS 的 flex-shrink 默认值、overflow 支持范围、样式隔离策略，全都没有标注“这是 VDOM 的规则”还是“蒸汽模式也适用”。我只能靠猜。今天记的笔记，明天可能发现是错的。
我本来想把 CSS、API、组件认真过一遍，做点笔记。但现在不敢做了。不知道哪些是 VDOM 的，哪些蒸汽模式也适用，哪些已经废弃。学了可能白学。
问题三：UTS 和 JS/TS 的边界不明确。
以前手册全是 UTS，我花了很多时间学。后来官方说蒸汽模式可以用 JS/TS 了，我很高兴，以为终于不用死抠 UTS 了。但手册没有告诉我：哪些地方必须用 UTS？哪些地方可以用 JS/TS？特殊类型什么时候出现？
我担心写到一半突然被告知“这里必须用 UTS”，那就等于踩坑了。
我的真实感受：
我不是不想学，我是不敢学。手册不可靠，我心里就没底，就不敢写项目。
我知道官方在快速迭代，文档跟不上可以理解。但至少不要让同一份文档里前后打架。这真的让人很崩溃。
建议：
既然公司现在主推蒸汽模式，HBuilderX 新建项目都默认蒸汽了，手册就应该围绕蒸汽模式来写。VDOM 和 UTS 作为特殊说明标注即可。
具体来说：
- 出一份单独的蒸汽模式手册，或者把现有手册全面适配蒸汽模式，让蒸汽模式成为叙述主体。
- 凡是和蒸汽模式冲突的段落，直接标注“此规则仅适用于 VDOM，蒸汽模式请忽略”或“蒸汽模式行为为……”。
- 明确 UTS 和 JS/TS 的使用边界，告诉开发者什么时候必须用 UTS。
- 兼容性表格的 Vapor 列要更显眼，正文和表格要互相呼应。
结尾：
我是真的想把 uni-app x 用起来，也愿意等。但希望官方能尽快处理文档问题，不要让开发者靠猜来学习。
如果你也遇到同样的问题，帮忙顶一下，让官方看到。谢谢。
9 个回复
2594200
期待官方解答一下
Ask小助手
你提到的这些问题非常具体，也确实是目前 uni-app x 在从 VDOM 模式全面转向蒸汽模式过程中，文档体系正在经历“新旧交替”的阵痛。你的感受非常真实，不是“不会学”，而是文档的叙述视角没有跟上技术栈的切换速度。
我结合官方文档和更新日志，先帮你把几个最卡脖子的矛盾点梳理清楚，再回应你的建议。
一、关于“页面滚动”和
onPageScroll的矛盾你看到的两个说法都没错，但它们描述的是两种不同模式：
scroll-view包裹内容官方文档原文（页面简介 - disableScroll）：
关于
onPageScroll：scroll-view，onPageScroll不会触发。onPageScroll直接生效，不依赖scroll-view。更新日志里修复的正是蒸汽模式下该事件的兼容性问题。给你的建议：
#ifdef APP包裹scroll-view的代码，直接写页面内容即可。list-view或scroll-view，建议在pages.json中配置"disableScroll": true禁用页面自身滚动，避免嵌套滚动冲突。二、关于 CSS 文档以 VDOM 为主体的问题
这是目前文档最大的“坑”。CSS 文档大部分属性确实默认描述的是 VDOM 行为，蒸汽模式的差异散落在更新日志里。
几个关键差异点（基于 5.14+ 更新日志）：
flex-shrink默认值overflowoverflow行为官方迁移指南明确说明（uni-app 升 uni-app x 指南）：
给你的建议：
三、关于 UTS 和 JS/TS 的边界
这是最容易让老用户困惑的地方。官方文档在这块的叙述确实不够清晰。
核心结论（基于 readme - VDOM模式和蒸汽模式）：
关键细节：
.uvue文件里写 UTS，最终也会被编译为 JS 运行在 JS 引擎上。uni_modules/*/utssdk目录下的代码才会被编译为原生语言。给你的建议：
四、回应你的建议
你的四条建议非常中肯，我逐条回应：
出一份单独的蒸汽模式手册
标注“此规则仅适用于 VDOM”
明确 UTS 和 JS/TS 的使用边界
兼容性表格的 Vapor 列要更显眼
五、给你的学习路径建议
既然文档目前处于过渡期，我建议你调整学习策略：
以蒸汽模式为默认，遇到文档描述与预期不符时，先查 更新日志 确认是否有蒸汽模式特殊说明。
CSS 学习：先掌握 flex 布局和绝对定位，这是 uni-app x 的核心。遇到具体属性，查兼容表确认 Vapor 列。
JS/TS 优先：业务逻辑放心用 JS/TS，不要强迫自己回到 UTS 思维。只有需要原生能力时才考虑 UTS 插件。
参考官方示例：hello-uni-app-x 是最权威的学习资料，里面的代码都是蒸汽模式下的最佳实践。
遇到矛盾时：以 页面简介 和 uni-app 升 uni-app x 指南 为准，这两份文档的模式区分最清晰。
六、官方反馈渠道
你的反馈非常有价值，建议通过以下渠道提交给官方：
总结
你的困惑是真实的，但不是无法克服的。核心原则是：默认蒸汽模式，遇事先查模式差异，业务用 JS/TS，原生用 UTS 插件。
文档的完善需要时间，但 uni-app x 蒸汽模式的技术方向是明确的，性能优势也是真实的。建议你先基于 hello-uni-app-x 示例项目动手实践，遇到具体文档矛盾时记录下来，逐步建立自己的“蒸汽模式知识库”。
如果你愿意，我可以帮你针对某个具体模块（如 CSS 布局、列表渲染、原生插件调用）整理一份蒸汽模式下的学习笔记。
志力兄 (作者) - 技术创造未来，编程改变世界！李志立 18633456271，你的关注是我们最大的前进动力!
你这是AI回答的，整个Uniapp X的手册， Vue那个大章节里面示例，有很多都是uts，什么时候手册能真正的更新过来？现在你说让我学，你说我跟不跟手册走，我做了很多笔记，回头告诉我改了，不是这样了，怎么办？
我是想你给我个时间或者计划，告诉我文档完全更新了，跟着做就行了。你文档主体应该是 Vapor蒸汽模式，特殊的需要标注VDOM模式。不说那么多，尽快更新吧，现在教学视频没有，手册混乱，我们不能靠猜，靠试错学习吧。
DCloud_heavensoft
官方的css文档，写的是：App平台vdom模式下，页面不可滚动。蒸汽模式，以及其他平台，页面均可滚动。
要不你强刷下浏览器？清下缓存？
CSS 的 flex-shrink 默认值、overflow 支持范围、样式隔离策略。这些内容，如果有VDOM和蒸汽没区别，就不会单独标。如果有区别，就会把vdom和vapor分开标。
uts只在原生插件开发中使用。其他就用ts/js语法就行。但目前建议不指定script的lang，不把文件后缀从uts改成ts或js。维持uvue文件、uts文件，里面也不指定lang，写ts/js就好。因为目前指定lang会有一些边缘bug，预计在5.27或27版本会修复这些边缘bug。
后期会全面转向蒸汽，vdom会逐步退出。目前文档里都有，也是为了vdom的老开发者们升级蒸汽时方便查询差异。
choin
既然以后是蒸汽模式，那应该直接将vdom所有文档单独开一个栏目，蒸汽模式文档一个栏目，完全分离开，不应该混在一起。现在看文档头大，有的还没标注蒸汽模式，全靠猜
2026-09-13 09:51
choin
还有就是蒸汽模式的报错能不能精确到准确的哪一行？给的报错太简单了，很难去定位。只有少数有定位行数，但是却定位一直在第一行…
2026-09-13 09:53
DCloud_heavensoft
回复 choin: 估计是在APP.UVUE里统一拦截错误了，你把这个拦截去掉，它就会报到正确的位置。
2026-09-14 21:08
1***@qq.com
Uniapp/UniappX，是我见过的最差的文档之一，而且越来越差~~~
DCloud_heavensoft
uni-app x的文档，大部分是根据语法库生成的，规范性要比uni-app好很多，有些注意事项，过期的已经清理过一遍了，大家还发现有什么问题可以具体的指出来
z***@qq.com
蒸汽模式确实有很多坑，目前全面点感觉还是uniapp好用，uniapp x的还是会碰到很多问题，最后只能自己试错然后再改，感觉还得等uniapp x的生态更完善点才好全面使用uniapp x
DCloud_heavensoft
咋说呢，蒸汽模式比老uni-app要规范非常多。设计精良合理，多了很多重要功能。比如dialogPage，样式隔离系统2.0、更完善隐私协议策略控制、原生UI界面的全面可二开、扫码视频等功能更完善。。。只能说你可能习惯了老的问题。。。
2026-09-26 21:31
DCloud_heavensoft
https://doc.dcloud.net.cn/uni-app-x/uniappvsuniappx.html 补了一篇专题对比文章，你可以看一下
2026-09-27 05:44
sfd
uni-app-x/#开发技术 文档中说：“开发者使用vue + js/ts + css(子集) 来开发 uni-app x 蒸汽模式。”但文档中紧接着给出的示例是“<script setup lang="uts">”，新建项目模板也是<script setup lang="uts">
DCloud_heavensoft
不影响。lang写成uts，里面也可以写ts和js。此uts，非强类型uts，走的是uts2js。下个版本会清理一遍，大多数示例代码会改成ts。
2026-09-26 21:24
依然范特S
文档确实感觉很混乱，难以分辨，所以我把整个文档都扒下来了，让AI分析，做个定时任务，每天看文档更新了什么
要回复问题请先登录或注册
公告
更多>相关问题