weapp-vite-best-practices

weapp-vite-best-practices

用途

用稳定默认值先把 weapp-vite 项目跑顺，再按目标逐步接入分包、AI、Web runtime、库模式和性能优化。

何时使用

• 用户要配置 vite.config.ts 里的 weapp。
• 用户要排查输出缺页、路径不对、自动路由不生效、layout 不生效。
• 用户要接入分包、npm 落位、多平台、worker、web runtime、lib mode。
• 用户要处理支付宝 .axml/.acss、抖音 .ttml/.ttss、buildScope、sourcemap 或自动 HMR 模式选择。
• 用户要用 Vitest 对真实小程序编译产物进行页面或组件测试。
• 用户要让 AI 正确使用项目，包括 AGENTS.md、dist/docs、screenshot / compare / logs / mcp。
• 用户要梳理 weapp-vite 与 weapp-ide-cli 的命令归属、六端构建上传与 ide upload/preview/open/config 等 IDE 能力边界。

不适用场景

本 skill 聚焦项目级架构、CLI 所有权、构建编排和 AI 工作流对齐。

• .vue 宏和模板兼容：使用 weapp-vite-vue-sfc-best-practices。
• wevu 生命周期、状态和事件：使用 wevu-best-practices。
• 原生迁移：使用 native-to-weapp-vite-wevu-migration。
• React 19 JSX/TSX、render mode 和组件 bridge：使用 weapp-vite-react-best-practices。

核心流程

1. 先收集上下文：
   • vite.config.ts
   • app.json / app.json.ts
   • 分包、组件、页面目录
   • package scripts
   • 根 AGENTS.md
   • 本地 node_modules/weapp-vite/dist/docs/
