快速开始

weapp-vite 当前已经不只是“把原生小程序改成 Vite 构建”这么简单。围绕一个项目，你通常会同时用到这几层能力：

• weapp-vite：开发、构建、分包策略、自动导入组件、自动路由、Web 预览、MCP。
• weapp-ide-cli：打开 IDE、预览、上传、automator 自动化，以及 CI 场景下的命令透传。
• wevu：当你使用 Vue SFC 或组合式运行时时，负责响应式、生命周期与最小化 setData 更新。
• create-weapp-vite：通过官方模板快速创建项目，并对齐目录、脚本与依赖。

如果你只是第一次接触，按本页流程走完即可。想深入某个功能时，再跳到后续专题页。

TIP

weapp-vite CLI 同时支持完整命令 weapp-vite 与简写命令 wv，两者完全等价。模板脚本通常会封装成 pnpm dev / pnpm build / pnpm open，如果你直接调用 CLI，可以任选其一。

IMPORTANT

使用前请确保安装 Node.js >=22.12.0。文档与脚手架场景统一以 Node.js 22 LTS（至少 22.12.0） 作为最低版本基线，并要求使用原生稳定支持 ESM 的版本，同时建议全局安装 pnpm（npm i -g pnpm）。

0. 准备工作

1. 下载并安装最新版 微信开发者工具。
2. 启动开发者工具，并先确认当前账号已登录。weapp-ide-cli / weapp-vite 现在会在调用前自动尝试预热 DevTools 安全设置，但首次仍建议手动确认开发者工具可正常工作。
3. 如果你希望命令行默认自动信任项目，可执行：

   weapp config set autoBootstrapDevtools true
   weapp config set autoTrustProject true

4. 如果你使用 VS Code，建议安装扩展市场里的 weapp-vite 扩展，获得命令入口、页面树、生成器、配置提示和 WXML 编辑器增强。详见 VS Code 扩展。

1. 使用官方模板

1. 创建项目

执行以下命令，创建一个集成了 weapp-vite 的项目：

pnpm

pnpm create weapp-vite

yarn

yarn create weapp-vite

npm

npm create weapp-vite@latest

bun

bun 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 / weapp-vite.config.ts

脚手架当前会根据你选择的模板，生成原生小程序、Wevu、TailwindCSS、TDesign 等不同组合。新项目建议优先用脚手架，而不是手动拷模板。

交互模式下，脚手架还会默认询问是否安装推荐的 AI skills，并提示将执行：

npx skills add sonofmagic/skills

同时会在项目根目录生成 AGENTS.md，把当前模板推荐的 AI 工作流一并带上。如果你先跳过 skills 安装，后续也可以手动执行这条命令。

2. 安装依赖

pnpm

pnpm i

yarn

yarn

npm

npm i

bun

bun i

3. 开始开发

执行 dev 命令（已开启服务端口后再添加 --open）

pnpm

pnpm dev
pnpm dev --open # 已开启服务端口时自动打开微信开发者工具

yarn

yarn dev --open # 已开启服务端口时自动打开微信开发者工具

npm

npm run dev -- --open # 已开启服务端口时自动打开微信开发者工具

bun

bun dev --open # 已开启服务端口时自动打开微信开发者工具

TIP

如果你当前是在 Codex、Claude Code、Cursor CLI 这类 AI 终端里工作，且配置保持默认 weapp.forwardConsole.enabled = 'auto'，那么 pnpm dev --open 在打开微信开发者工具后还会自动尝试把小程序 console 日志桥接回当前终端。

想手动进入持续监听模式时，可直接执行：

wv ide logs --open
# 或
wv ide logs --open

4. 打开开发者工具

执行 open 命令

pnpm

pnpm open

yarn

yarn open

npm

npm run open

bun

bun open

TIP

如果命令行提示 “请先在微信开发者工具中开启服务端口”，请回到「微信开发者工具 → 设置 → 安全设置」重新勾选该选项，并重启开发者工具后再次运行命令。

2. 手动接入现有项目

1. 先准备一个原生项目

如果你不想用脚手架，也可以先用开发者工具创建一个“原生小程序”，再手动接入 Weapp-vite：

打开微信开发者工具 → 点击 + → 依次选择：

• 开发模式: 小程序
• 后端服务: 不使用云服务
• 模板选择: 基础（JS）

使用 JS 基础模板创建项目，依然可以使用 TypeScript

如果你创建的是 TS 模板项目，请在 vite.config.ts 或 weapp-vite.config.ts 中设置 weapp.srcRoot 为 './miniprogram'。

2. 接入 weapp-vite

如果你已经有运行中的小程序，希望在原目录上直接接入 Weapp-vite，请跳转到《手动集成》查看完整步骤（依赖安装、脚本配置、目录迁移等）。这里的快速开始章节仅演示模板创建流程。

完成依赖与脚本配置后，执行一次安装命令，确保 node_modules 就绪：

pnpm

pnpm i

yarn

yarn

npm

npm i

bun

bun i

完成后，小程序 API 类型声明、weapp-vite 生成的支持文件，以及后续可选的自动路由 / 自动导入组件类型文件，都会逐步接入到编辑器提示体系里。

想要一步步把现有项目接入 Weapp-vite：参考《手动集成》。想知道 CLI 初始化做了哪些改动：阅读 wv init 做了什么?。

常用命令

完整参数、透传规则与更多示例可查看 CLI 命令参考。

开发命令

pnpm dev
pnpm dev --open # 自动预热 DevTools 配置后打开微信开发者工具
pnpm dev -o # 自动预热 DevTools 配置后打开微信开发者工具
wv ide logs --open # 持续监听 DevTools console，并桥接回终端

命令会启动监听构建。保存后会自动重新编译并同步到开发目录；配合 --open 时，会先尝试预热 DevTools 配置，再直接拉起微信开发者工具。

构建命令

pnpm build
pnpm build --open # 预热 DevTools 配置后打开微信开发者工具，见下方
pnpm build -o # 预热 DevTools 配置后打开微信开发者工具，见下方

此时会执行生产构建，重新生成输出目录，并应用压缩、静态资源处理和分包产物整理。

打开微信开发者工具命令

pnpm open
wv ide setup .

pnpm open 会直接打开微信开发者工具；wv ide setup . 则只做 DevTools 配置预热，不会立即打开 IDE。

也可以通过 weapp-vite 直接调用 weapp-ide-cli 的完整命令能力（预览、上传、automator、config 等）：

# 直接透传（推荐在脚本中使用）
wv preview --project ./dist/build/mp-weixin
wv upload --project ./dist/build/mp-weixin -v 1.0.0 -d "release"
wv config lang en
wv screenshot --project ./dist/build/mp-weixin --json
wv compare --project ./dist/build/mp-weixin --baseline .screenshots/baseline/index.png --max-diff-pixels 100 --json

# 或使用命名空间透传
wv ide preview --project ./dist/build/mp-weixin
wv ide config show
wv ide setup .

WARNING

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。

  默认情况下 CLI 会自动尝试预热 DevTools 服务端口配置；如果你不希望自动处理，可执行 weapp config set autoBootstrapDevtools false。

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 或 weapp-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/

如果两个文件同时存在，weapp-vite 会合并其中的 weapp 配置，优先级为 weapp-vite.config.* 高于 vite.config.*。