快速开始
weapp-vite 当前已经不只是“把原生小程序改成 Vite 构建”这么简单。围绕一个项目，你通常会同时用到这几层能力：
weapp-vite：开发、构建、分包策略、自动导入组件、自动路由、Web 预览、MCP。weapp-ide-cli：打开 IDE、预览、上传、automator 自动化，以及 CI 场景下的命令透传。wevu：当你使用 Vue SFC 或组合式运行时时，负责响应式、生命周期与最小化setData更新。create-weapp-vite：通过官方模板快速创建项目，并对齐目录、脚本与依赖。
如果你只是第一次接触，按本页流程走完即可。想深入某个功能时，再跳到后续专题页。
IMPORTANT
使用前请确保安装 Node.js ^20.19.0 || >=22.12.0。建议使用 Node.js 官网 的 LTS，并全局安装 pnpm（npm i -g pnpm）。
0. 准备工作
- 下载并安装最新版 微信开发者工具。
- 启动开发者工具，在「设置 > 安全设置」中勾选 服务端口。这是
pnpm dev --open、pnpm open等命令能唤起 IDE 的前提。 - 第一次使用建议先手动打开一次项目，确认开发者工具可用，避免后续命令行提示 “请先在微信开发者工具中开启服务端口”。
1. 使用官方模板
1. 创建项目
执行以下命令，创建一个集成了 weapp-vite 的项目：
pnpm create weapp-viteyarn create weapp-vitenpm create weapp-vite@latestbun create weapp-vite生成的 my-app 项目中，默认包含以下内容:
.
├── README.md
├── package.json
├── project.config.json
├── project.private.config.json
├── src
│ ├── app.json
│ ├── app.scss
│ ├── app.ts
│ ├── components
│ │ └── HelloWorld
│ │ ├── HelloWorld.json
│ │ ├── HelloWorld.scss
│ │ ├── HelloWorld.ts
│ │ └── HelloWorld.wxml
│ ├── pages
│ │ └── index
│ │ ├── index.json
│ │ ├── index.scss
│ │ ├── index.ts
│ │ └── index.wxml
│ ├── sitemap.json
│ ├── theme.json
│ ├── utils
│ │ └── util.ts
│ └── vite-env.d.ts
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts脚手架当前会根据你选择的模板，生成原生小程序、Wevu、TailwindCSS、TDesign 等不同组合。新项目建议优先用脚手架，而不是手动拷模板。
2. 安装依赖
pnpm iyarnnpm ibun i3. 开始开发
执行 dev 命令（已开启服务端口后再添加 --open）
pnpm dev
pnpm dev --open # 已开启服务端口时自动打开微信开发者工具yarn dev --open # 已开启服务端口时自动打开微信开发者工具npm run dev -- --open # 已开启服务端口时自动打开微信开发者工具bun dev --open # 已开启服务端口时自动打开微信开发者工具4. 打开开发者工具
执行 open 命令
pnpm openyarn opennpm run openbun openTIP
如果命令行提示 “请先在微信开发者工具中开启服务端口”，请回到「微信开发者工具 → 设置 → 安全设置」重新勾选该选项，并重启开发者工具后再次运行命令。
2. 手动接入现有项目
1. 先准备一个原生项目
如果你不想用脚手架，也可以先用开发者工具创建一个“原生小程序”，再手动接入 Weapp-vite：
打开微信开发者工具 → 点击 + → 依次选择：
开发模式: 小程序后端服务: 不使用云服务模板选择: 基础（JS）
使用
JS基础模板创建项目，依然可以使用TypeScript
如果你创建的是 TS 模板项目，请在
vite.config.ts中设置weapp.srcRoot为'./miniprogram'。
2. 接入 weapp-vite
如果你已经有运行中的小程序，希望在原目录上直接接入 Weapp-vite，请跳转到《手动集成》查看完整步骤（依赖安装、脚本配置、目录迁移等）。这里的快速开始章节仅演示模板创建流程。
完成依赖与脚本配置后，执行一次安装命令，确保 node_modules 就绪：
pnpm iyarnnpm ibun i完成后，小程序 API 类型声明、weapp-vite 生成的支持文件，以及后续可选的自动路由 / 自动导入组件类型文件，都会逐步接入到编辑器提示体系里。
想要一步步把现有项目接入 Weapp-vite：参考《手动集成》。想知道 CLI 初始化做了哪些改动：阅读
weapp-vite init 做了什么?。
常用命令
完整参数、透传规则与更多示例可查看 CLI 命令参考。
开发命令
pnpm dev
pnpm dev --open # 已开启服务端口时自动打开微信开发者工具
pnpm dev -o # 已开启服务端口时自动打开微信开发者工具命令会启动监听构建。保存后会自动重新编译并同步到开发目录；如果已开启服务端口，也可以配合 --open 直接拉起微信开发者工具。
构建命令
pnpm build
pnpm build --open # 打开微信开发者工具，见下方
pnpm build -o # 打开微信开发者工具，见下方此时会执行生产构建，重新生成输出目录，并应用压缩、静态资源处理和分包产物整理。
打开微信开发者工具命令
pnpm open使用该命令直接打开微信开发者工具（需要先开启服务端口）。
也可以通过 weapp-vite 直接调用 weapp-ide-cli 的完整命令能力（预览、上传、automator、config 等）：
# 直接透传（推荐在脚本中使用）
weapp-vite preview --project ./dist/build/mp-weixin
weapp-vite upload --project ./dist/build/mp-weixin -v 1.0.0 -d "release"
weapp-vite config lang en
weapp-vite screenshot --project ./dist/build/mp-weixin --json
# 或使用命名空间透传
weapp-vite ide preview --project ./dist/build/mp-weixin
weapp-vite ide config showWARNING
weapp-vite 会优先执行自己的原生命令；只有未命中时，才会回退透传到 weapp-ide-cli。因此 build/dev/open/analyze/generate/mcp/prepare 这些命令不会被官方 IDE CLI 覆盖。
下一步建议
- 想了解命令行能力边界：看 CLI 命令参考。
- 想开始使用 Vue 单文件组件：看 Vue SFC 开发 和 Wevu 概览。
- 想减少手写
app.json.pages与usingComponents：看 自动路由 与 自动导入组件。 - 想做 AI 协作或本地 MCP：看 AI 协作 与 @weapp-vite/mcp。
请在
微信开发者工具→设置→安全设置→ 勾选服务端口。
WARNING
Linux 目前没有官方微信开发者工具，请安装社区版：msojocs/wechat-web-devtools-linux，并把 wechat-devtools-cli 链接到系统 PATH，例如：
sudo ln -s /opt/apps/io.github.msojocs.wechat-devtools-linux/files/bin/bin/wechat-devtools-cli /usr/local/bin/生成组件命令
pnpm g [filename]用于快速生成页面/组件/App 等基础文件，详见 生成脚手架。
简易配置项
如果你用微信开发者工具创建的是 TypeScript 模板（源码目录为 miniprogram/），需要把 weapp.srcRoot 指向它；否则按模板默认的 src/ 即可。
配置项可以与 vite 通用，同时加入了 weapp-vite 的扩展:
vite.config.[m]ts:
import { defineConfig } from 'weapp-vite/config'
export default defineConfig({
weapp: {
// 让 weapp-vite 知道 app.json / pages/ 在哪个目录下
srcRoot: './miniprogram',
},
})你也可以在 defineConfig 里继续使用其他 Vite 插件（例如 weapp-tailwindcss）。
更多配置见：/config/