wevu-best-practices

用途

在小程序运行时里用 wevu 写出边界清晰、更新可控、契约明确的页面、组件和 store。

何时使用

用户问 wevu 页面或组件应该怎么写。
用户问生命周期、hook 时序或 setup 约束。
用户问 props / emit / 双向绑定 / store。
用户问 setPageLayout、useNativeRouter 或 wevu/router。
用户问 AI 应如何保持 wevu 代码和模板约定一致。
用户使用纯 .jsx/.tsx、Vue 风格 TSX 或 SFC 内 JSX/TSX 编写 Wevu 页面和组件。
用户反馈卡顿、掉帧、页面切换慢、白屏、内存告警，且问题主轴在 wevu 运行时状态、渲染或副作用管理。

不适用场景

本 skill 聚焦运行时行为和状态/事件契约。

构建配置和分包：使用 weapp-vite-best-practices。
.vue 模板和宏：使用 weapp-vite-vue-sfc-best-practices。
原生迁移：使用 native-to-weapp-vite-wevu-migration。
项目级 weapp.react、React hooks 或 @weapp-vite/react bridge：使用 weapp-vite-react-best-practices。

核心流程

运行时 API 从 wevu 导入，页面和组件边界明确；选项式 data 若存在，保持函数形式。
生命周期和 hook 必须在同步 setup() 中注册，不要在 await 之后注册。
响应式更新优先 ref/reactive/computed，避免大对象和不透明状态写入；模板状态要可序列化。
- 同一轮多个 ref/reactive 变更必须由调度器完整合并，不能因先到的刷新任务吞掉后续数组或对象 patch。
事件和双向绑定遵循小程序语义：
- 事件走 emit
- 通用字段优先 bindModel/useBindModel
- parser / formatter 语义明确
layout 与 router 要分清：
- 运行时 layout 变化走 setPageLayout / usePageLayout
- 区分原生 router helpers 与 wevu/router
性能问题先分层：
- setData 路径：是否高频整对象回写、是否启用 autoSetDataPick
- render 路径：是否把重逻辑放进 onPageScroll
- navigation 路径：onHide/onUnload 是否阻塞
- resource / memory：图片尺寸、缓存、监听与定时器是否清理
store 以小 domain 为先，解构 state/getters 用 storeToRefs，避免巨大跨页 store。
- 平台分支直接判断编译期常量 import.meta.env.PLATFORM（weapp/alipay/tt/swan/jd/xhs/web）；现有 --platform / weapp.platform 自动注入目标值，无需额外裁剪配置。
- Wevu 发布包保留平台表达式供消费构建替换并删除非目标分支；独立工具链未提供目标时保留动态宿主探测。
- 能力裁剪取决于实际使用与具名导入，不新增能力开关；SFC/JSX 由 Binding Manifest 安装所需能力，没有创建 router 时不引入首航 guard 状态机。
- 区分编译器精简入口与公开动态工厂的保守兼容安装；未使用 API/fetch 时可整体移除，使用后仍保留动态跨平台 adapter。
写法同时对照项目根 AGENTS.md 和本地 dist/docs/wevu-authoring.md。
JSX/TSX 中保持小程序事件、class 和组件 tag 语义；编译后的自定义组件标签应为 kebab-case，可选链/空值合并不得残留为目标模板不支持的表达式。
Wevu 项目通过共享 ESLint 配置统一启用 @weapp-vite/eslint 的 wevuCompatibilityRecommended 与 miniProgramRuntimeRecommended，模板不要单独增加 workspace 依赖；后者限制 DOM/Node 全局、现代内建和隐式 polyfill。不要假定微信 runtime 存在 queueMicrotask，新增宿主 API 前先在目标真实 IDE AppService 中探测。旧项目可继续从 weapp-vite/eslint 兼容入口导入。
glass-easel 项目保持静态文本、属性和 Mustache 边界使用标准 WXML 实体转义；迁移时运行 wv analyze --glass-easel-check，循环内 <include> 和旧式反斜杠引号转义需人工确认语义。

Router 与平台边界

只需要宿主 navigateTo/redirectTo 时使用根入口 native router helpers；需要统一 route records、guards、resolve 和导航结果时使用 wevu/router。
小程序路由栈不提供标准前进语义；router.forward() 返回预期的 aborted failure，不应当按浏览器 bug 处理。
currentRoute 不是 Ref，isReady() 立即完成；不要引入 RouterView / RouterLink 或 Web history。
router、layout host、页面栈和 request globals 都以小程序生命周期为边界，不能套用浏览器 Vue 的挂载/卸载假设。
React 项目需要复用 Wevu SFC 时，把 Wevu 组件作为小程序自定义组件注册并由 React bridge 引用；不要让 Wevu 和 React 同时拥有同一个 JSX/TSX 模块。
性能回归必须记录高频更新信号、页面切换链路和资源清理结果，再决定是否调整 runtime 或业务状态结构。

Router 选择和迁移见 references/router-runtime-matrix.md。

约束

不要在 await 后注册 hooks。
不要直接解构 store 丢失响应性。
Store 以 Pinia 4.0.3 为参照：用 use(createPinia()) / app.use(pinia) 安装，或显式 useStore(pinia)；外部 state 自动解包，Setup 自行提供 $reset，$dispose 保留 manager 状态。createStore 是 createPinia 的同函数别名，StoreManager 继续保留；本次 minor 仍需按 PR 前后迁移指南升级旧消费者。
不要返回不可序列化原生实例到模板状态。
不要把浏览器 Vue 行为当成 wevu 默认行为。
不要在没有基线时同时修改性能、运行时和业务逻辑三类变量。

输出

应用本 skill 时，输出必须包含：

运行时风险摘要。
文件级改动建议。
相对 Vue Web runtime 的兼容说明。
最小验证命令。

完成标记

API 导入来自 wevu。
页面 / 组件边界清晰。
hook 注册时序正确。
layout、router、store 选择有明确理由。
与项目 AGENTS.md 约定一致。

参考资料

references/component-patterns.md
references/store-patterns.md
references/troubleshooting-checks.md
references/runtime-perf-matrix.md
references/tuning-recipes.md
references/router-runtime-matrix.md