使用文档地址: vite.icebreaker.top

Features

• 🚀 Vue 3 支持：完整的 Vue 单文件组件（SFC）支持，使用 Vue 官方编译器

  • <script setup> 和 TypeScript 完整支持
  • 完整的模板语法（v-if、v-for、v-model 等）
  • Scoped CSS 和 CSS Modules
  • 动态组件、过渡动画、KeepAlive
  • 详细文档 →

• ⚡️ Vite 构建：带来了 typescript / scss / less 等等的原生支持

• 🔌 插件生态：Vite 插件生态支持，也可以自定义编写插件，方便扩展

• 🧰 IDE 命令增强：可直接透传 weapp-ide-cli 全量命令（preview/upload/config/automator 等）

快速开始

说明：CLI 同时支持完整命令 weapp-vite 与简写命令 wv，两者等价。下面的示例默认使用 weapp-vite，你也可以按个人习惯替换成 wv。

Vue 项目

// vite.config.ts
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    srcRoot: 'src',
    vue: {
      enable: true,
      template: {
        removeComments: true,
      },
    },
  },
})

<!-- App.vue -->
<script setup>
import { ref } from 'vue'

const message = ref('Hello Vue in Mini-program!')

function handleClick() {
  console.log('Button clicked!')
}
</script>

<template>
  <view class="container">
    <text>{{ message }}</text>
    <button @click="handleClick">
      Click
    </button>
  </view>
</template>

<style scoped>
.container {
  padding: 20rpx;
}
</style>

📚 完整文档: Vue 支持文档

• 配置智能提示文档：docs/volar.md
• defineConfig 重载说明：docs/define-config-overloads.md
• Vite 插件识别 weapp-vite 宿主：https://vite.icebreaker.top/guide/vite-plugin-host
• MCP 集成使用指南：docs/mcp.md

AI 项目指引

通过 create-weapp-vite 创建的新项目，现在会默认携带一个根目录 AGENTS.md。同时，weapp-vite npm 包会随版本发布一份本地文档目录：node_modules/weapp-vite/dist/docs/。

这个文件会告诉常见 AI 编程代理：

• 安装依赖后，优先阅读 node_modules/weapp-vite/dist/docs/README.md、node_modules/weapp-vite/dist/docs/mcp.md 等本地版本文档
• CLI 同时支持 weapp-vite 与 wv
• 需要做小程序截图采集时，优先使用 weapp-vite screenshot / wv screenshot
• 需要做小程序截图对比验收时，优先使用 weapp-vite compare / wv compare
• 不要把小程序运行时截图退化成通用浏览器截图
• 需要看 DevTools 终端日志时，优先使用 weapp-vite ide logs --open 或 wv ide logs --open

推荐把下面这组意图映射写进项目根 AGENTS.md，让常见 AI 更稳定命中：

• 提到 截图、页面快照、runtime screenshot
  • 默认使用 weapp-vite screenshot / wv screenshot
• 提到 截图对比、diff、baseline、视觉回归、像素对比
  • 默认使用 weapp-vite compare / wv compare
• 提到 运行时日志、DevTools 日志
  • 默认使用 weapp-vite ide logs --open / wv ide logs --open

dist/docs 当前会内置这些文件：

• README.md
• getting-started.md
• ai-workflows.md
• project-structure.md
• weapp-config.md
• wevu-authoring.md
• vue-sfc.md
• troubleshooting.md
• mcp.md
• volar.md
• define-config-overloads.md
• index.md

推荐的截图命令示例：

weapp-vite screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json

# 等价写法
wv screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json

推荐的截图对比命令示例：

weapp-vite compare --project ./dist/build/mp-weixin --page pages/index/index --baseline .screenshots/baseline/index.png --diff-output .tmp/index.diff.png --max-diff-pixels 100 --json

# 等价写法
wv compare --project ./dist/build/mp-weixin --page pages/index/index --baseline .screenshots/baseline/index.png --diff-output .tmp/index.diff.png --max-diff-pixels 100 --json

DevTools 日志桥接

weapp-vite 现在支持把微信开发者工具里的小程序 console 输出桥接到当前终端。

默认行为：

• weapp.forwardConsole 默认是 enabled: 'auto'
• 当检测到当前运行环境是 AI 终端时，weapp-vite dev --open 会自动尝试附加日志桥
• 也可以手动进入持续监听模式

配置示例：

import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    forwardConsole: {
      enabled: 'auto',
      logLevels: ['log', 'info', 'warn', 'error'],
      unhandledErrors: true,
    },
  },
})

手动启动持续监听：

weapp-vite ide logs
weapp-vite ide logs --open
# 等价写法
wv ide logs
wv ide logs --open

CLI 中调用 weapp-ide-cli

weapp-vite 内置了对 weapp-ide-cli 的透传能力，除了 dev/build/open/init/generate/analyze/npm 等原生命令外，其它 IDE 相关命令都可以直接调用：

weapp-vite preview --project ./dist/build/mp-weixin
weapp-vite upload --project ./dist/build/mp-weixin -v 1.0.0 -d "release"
weapp-vite cache --clean compile
weapp-vite cache --clean all
weapp-vite config lang zh
weapp-vite navigate pages/index/index --project ./dist/build/mp-weixin
# 等价写法
wv preview --project ./dist/build/mp-weixin
wv cache --clean all

也支持命名空间写法：

weapp-vite ide preview --project ./dist/build/mp-weixin
weapp-vite ide config show
weapp-vite ide logs --open
# 等价写法
wv ide preview --project ./dist/build/mp-weixin

CLI 启动 MCP

weapp-vite 已集成 @weapp-vite/mcp：

• 默认不自动启动 MCP 服务（可通过配置开启自动启动）
• 优先推荐直接生成客户端配置，而不是手写 MCP 地址

wv mcp init codex
wv mcp init claude-code
wv mcp init cursor

检查配置是否可用：

wv mcp doctor codex

仍然需要手动启动 MCP Server 时：

weapp-vite mcp
# 等价写法
wv mcp

指定工作区根路径：

weapp-vite mcp --workspace-root /absolute/path/to/weapp-vite
# 等价写法
wv mcp --workspace-root /absolute/path/to/weapp-vite

在 vite.config.ts 中开启自动启动：

import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    mcp: {
      autoStart: true,
    },
  },
})

详细说明见：docs/mcp.md

Contribute

我们邀请你来贡献和帮助改进 weapp-vite 💚💚💚

以下有几个方式可以参与:

• 报告错误：如果您遇到任何错误或问题，请提issue并提供完善的错误信息和复现方式。
• 建议：有增强 weapp-vite 的想法吗？请提 issue 来分享您的建议。
• 文档：如果您对文档有更好的见解或者更棒的修辞方式，欢迎 pr。
• 代码：任何人的代码都不是完美的，我们欢迎你通过 pr 给代码提供更好的质量与活力。

License

MIT