weapp-vite-vue-sfc-best-practices

# weapp-vite-vue-sfc-best-practices ## 用途 在小程序项目里用 Vue SFC 写出“编译可预测、运行时可验证、类型可跟上”的页面和组件。 ## 何时使用 - 用户问 `.vue` 文件应该怎么写。 - 用户问 JSON 宏和 `<json>` 怎么选。 - 用户问 `definePageMeta` / layout 怎么配。 - 用户遇到模板兼容或编译错误。 - 用户遇到 `.weapp-vite` 类型输出、组件声明或 route type 漂移。 ## 不适用场景 本 skill 聚焦 SFC 编写和编译期兼容。 - 项目级构建配置：使用 `weapp-vite-best-practices`。 - `wevu` 生命周期和 store：使用 `wevu-best-practices`。 - 迁移规划：使用 `native-to-weapp-vite-wevu-migration`。 ## 核心流程 1. 先判定问题阶段： - 编译期：宏、模板、`usingComponents` - 运行期：事件、hooks、响应式 - 工具层：Volar、`.weapp-vite`、typed outputs 2. 默认使用 `<script setup lang="ts">`。 3. JSON 优先走宏：`defineAppJson`、`definePageJson`、`defineComponentJson`；页面元信息走 `definePageMeta`。 4. 套用模板兼容规则： - `v-model` 只能作用于可赋值左值 - 不要假设 Web Vue 的所有模板特性都可用 - `usingComponents` 走 JSON 宏 / 自动导入，不走 Web Vue 注册思路 5. 若 `typed-router.d.ts`、`typed-components.d.ts`、`components.d.ts` 漂移，先跑 `wv prepare`。 6. 若项目有根 `AGENTS.md` 或本地 `dist/docs/vue-sfc.md`，SFC 写法要与其约束一致。 ## 约束 - 不要在一个 SFC 里混多套 JSON 宏。 - 不要把小程序组件注册当成 Web Vue 组件注册。 - 不要忽略 `prepare` 和 `.weapp-vite` 产物。 - 不要在修 SFC 语法时顺手做无关运行时重构。 ## 输出 应用本 skill 时，输出必须包含： - 问题阶段诊断。 - SFC 级改动建议。 - 模板兼容注意点。 - 最小验证命令。 ## 完成标记 - 宏使用清晰且单一。 - 模板没有踩不支持语法。 - `usingComponents` 路径安全、来源明确。 - `.weapp-vite` 支持文件和类型输出已同步。 ## 参考资料 - `references/macro-config-checklist.md` - `references/template-compat-matrix.md` - `references/troubleshooting-playbook.md`