# Wevu Best Practices

> 面向小程序中 wevu 运行时的实践手册，覆盖生命周期注册、响应式更新、JSX/TSX、事件契约、`bindModel/useBindModel`、layout、原生 router helpers、`wevu/router`、store 约束，以及 `setData` 调度、渲染、页面切换、资源与内存性能治理。

- Skill: `sonofmagic/wevu-best-practices` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds add sonofmagic/wevu-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sonofmagic/wevu-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sonofmagic (https://skillmd.com/u/sonofmagic)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/sonofmagic/wevu-best-practices

---


# 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`。

## 核心流程

1. 运行时 API 从 `wevu` 导入，页面和组件边界明确；选项式 `data` 若存在，保持函数形式。
2. 生命周期和 hook 必须在同步 `setup()` 中注册，不要在 `await` 之后注册。
3. 响应式更新优先 `ref/reactive/computed`，避免大对象和不透明状态写入；模板状态要可序列化。
   - 同一轮多个 ref/reactive 变更必须由调度器完整合并，不能因先到的刷新任务吞掉后续数组或对象 patch。
4. 事件和双向绑定遵循小程序语义：
   - 事件走 `emit`
   - 通用字段优先 `bindModel/useBindModel`
   - parser / formatter 语义明确
5. layout 与 router 要分清：
   - 运行时 layout 变化走 `setPageLayout` / `usePageLayout`
   - 区分原生 router helpers 与 `wevu/router`
6. 性能问题先分层：
   - `setData` 路径：是否高频整对象回写、是否启用 `autoSetDataPick`
   - render 路径：是否把重逻辑放进 `onPageScroll`
   - navigation 路径：`onHide/onUnload` 是否阻塞
   - resource / memory：图片尺寸、缓存、监听与定时器是否清理
7. store 以小 domain 为先，解构 state/getters 用 `storeToRefs`，避免巨大跨页 store。
8. 写法同时对照项目根 `AGENTS.md` 和本地 `dist/docs/wevu-authoring.md`。
9. JSX/TSX 中保持小程序事件、class 和组件 tag 语义；编译后的自定义组件标签应为 kebab-case，可选链/空值合并不得残留为目标模板不支持的表达式。
10. Wevu 项目通过共享 ESLint 配置统一启用 `@weapp-vite/eslint` 的 `wevuCompatibilityRecommended` 与 `miniProgramRuntimeRecommended`，模板不要单独增加 workspace 依赖；后者限制 DOM/Node 全局、现代内建和隐式 polyfill。不要假定微信 runtime 存在 `queueMicrotask`，新增宿主 API 前先在目标真实 IDE AppService 中探测。旧项目可继续从 `weapp-vite/eslint` 兼容入口导入。
11. 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 丢失响应性。
- 不要调用 `createPinia()` 或向 `useStore()` 传 manager；`createStore()` 是全局时序敏感的可选插件入口，`install()` 不执行额外逻辑。
- 不要返回不可序列化原生实例到模板状态。
- 不要把浏览器 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`