mcpField
W
weapp-vite-best-practices

weapp-vite-best-practices

github.com/weapp-vite开发51848 次安装今天更新
代码仓库

关于 weapp-vite-best-practices

weapp-vite-best-practices 是面向 weapp-vite 项目的配置、构建和 AI 工作流指南，适用于项目维护者与开发者。它从稳定基础配置出发，涵盖路由、分包、CLI 命令归属及调试问题，并给出按目标逐步启用能力的流程。

主要功能

  1. 01梳理 Vite 与小程序配置
  2. 02配置路由和组件自动导入
  3. 03指导分包、npm 与 worker
  4. 04区分构建工具和 IDE CLI 命令
  5. 05排查路径、类型与路由问题
  6. 06对齐 AGENTS.md、文档与 MCP

适用场景

  1. 01诊断构建输出或路由异常
  2. 02为项目配置分包及多平台能力
  3. 03厘清 preview、upload 等命令归属
  4. 04调整 AI 调试入口与项目文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/weapp-vite/weapp-vite --skill weapp-vite-best-practices

安装后在 Claude Code 中输入/weapp-vite-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
cli-dispatch-playbook.md
config-playbook.md
debug-playbook.md
ide-command-playbook.md
ide-i18n-config-playbook.md

详细介绍

来自项目 README

weapp-vite-best-practices

用途

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

何时使用

  • 用户要配置 vite.config.ts 里的 weapp。
  • 用户要排查输出缺页、路径不对、自动路由不生效、layout 不生效。
  • 用户要接入分包、npm 落位、多平台、worker、web runtime、lib mode。
  • 用户要让 AI 正确使用项目，包括 AGENTS.md、dist/docs、screenshot / compare / logs / mcp。
  • 用户要梳理 weapp-vite 与 weapp-ide-cli 的命令归属、透传边界、preview/upload/open/config 这类 DevTools CLI 能力。

不适用场景

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

  • .vue 宏和模板兼容：使用 weapp-vite-vue-sfc-best-practices。
  • wevu 生命周期、状态和事件：使用 wevu-best-practices。
  • 原生迁移：使用 native-to-weapp-vite-wevu-migration。

核心流程

  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
    • weapp.autoRoutes
    • weapp.autoImportComponents
    • weapp.routeRules
    • weapp.typescript
  3. 按目标启用能力：
    • AI / 调试：weapp.forwardConsole、weapp.mcp、wv screenshot、wv compare、wv ide logs --open
    • 产物与结构：subPackages、npm、chunks、worker
    • 进阶链路：web、lib
  4. CLI 与 IDE 所有权保持清晰：
    • weapp-vite 原生命令优先
    • weapp-ide-cli 只在 catalog 命中后透传
    • preview / upload / open / config / screenshot / compare 的帮助、退出码、JSON 输出要稳定
    • 不要让未知命令盲目 passthrough
  5. 常见症状先分诊：
    • 输出路径不对：查 srcRoot、project config、build.outDir
    • .weapp-vite 类型异常：先跑 wv prepare
    • 页面 / layout 不对：查 autoRoutes、routeRules、definePageMeta
    • 自动导入异常：查 autoImportComponents 与 resolver
    • AI 无法稳定操作：查 AGENTS.md、dist/docs、CLI 路由、MCP
  6. 验证按最小范围进行；若改了 packages/*/src/**，下游验证前先重建对应包，并明确 dist sync: rebuilt weapp-vite before downstream validation。

约束

  • 不要在 srcRoot 和页面来源没确认前先调 chunk 策略。
  • 不要把 Web runtime 当作小程序真机等价运行时。
  • 不要忽略 AGENTS.md 和 dist/docs，它们是当前 AI 合约的一部分。
  • 不要让 weapp-vite 和 weapp-ide-cli 命令名单分裂。
  • 不要让 screenshot / compare / ide logs 的文件和 JSON 合约漂移。

输出

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

  • 诊断摘要。
  • 最小改动列表。
  • 推荐验证命令。
  • 分包 / chunk / AI 工作流的取舍说明。

完成标记

  • 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

评论

支持 Markdown