2. 区分顶层 Vite 字段和小程序专属 weapp.*，先理顺基础项：
   • weapp.srcRoot
   • weapp.platform
   • weapp.multiPlatform：多端推荐 projectConfigs 平台映射，公共字段用对象展开；未写 targets 时从映射键推导。无需手工维护六份 JSON，构建器在代码输出目录内原生生成标准项目文件，代码根固定为 .。输入不写代码根字段，目录用 build.outDir；原生文件方式仍用 projectConfigRoot，不能与映射混用。AppID 可在外层配置函数按 mode 读取，Token/私钥不进入映射。
   • 多平台始终单目标构建；显式选择微信、支付宝、抖音、百度、京东、小红书或 Web，不把一次构建描述成同时产出全部平台
   • weapp.autoRoutes
   • weapp.autoImportComponents
   • weapp.i18n：基于 @weapp-vite/i18n 的微信平台 locale JSON 编译与运行时切换；defaultLocale 必填，默认扫描 **/i18n/*.json
   • weapp.uniApp：实验性外部 uni-app Vue SFC 转换；npm 包必须显式加入 include 白名单
   • weapp.routeRules
   • weapp.styles：生成主包独立样式入口并按规则注入主包与普通分包；默认不修改 app.wxss，显式 include: 'app.vue' 时可注入，也不跨入独立分包
   • weapp.buildScope / wv dev|build --scope：限定页面或分包构建时保持 autoRoutes 的主包/分包归属
   • weapp.typescript
   • weapp.hmr.runtime：显式配置优先；未配置时结合工作区 compileHotReLoad 选择 classic 或实验性 stateful 模式；实际 bundle 含 Skyline renderer 时强制关闭 DevTools 热重载并降级 classic
   • weapp.vue.template.slotFallbackWrapperStrategy：微信平台默认使用内部 virtualHost 组件承载转发 <slot /> 的具名插槽 fallback；需要旧版真实节点行为时显式设为 view
   • weapp.vue.template.slotFallbackWrapper：普通具名插槽 fallback 的真实 wrapper，可用全局默认、按模板标签名 component、子组件静态 defineOptions({ name }) 的 componentName、slot 规则和组件内 slot-wrapper / slot-wrapper-footer / slot-wrapper-class / slot-wrapper-footer-class 静态覆盖；显式配置后优先于默认策略；不要把 block 当作转发 <slot /> 的 wrapper
3. 按目标启用能力：
   • 项目检查：wv doctor 默认只读 JSON/源码；--build 与 --runtime 显式选择构建/已打开宿主。JSON/SARIF 保留分层覆盖，退出码 2 表示 incomplete，不能当作通过；宿主页面探针不能替代功能 E2E。
   • AI / 调试：weapp.forwardConsole、weapp.mcp、wv mcp init|print|doctor、wv screenshot、wv compare、wv ide logs --open
   • 产物与结构：subPackages、npm、chunks、worker、weapp.analyze.budgets / history
   • 进阶链路：web、lib
   • 页面/组件单测：@mpcore/weapp-vite 构建产物，@mpcore/test 提供 render/query/user，@mpcore/vitest 提供每测试隔离和 matcher
   • i18n：通过 import { i18n } from 'weapp-vite/i18n' 获取构建实例；Native Component 与 Component Page 使用 behaviors: [i18n.behavior]，传统 Page({...}) 使用 i18n.page(options)；主包与普通分包共享实例，独立分包从默认语言创建实例；无 Vite 原生项目直接使用 @weapp-vite/i18n
   • React 项目：这里只判断项目级 weapp.react 和构建所有权，TSX/runtime/bridge 细节转交 weapp-vite-react-best-practices
4. CLI 与 IDE 所有权保持清晰：
   • weapp-vite 原生命令通常优先；明确保留旧顶层微信 IDE upload 与 help upload 的兼容例外
   • weapp-ide-cli 只在 catalog 命中后透传
   • 原生命令包含 dev / serve / build / upload / preview / close / analyze / init / open / npm / generate / prepare / mcp
   • analyze 支持 --json、--markdown、--report pr、--budget-check、--hmr-profile、--preload、--glass-easel-check；分包预算来自 weapp.analyze.budgets，增量归因来自 weapp.analyze.history，预下载审计按触发包汇总实际分包体积与共享的 2 MB 额度
   • wv build --upload -p <平台> 复用本次构建并在产物校验通过后上传；普通 build/dev/HMR 不启用上传。weapp.upload 仅提供版本和说明，AppID 与凭据配置先读 dist/docs/upload.md 及分平台上传指南，不要把支付宝当作淘宝支持。
   • SDK wv upload/preview -p <weapp|alipay|tt|xhs|jd|swan> 自行构建后调用按需安装的官方工具；多目标用逗号分隔或显式 all，与 build -p all 的“小程序 + Web”含义不同。--dry-run 不调用 SDK；upload 只上传开发版本，preview 只生成官方预览结果，均不提审、不正式上线。顶层 preview 不在旧语法兼容范围内，IDE 预览用 wv ide preview。
   • 独立 upload --json 的 stdout 只输出单个结构化汇总，日志与官方进度进入 stderr；批量遇错停止，保留前序成功及后续 not-run。--timeout <秒> 仅限制各平台 SDK worker，不含构建；SDK 开始后超时／中断标记远端结果未确认，不等于远端取消，禁止自动重试。结果字段只取官方实际返回信息，不推断版本或统一百分比。这两个选项不用于 build --upload、preview、IDE 或 weapp.upload 配置。
   • 旧顶层 wv upload --project ./dist --version 1.2.3 --desc "release" 与 wv upload -p ./dist -v 1.2.3 -d "release" 保留原始参数、IDE 分发及退出行为，不额外触发构建；每次仅警告一次未来移除。显式 wv ide upload 不弃用、不警告，不能把原生所有权断言写成“所有 upload 都禁止 IDE 分发”。
   • 分流只依据明确方言标记：旧 --version/-v、--project、--appid、--ext-appid、--info-output/-i；SDK 长参数 --platform、--uv、--bump、--git-desc、--dry-run、--json、--timeout。混用在 IDE、编译、版本修改前报错，SDK 的 --no-* 形式也参与判断；不允许 SDK 专属选项在 IDE 调用中静默忽略。
   • -p 有旧标记时是 IDE 项目目录，否则是平台，不看目录是否存在或值是否像平台名。--desc 共用；-d 仅在旧调用中为说明，原生仍为 debug。选项值只是数据，支持分开及 = 形式，在 -- 处停止分流扫描。
   • SDK 迁移从源码项目根安装官方 SDK，配置 AppID 与 SDK 上传凭据后使用 wv build --upload -p weapp --uv 1.2.3 --desc "release"，不能把旧 --project 产物目录直接当作 SDK root，也不复用 IDE 登录。dry-run、--bump、--git-desc、--json、--timeout 只属于 SDK；保留原行为用稳定的 wv ide upload。
   • ide preview / ide upload / config / screenshot / compare 的帮助、退出码、JSON 输出要稳定；wv upload --help 保持 SDK 帮助，wv help upload 恢复旧 IDE 帮助并警告未来弃用，wv ide help upload 不警告。原生上传版本用 --uv，原生 preview 不要求上传版本。
   • 不要让未知命令盲目 passthrough
5. 常见症状先分诊：
   • 输出路径不对：查 srcRoot、project config、build.outDir
   • 支付宝/抖音原生文件缺失：先核对目标平台描述符、模板/样式扩展名和单目标 -p <platform>，不要回退成微信扩展名复制
   • .weapp-vite 类型异常：先跑 wv prepare
   • 页面 / layout 不对：查 autoRoutes、routeRules、definePageMeta
   • 自动导入异常：查 autoImportComponents 与 resolver
   • i18n 构建失败或模板未翻译：查 locale 文件名、重复/非字符串叶子、default/fallback 是否存在、WXS module 是否重名，以及模板是否通过 i18n.behavior 或传统 Page 的 i18n.page() 接入；原生无 Vite 项目再检查 weapp-i18n compile 产物和 WXS 显式引用
   • Wot UI / uview-plus / uni-app 组件库异常：同时检查 weapp.uniApp.include、resolver 的真实 resolvedId / sourceType: 'wevu-sfc'，以及目标端条件分支
   • AI 无法稳定操作：查 AGENTS.md、dist/docs、CLI 路由、MCP
   • 分包体积或 HMR 变慢：先跑 wv analyze --markdown / wv analyze --budget-check，HMR profile 已开启时再跑 wv analyze --hmr-profile
   • 外部体积消费使用小程序 analyze schema v2 的 artifacts.files，按模块所属包识别 runtime，不能猜测 chunk 文件名；实际字节与模块估算分开，runtime 预算采用含混合 chunk 的文件上界，unknown 不能作为通过
   • preloadRule 或跨分包跳转：先跑 wv analyze --preload，只把宿主导航 API 和可证明路由 binding 作为证据；结合按触发包聚合的实际体积与 2 MB 额度后，再显式配置 weapp.routeRules.<pattern>.preload
   • glass-easel 迁移：WebView glass-easel 默认不启用；开发者工具与真机基础库均不低于 3.8.12 时，才由用户在宿主 JSON 成对配置 componentFramework: 'glass-easel' 与 glassEaselWebview: true，再跑 wv analyze --glass-easel-check；低版本保持回退，不要新增重复的 weapp.glassEasel 配置
   • 状态保持 HMR 不生效：先确认生成的应用/页面 JSON 未使用 Skyline；WebView 项目再确认平台为微信、DevTools 开启服务端口与热重载、compileHotReLoad: true，并区分安全 JS/Vue 补丁与 CSS/资源/配置的完整重载回退
   • sourcemap 漂移：检查 CLI --sourcemap 透传和构建后 npm、平台 API、shared chunk 重写是否组合原 map，不接受只保留旧 map
6. 评估 Rust/native 加速时，先看真实 profile 和跨边界调用次数：
   • 默认把 JS ↔ Rust 往返、序列化/反序列化和 AST 数据搬运视为热路径成本。
   • 优先 batch analysis，一次传源码、一次 parse、一次返回多个分析结果。
   • 避免把同一份源码上的多个小 AST 查询拆成多个 N-API 调用；如果必须细粒度调用，先证明真实 HMR/build 热路径有净收益。
   • native fast path 必须显式启用、可选依赖、失败回退 Babel/Oxc/Vue compiler，并配 correctness 对齐测试与 profile。
7. 验证按最小范围进行；若改了 packages/*/src/**，下游验证前先重建对应包，并明确 dist sync: rebuilt weapp-vite before downstream validation。
8. 新增小程序 runtime API 前，先在目标真实 IDE AppService、基础库和 renderer 中验证存在性与最小调用语义；不要用浏览器、Node、类型声明或 headless 结果替代。项目源码通过共享 ESLint 配置统一接入 @weapp-vite/eslint 的 miniProgramRuntimeRecommended，模板不要单独增加 workspace 依赖，且不要假定微信运行时存在 queueMicrotask。

近期能力决策

• 插件项目先确认 weapp.pluginRoot，结构变化必须同时检查主应用 dist/ 和插件 dist-plugin/；不要只验证 host 产物。
• 状态保持 HMR 仅适用于微信小程序 WebView：需要 DevTools 服务端口、热重载和 setting.compileHotReLoad: true。实际 bundle 检测到 Skyline renderer 时，即使显式选择 stateful 也会输出官方兼容性警告、关闭项目私有配置中的热重载并降级 classic；切回 WebView 后不自动重新开启。JS/Vue 安全补丁可保留实例状态；CSS、资源、JSON、配置、边界不兼容或补丁失败时应接受完整构建回退。
• Web runtime 只验证 Web 语义，不把它当成小程序真机等价环境；请求 globals、URL 和平台 API 兼容问题要分别在目标 runtime 验证。
• Wevu 平台分支使用编译期常量 import.meta.env.PLATFORM（weapp/alipay/tt/swan/jd/xhs/web），由现有 --platform / weapp.platform 自动注入。发布包保留表达式供消费构建替换并删除非目标分支；独立工具链未提供目标时保留动态宿主探测。
• 平台分支裁剪与能力裁剪分开判断：具名导入支持移除未使用模块，没有创建 router 时不引入首航 guard 状态机；SFC/JSX 根据 Binding Manifest 安装 JSX island 等所需能力，无需额外开关。公开动态工厂保留兼容安装，已使用的 API/fetch 保留动态跨平台 adapter。
• 小程序单测不使用 jsdom；@mpcore/test 只暴露逻辑 WXML 树。测试产物必须通过 weapp-vite/test 交给 Vite/Rolldown emit，不能由适配器手写 bundle。
• uni-app 兼容层默认关闭，只转换项目源码与 include 白名单依赖；Wot UI 与 uview-plus 分别以 @wot-ui/[email protected]、[email protected] 的 npm 发布包 SFC 清单为兼容基线，不把它们泛化成完整 uni-app runtime。
• 分包、插件、worker 和 lib mode 的性能判断都先看产物结构与 wv analyze，再改 chunk/shared 策略。
• 第三方 compilerPlugins 的源码依赖通过转换结果的 dependencies 或该次异步转换内的 context.addWatchFile 声明；开发快照结束不代表 controller 会话结束。状态保持批次读取 request.sources 冻结视图，产物仍由 Vite/Rolldown 写出。完整验收要区分产物、JS 补丁和真实 IDE 计算样式。
• 主包共享样式优先使用 weapp.styles 保持独立产物；默认排除 app，只有显式 include: 'app.vue' 等应用入口时才注入 app.wxss；inject: false 只 emit，独立分包必须通过自己的 subPackages.<root>.styles 持有副本。
• 内置 i18n v1 只支持 {name} / {user.name} 插值，不提供 ICU、复数、日期/数字格式化或自动 storage 持久化；非微信平台不要启用。

参考决策表

• HMR 行为：references/stateful-hmr-playbook.md
• 插件双产物：references/plugin-build-playbook.md
• Web runtime 与 URL：references/web-runtime-compatibility.md
• native AST：references/native-ast-performance-checklist.md

约束

• 不要在 srcRoot 和页面来源没确认前先调 chunk 策略。
• 不要把 Web runtime 当作小程序真机等价运行时。
• 不要忽略 AGENTS.md 和 dist/docs，它们是当前 AI 合约的一部分。
• 不要让 weapp-vite 和 weapp-ide-cli 命令名单分裂。
• 不要让 screenshot / compare / ide logs 的文件和 JSON 合约漂移。
• 不要用大量细粒度 JS ↔ Rust 调用替代原本一次 JS AST 遍历；native 加速要先合并通信边界，再用真实 profile 扩大覆盖。

输出

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

• 诊断摘要。
• 最小改动列表。
• 推荐验证命令。
• 分包 / chunk / AI 工作流的取舍说明。
• 若涉及 Rust/native 加速，说明是否减少跨边界调用次数，以及真实 profile 是否支持继续扩大迁移。

完成标记

• weapp 配置结构清晰。
• 路由和组件来源明确。
• .weapp-vite 支持文件流程已考虑。
• CLI 原生命令、IDE 透传和 AI 路由不冲突。
• AGENTS.md、dist/docs、MCP、截图和日志入口保持一致。

参考资料

• references/config-playbook.md
• references/debug-playbook.md
• references/cli-dispatch-playbook.md
• references/ide-command-playbook.md
• references/ide-i18n-config-playbook.md
• references/stateful-hmr-playbook.md
• references/plugin-build-playbook.md
• references/web-runtime-compatibility.md
• references/native-ast-performance-checklist.md

标准 Vite 插件（实验性）

• 配置可导入 weapp from weapp-vite/vite，以 plugins: [weapp()] 激活；继续读取顶层 weapp。
• 当前插件支持单目标微信生产构建与实验性 classic/stateful 开发（vite dev / vp dev，通过顶层 weapp.hmr.runtime 选择），以及原生 vite build --watch / vp build --watch（生产完整产物，修改宿主配置后需重启命令）；支持微信原生 TS、Wevu Vue 与 React；React 静态 TSX 的 stateful 更新会重建会话，不承诺 hooks 状态保持。已支持独立分包及其宿主监听、子构建配置复用；worker 已进入共享子目标与宿主监听；stateful worker 更新使用完整批次，不承诺线程状态保持。微信插件双产物已接入独立会话与原生 app builder；插件更新不承诺状态保持，双产物暂不支持 build.write: false。lib mode 已共用原生声明发布、classic 开发与生产 watch；六平台原生 TS/Vue 支持顶层 weapp.platform 单目标选择、classic 与生产 watch；多平台目录式项目配置走原生写出，stateful 仍仅限微信，其他平台真实 IDE 和高级组合单独验收。纯 Web 使用顶层 weapp.platform: 'web'，复用同一插件与浏览器宿主；需要既有 Web HTML 入口，不要求小程序项目配置。Web/小程序混合宿主仍待对齐。独立 wv dev/build 保留完整能力。
• 宿主配置是唯一隐式来源；插件不会再次发现 weapp-vite.config.*。Vite+ 要按官方 alias 规则统一 vite 与 core，不能只看版本号相等。
• 脚手架的 --toolchain=wv|vite|vite-plus 与业务模板独立。生成的 vite*.config.ts 显式导入共享配置，按目标单独启用 Web；prepare/open/upload/mcp 仍由 wv 提供，不能把 wv --platform 传给普通宿主。已有 pnpm workspace 必须先统一 Vite+ core 与配套 Vitest override；严格 peer 检查只为固定 core 的 Vite alias 声明版本兼容，脚手架不修改上级工作区。
• npm.buildOptions 的回调接收最终路径，可返回 false 跳过包；手工 npm 映射共用 CLI 的主 manifest/镜像语义。产物仍交给原生 emit/write，外部映射保存精确文件归属；build.write: false 仅支持宿主输出目录内的 npm 产物。
• Vitest 配置加载不启动小程序编译。vp preview、vp pack 不能分别解释为微信预览或小程序组件库构建。
• 使用前优先读取当前包 dist/docs/vite-plugin.md 的支持矩阵，不把后续路线图当成已发布能力。