---
url: /packages/mcp.md
description: '@weapp-vite/mcp 是 weapp-vite 与 wevu 的 MCP 服务实现，面向 AI 助手提供源码检索、命令执行与文档资源能力。'
---

# @weapp-vite/mcp

`@weapp-vite/mcp` 是 `weapp-vite` 官方维护的 MCP 服务实现，目标是把 `weapp-vite / wevu / wevu-compiler` 的关键研发能力暴露给 AI 助手。

在当前版本中，`weapp-vite` 已集成该能力，你通常不需要单独使用此包，而是直接通过 `weapp-vite mcp` 启动。

## 何时使用

1. 你要让 AI 助手直接读取 `weapp-vite` 仓库源码与文档。
2. 你要让 AI 在受限命令白名单下完成“修改 + 验证”闭环。
3. 你要基于官方 MCP 能力扩展团队内部 AI 工作流。

## 安装

```bash
pnpm add @weapp-vite/mcp
```

## 启动方式

推荐直接使用 `weapp-vite` CLI：

```bash
weapp-vite mcp
```

不在仓库目录执行时，可选追加 `--workspace-root /path/to/weapp-vite`。

如果你只想单独运行包本身：

```bash
pnpm --filter @weapp-vite/mcp start
```

## 主要能力

Tools：

1. `workspace_catalog`
2. `list_source_files`
3. `read_source_file`
4. `search_source_code`
5. `run_package_script`
6. `run_weapp_vite_cli`
7. `run_repo_command`

Resources：

1. `weapp-vite://workspace/catalog`
2. `weapp-vite://docs/{package}/README.md`
3. `weapp-vite://docs/{package}/CHANGELOG.md`
4. `weapp-vite://source/{package}?path={path}`

Prompts：

1. `plan-weapp-vite-change`
2. `debug-wevu-runtime`

## 安全约束

1. 文件读取限制在 workspace 根目录内。
2. 命令执行限制在白名单（`pnpm/node/git/rg`）。
3. 输出内容有截断与超时保护。

## 二次开发建议

若你要扩展能力，建议从以下文件开始：

1. `packages/mcp/src/server.ts`：工具/资源/Prompt 注册入口。
2. `packages/mcp/src/fileOps.ts`：文件读取与搜索策略。
3. `packages/mcp/src/commandOps.ts`：命令白名单与执行约束。

## 关联阅读

1. [AI 协作指南](/guide/ai)
2. [AI 学习入口](/ai)

---

---
url: /packages/volar.md
description: '@weapp-vite/volar 为 Weapp-vite 项目提供 Volar 语言服务能力，重点增强 配置块的补全与校验。'
---

# @weapp-vite/volar

`@weapp-vite/volar` 为 Weapp-vite 项目提供 Volar 语言服务能力，重点增强 `<json>` 配置块的补全与校验。

## 何时使用

* 你在 `.vue` 文件里使用 `<json>` 自定义块
* 你希望拿到配置字段的类型提示和错误检查
* 你在 VSCode + Volar 环境下做小程序配置开发

## 安装说明

通常不需要单独安装。使用 `weapp-vite` 时会自动带上该能力。

```bash
pnpm add -D @weapp-vite/volar
```

## 主要能力

* `<json>` 块配置提示与校验
* JSON Schema 语义支持
* 依据路径自动推断 `App/Page/Component` 配置类型
* 支持 `json/jsonc/json5` 与 js/ts 配置表达

## 推荐阅读

* [JSON 配置智能提示](/guide/json-intelli-sense)
* [使用 TS/JS 生成 JSON](/guide/json-enhance)

---

---
url: /packages/web.md
description: '@weapp-vite/web 是实验性的 H5 运行时与 Vite 插件，用于把小程序模板能力映射到浏览器环境做验证。'
---

# @weapp-vite/web

`@weapp-vite/web` 是实验性的 H5 运行时与 Vite 插件，用于把小程序模板能力映射到浏览器环境做验证。

> 当前仍是 POC 阶段，适合技术验证，不建议直接作为生产方案。

## 何时使用

* 你要在浏览器快速验证小程序页面逻辑
* 你要做模板编译、事件桥接、路由行为的实验
* 你要为小程序 DSL 做 Web 演示或调试

## 安装

```bash
pnpm add -D @weapp-vite/web
```

## Vite 插件接入

```ts
import { weappWebPlugin } from '@weapp-vite/web'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    weappWebPlugin({
      srcDir: 'src',
      runtime: {
        executionMode: 'compat',
      },
    }),
  ],
})
```

## 运行时能力

包内同时导出运行时 API，例如：

* `defineComponent`
* `registerApp` / `registerPage` / `registerComponent`
* `navigateTo` / `navigateBack` / `getCurrentPages`
* `request` / `showToast` 等 polyfill API

## 能力边界

* 支持 `wx:if` / `wx:for` / 插值等常见语法
* 支持小程序到 DOM 事件桥接（如 `bindtap`）
* 样式与 API 兼容度仍在持续补齐

---

---
url: /packages/weapi.md
description: '@wevu/api 独立文档入口，按总览、全量目录、兼容矩阵与差异说明组织。'
---


---

---
url: /packages/weapi/compat-overview.md
description: '@wevu/api 三端 API 兼容报告总览，覆盖覆盖率、对齐结论与核心差异映射。'
---

# `@wevu/api` 兼容总览

本页展示 `@wevu/api` 当前三端 API 兼容报告的总览数据。

相关页面：

* [微信基准 API 全量清单](/packages/weapi/wx-method-list)
* [支付宝兼容矩阵](/packages/weapi/alipay-compat-matrix)
* [抖音兼容矩阵](/packages/weapi/douyin-compat-matrix)
* [兼容差异说明](/packages/weapi/gap-notes)
* [平台独有 API 清单](/packages/weapi/platform-only-methods)

# 01 Overview

## 覆盖结论

* 微信基准命名方法总数：481
* 支付宝可调用兼容方法数：201
* 支付宝语义对齐方法数：201
* 支付宝 fallback 方法数：0
* 抖音可调用兼容方法数：133
* 抖音语义对齐方法数：133
* 抖音 fallback 方法数：0
* 三端可调用完全对齐方法数：117
* 三端语义完全对齐方法数：117
* 三端命名交集方法数（wx∩my∩tt）：112
* 三端命名交集可调用完全对齐方法数：112
* 三端命名交集可调用覆盖率：100.00%
* 三端命名交集语义完全对齐方法数：112
* 三端命名交集语义对齐覆盖率：100.00%

## 不兼容规模

* 支付宝侧不兼容（按微信命名调用失败）方法：280
* 抖音侧不兼容（按微信命名调用失败）方法：348

## 不兼容示例（前 40 项）

### 支付宝不兼容示例

* `addCard` -> 目标 `addCard`（unsupported）
* `addFileToFavorites` -> 目标 `addFileToFavorites`（unsupported）
* `addPaymentPassFinish` -> 目标 `addPaymentPassFinish`（unsupported）
* `addPaymentPassGetCertificateData` -> 目标 `addPaymentPassGetCertificateData`（unsupported）
* `addPhoneCalendar` -> 目标 `addPhoneCalendar`（unsupported）
* `addPhoneRepeatCalendar` -> 目标 `addPhoneRepeatCalendar`（unsupported）
* `addVideoToFavorites` -> 目标 `addVideoToFavorites`（unsupported）
* `authorize` -> 目标 `authorize`（unsupported）
* `authorizeForMiniProgram` -> 目标 `authorizeForMiniProgram`（unsupported）
* `authPrivateMessage` -> 目标 `authPrivateMessage`（unsupported）
* `batchGetStorage` -> 目标 `batchGetStorage`（unsupported）
* `batchGetStorageSync` -> 目标 `batchGetStorageSync`（unsupported）
* `batchSetStorage` -> 目标 `batchSetStorage`（unsupported）
* `batchSetStorageSync` -> 目标 `batchSetStorageSync`（unsupported）
* `bindEmployeeRelation` -> 目标 `bindEmployeeRelation`（unsupported）
* `canAddSecureElementPass` -> 目标 `canAddSecureElementPass`（unsupported）
* `cancelIdleCallback` -> 目标 `cancelIdleCallback`（unsupported）
* `canvasGetImageData` -> 目标 `canvasGetImageData`（unsupported）
* `canvasPutImageData` -> 目标 `canvasPutImageData`（unsupported）
* `checkDeviceSupportHevc` -> 目标 `checkDeviceSupportHevc`（unsupported）
* `checkEmployeeRelation` -> 目标 `checkEmployeeRelation`（unsupported）
* `checkIsAddedToMyMiniProgram` -> 目标 `checkIsAddedToMyMiniProgram`（unsupported）
* `checkIsOpenAccessibility` -> 目标 `checkIsOpenAccessibility`（unsupported）
* `checkIsPictureInPictureActive` -> 目标 `checkIsPictureInPictureActive`（unsupported）
* `checkSession` -> 目标 `checkSession`（unsupported）
* `chooseAddress` -> 目标 `chooseAddress`（unsupported）
* `chooseInvoice` -> 目标 `chooseInvoice`（unsupported）
* `chooseInvoiceTitle` -> 目标 `chooseInvoiceTitle`（unsupported）
* `chooseLicensePlate` -> 目标 `chooseLicensePlate`（unsupported）
* `chooseMedia` -> 目标 `chooseMedia`（unsupported）
* `chooseMessageFile` -> 目标 `chooseMessageFile`（unsupported）
* `choosePoi` -> 目标 `choosePoi`（unsupported）
* `compressVideo` -> 目标 `compressVideo`（unsupported）
* `createAudioContext` -> 目标 `createAudioContext`（unsupported）
* `createBLEPeripheralServer` -> 目标 `createBLEPeripheralServer`（unsupported）
* `createBufferURL` -> 目标 `createBufferURL`（unsupported）
* `createCacheManager` -> 目标 `createCacheManager`（unsupported）
* `createCameraContext` -> 目标 `createCameraContext`（unsupported）
* `createGlobalPayment` -> 目标 `createGlobalPayment`（unsupported）
* `createInferenceSession` -> 目标 `createInferenceSession`（unsupported）

### 抖音不兼容示例

* `addCard` -> 目标 `addCard`（unsupported）
* `addFileToFavorites` -> 目标 `addFileToFavorites`（unsupported）
* `addPaymentPassFinish` -> 目标 `addPaymentPassFinish`（unsupported）
* `addPaymentPassGetCertificateData` -> 目标 `addPaymentPassGetCertificateData`（unsupported）
* `addPhoneCalendar` -> 目标 `addPhoneCalendar`（unsupported）
* `addPhoneContact` -> 目标 `addPhoneContact`（unsupported）
* `addPhoneRepeatCalendar` -> 目标 `addPhoneRepeatCalendar`（unsupported）
* `addVideoToFavorites` -> 目标 `addVideoToFavorites`（unsupported）
* `authorizeForMiniProgram` -> 目标 `authorizeForMiniProgram`（unsupported）
* `authPrivateMessage` -> 目标 `authPrivateMessage`（unsupported）
* `batchGetStorage` -> 目标 `batchGetStorage`（unsupported）
* `batchGetStorageSync` -> 目标 `batchGetStorageSync`（unsupported）
* `batchSetStorage` -> 目标 `batchSetStorage`（unsupported）
* `batchSetStorageSync` -> 目标 `batchSetStorageSync`（unsupported）
* `bindEmployeeRelation` -> 目标 `bindEmployeeRelation`（unsupported）
* `canAddSecureElementPass` -> 目标 `canAddSecureElementPass`（unsupported）
* `cancelIdleCallback` -> 目标 `cancelIdleCallback`（unsupported）
* `canvasGetImageData` -> 目标 `canvasGetImageData`（unsupported）
* `canvasPutImageData` -> 目标 `canvasPutImageData`（unsupported）
* `checkDeviceSupportHevc` -> 目标 `checkDeviceSupportHevc`（unsupported）
* `checkEmployeeRelation` -> 目标 `checkEmployeeRelation`（unsupported）
* `checkIsAddedToMyMiniProgram` -> 目标 `checkIsAddedToMyMiniProgram`（unsupported）
* `checkIsOpenAccessibility` -> 目标 `checkIsOpenAccessibility`（unsupported）
* `checkIsPictureInPictureActive` -> 目标 `checkIsPictureInPictureActive`（unsupported）
* `checkIsSoterEnrolledInDevice` -> 目标 `checkIsSoterEnrolledInDevice`（unsupported）
* `checkIsSupportSoterAuthentication` -> 目标 `checkIsSupportSoterAuthentication`（unsupported）
* `chooseContact` -> 目标 `chooseContact`（unsupported）
* `chooseInvoice` -> 目标 `chooseInvoice`（unsupported）
* `chooseInvoiceTitle` -> 目标 `chooseInvoiceTitle`（unsupported）
* `chooseLicensePlate` -> 目标 `chooseLicensePlate`（unsupported）
* `chooseMessageFile` -> 目标 `chooseMessageFile`（unsupported）
* `choosePoi` -> 目标 `choosePoi`（unsupported）
* `chooseVideo` -> 目标 `chooseVideo`（unsupported）
* `closeBLEConnection` -> 目标 `closeBLEConnection`（unsupported）
* `closeBluetoothAdapter` -> 目标 `closeBluetoothAdapter`（unsupported）
* `closeSocket` -> 目标 `closeSocket`（unsupported）
* `compressVideo` -> 目标 `compressVideo`（unsupported）
* `connectWifi` -> 目标 `connectWifi`（unsupported）
* `createAudioContext` -> 目标 `createAudioContext`（unsupported）
* `createBLEConnection` -> 目标 `createBLEConnection`（unsupported）

---

---
url: /packages/wevu-compiler.md
description: '@wevu/compiler 是 Wevu 的编译能力底座，提供 Vue SFC 与小程序模板的解析、转换和输出能力。'
---

# @wevu/compiler

`@wevu/compiler` 是 Wevu 的编译能力底座，提供 Vue SFC 与小程序模板的解析、转换和输出能力。

## 何时使用

* 你要在非 Vite 场景复用 Wevu 编译链路
* 你要独立处理 SFC 的 script/template/style/config
* 你要在构建阶段做页面特性分析与注入

## 安装

```bash
pnpm add @wevu/compiler
```

## 最小示例：编译 SFC

```ts
import { compileSfc } from '@wevu/compiler'

const result = await compileSfc(sourceCode, 'pages/index/index.vue', {
  isPage: true,
  json: { kind: 'page' },
})

console.log(result.script)
console.log(result.template)
console.log(result.style)
```

## 常用导出

* `compileSfc` / `compileVueFile`
* `compileTemplate` / `compileStyle`
* `collectWevuPageFeatureFlags`
* `injectWevuPageFeaturesInJs`

## 与 Weapp-vite 的关系

`weapp-vite` 在上层整合构建流程，`@wevu/compiler` 提供底层编译能力。若你只是常规业务开发，优先看 [Weapp-vite 指引](/guide/)。

---

---
url: /guide/directory-structure/src-root.md
description: Weapp-vite 的源码根目录概念，所有 pages、components、分包、自动生成类型文件都基于它定位。
---

# `<srcRoot>/`

`<srcRoot>/` 是这组目录文档里最重要的概念。
`weapp-vite` 真正依赖的是 `weapp.srcRoot`，不是某个固定叫 `src/` 的文件夹。

## 默认值

大多数模板会把它设成：

```ts
export default defineConfig({
  weapp: {
    srcRoot: 'src',
  },
})
```

但你也可以改成：

```ts
export default defineConfig({
  weapp: {
    srcRoot: 'miniprogram',
  },
})
```

## 它会影响什么

* `pages/` 的扫描根目录
* `components/` 的扫描根目录
* `custom-tab-bar/`、`app-bar/` 的固定位置
* `typed-router.d.ts`、`typed-components.d.ts`、`components.d.ts` 的默认输出位置

## 一个简单判断

如果某条文档写的是 `<srcRoot>/pages/**`，你应该先自动在脑中把它理解为：

`<srcRoot>/pages/**`

---

---
url: /guide/directory-structure/subpackages.md
description: 分包目录与分包 root 的关系说明，weapp.subPackages 才是分包边界的权威配置。
---

# `<subPackageRoot>/`

`weapp-vite` 不要求分包必须叫 `packages/` 或 `subpackages/`。
真正决定“这是不是分包”的，是你是否把该目录声明到 `weapp.subPackages`。

## 推荐配置

```ts
export default defineConfig({
  weapp: {
    subPackages: {
      'packageA': {},
      'subpackages/marketing': {
        independent: true,
      },
    },
  },
})
```

## 对应目录

```text
<srcRoot>/
  <subPackageRoot>/
    pages/
    components/
  subpackages/
    marketing/
      pages/
      components/
```

## 默认行为

* `<srcRoot>/<subPackageRoot>/pages/**` 会被识别为分包页面
* `<srcRoot>/<subPackageRoot>/components/**` 会被识别为分包组件
* 页面会进入自动路由的 `subPackages` 结果

如果你只建目录，不声明 `weapp.subPackages`，那它就不是稳定的分包边界。

---

---
url: /guide/ai.md
description: 面向 weapp-vite 团队的 AI 协作入口，聚焦 Skills、MCP 与 llms.txt 三大章节。
---

# AI 协作指南

## Skills

`Skills` 负责给 AI 注入稳定的工程流程，减少“回答看起来对、执行却跑偏”的情况。

这里分两层理解：

1. `skills/*`：公开分发给用户的通用技能，适合安装到自己的 Codex / Claude 环境。
2. `.claude/skills/*`：这个项目仓库内附带的本地附加技能，通常跟本仓库工作流或本地工具链强绑定。

如果你是直接使用公开技能仓库，先安装：

```bash
npx skills add sonofmagic/skills
```

如果你正在这个 monorepo 里开发，优先把仓库自带技能链接到本地环境：

```bash
pnpm skills:link
```

只想预览链接结果而不改本地环境时：

```bash
pnpm skills:link:dry
```

公开 skills（`skills/*`）里当前常用的有：

```text
$weapp-vite-best-practices
$docs-and-website-sync
$github-issue-fix-workflow
$release-and-changeset-best-practices
$weapp-devtools-e2e-best-practices
$weapp-vite-wevu-performance-best-practices
$weapp-vite-vue-sfc-best-practices
$wevu-best-practices
$native-to-weapp-vite-wevu-migration
$weapp-ide-cli-best-practices
```

项目本地附加 skills（当前位于 `.claude/skills/*`）按需通过 `pnpm skills:link` 一起同步。

当前仓库内的本地附加 skill 示例：

```text
$playwright-cli
```

建议：

1. 面向用户公开分发的流程优先沉淀到 `skills/*`。
2. 仅对本仓库有效、依赖本地工具链或本地 agent 能力的内容，更适合放到 `.claude/skills/*`。
3. 项目架构、分包、构建编排问题优先用 `weapp-vite-best-practices`。
4. 根据现有代码同步 `website`、`skills`、AI 指南时优先用 `docs-and-website-sync`。
5. GitHub issue 修复、`e2e-apps/github-issues` 复现、PR 闭环优先用 `github-issue-fix-workflow`。
6. changeset、发布、`create-weapp-vite` 联动和提交规范优先用 `release-and-changeset-best-practices`。
7. WeChat DevTools runtime e2e、automator 复用、`reLaunch` 方案优先用 `weapp-devtools-e2e-best-practices`。
8. 卡顿、掉帧、白屏、内存告警优先用 `weapp-vite-wevu-performance-best-practices`。
9. `.vue` 宏、模板兼容、`v-model`/`usingComponents` 问题优先用 `weapp-vite-vue-sfc-best-practices`。
10. `wevu` 生命周期、状态、事件、store 问题优先用 `wevu-best-practices`。
11. 原生小程序迁移到 `weapp-vite + wevu + Vue SFC` 优先用 `native-to-weapp-vite-wevu-migration`。
12. DevTools 自动化、`preview/upload/automator/config` 命令治理优先用 `weapp-ide-cli-best-practices`。
13. 先让 AI 明确使用哪个 Skill，再开始具体任务。

## MCP

`MCP` 负责把仓库真实能力暴露给 AI（读代码、搜代码、执行受限命令、调用 weapp-vite CLI）。

默认行为：

1. `weapp-vite` 默认启用 MCP 能力。
2. 默认不会自动启动 MCP 服务（`autoStart: false`）。

手动启动（推荐）：

```bash
weapp-vite mcp
```

需要 HTTP 连接时：

```bash
weapp-vite mcp --transport streamable-http --host 127.0.0.1 --port 3088 --endpoint /mcp
```

可选：不在仓库目录执行时，再加 `--workspace-root /path/to/weapp-vite`。

### 示例：驱动 weapp-vite screenshot 做验收

前置条件：

1. AI 客户端已接入 `weapp-vite` MCP。
2. 微信开发者工具已登录，并开启「设置 -> 安全设置 -> 服务端口」。

可直接复制的提示词：

```text
你现在连接的是 weapp-vite MCP。请帮我完成一次小程序截图验收：
1. 构建 e2e-apps/auto-routes-define-app-json（platform=weapp）。
2. 执行 weapp-vite screenshot，参数如下：
   - project: e2e-apps/auto-routes-define-app-json/dist/build/mp-weixin
   - page: pages/home/index
   - output: .tmp/mcp-screenshot.png
   - 使用 --json 返回结果
3. 检查 .tmp/mcp-screenshot.png 是否存在：
   - 存在输出 screenshot-ok
   - 不存在输出 screenshot-missing
4. 最后汇总：执行命令、关键输出、最终结论。
```

期望结果：

1. AI 输出 `screenshot-ok`。
2. 工作区产出 `.tmp/mcp-screenshot.png`。

## llms.txt

`llms.txt` 负责给模型稳定喂上下文，减少遗漏与误判。

可用资源：

1. `/llms.txt`：轻量索引。
2. `/llms-full.txt`：完整语料。
3. `/llms-index.json`：结构化索引。

推荐喂给顺序：

1. 先 `/llms.txt` 建立目录语义。
2. 再按需读取 `/llms-full.txt`。
3. 最后结合 `/llms-index.json` 做结构化定位。

## 关联阅读

1. [CLI 命令参考](/guide/cli)
2. [共享配置：weapp.mcp](/config/shared#weapp-mcp)
3. [@weapp-vite/mcp 包说明](/packages/mcp)
4. [AI 学习入口](/ai)

---

---
url: /ai.md
description: 统一的 AI 学习入口，聚合 llms 语料、MCP 接入与 Weapp-vite / Wevu 技能安装方式。
---


---

---
url: /packages/rolldown-require/options.md
description: >-
  rolldown-require exposes three APIs: bundleRequire, bundleFile, and
  loadFromBundledFile. Prefer the one-stop bundleRequ…
---

# API & options

> Language: English | [中文](/packages/rolldown-require/options.zh)

`rolldown-require` exposes three APIs: `bundleRequire`, `bundleFile`, and `loadFromBundledFile`. Prefer the one-stop `bundleRequire`, which resolves the entry, bundles with rolldown, writes the temp output, loads it, and returns:

* `mod`: the executed module (automatically unwraps `default` if present)
* `dependencies`: the file paths touched during bundling

## Common options

### filepath / cwd

* `filepath` is required and accepts relative or absolute paths.
* `cwd` defaults to `process.cwd()` for resolving the relative entry and `tsconfig`.

### format

* If omitted, format is inferred from extension and `package.json.type` (`.mjs`/`.mts`/`type:module` -> `esm`, `.cjs`/`.cts` -> `cjs`).
* Pass `cjs`/`esm` to skip inference, e.g. force ESM for `.js`.

### require

Customize how the temp output is loaded: `(outfile, { format }) => any`.

* ESM: `import(outfile)` (temp file or data URL is written during bundling)
* CJS: compiles the source via a temporary `_require.extensions` hook

Use this to plug in your own loader, add custom `import` logic for ESM output, or inject mocks in tests.

### rolldownOptions

Pass through parts of rolldown options:

* `input`: add plugins, `resolve` rules, transforms, etc. Internally `platform: 'node'` and `treeshake: false` are fixed, and `define` injects `__dirname`/`__filename`/`import.meta.url`.
* `output`: merged with defaults; `format` is overridden by the `format` option, `inlineDynamicImports` is always `true`.

> Avoid overriding `platform`, `input`, or `inlineDynamicImports`, otherwise resolution/dependency collection may break.

### external

Forwarded to rolldown. The plugin already externalizes most `node_modules` deps while keeping JSON inlined; use this option to exclude or force-inline specific deps.

### tsconfig

* Auto-searches upward for `tsconfig.json` and reads `paths` for alias resolution during bundling.
* Pass a string to set the path explicitly; pass `false` to disable tsconfig handling.

### getOutputFile

Customize where the temp output is written (defaults to `node_modules/.rolldown-require` or the system temp dir with a random suffix). Handy for writing to a debuggable location.

### preserveTemporaryFile

Temp files are cleaned after CJS load or ESM import by default. Set to `true` (or `BUNDLE_REQUIRE_PRESERVE`) to keep them for inspection.

### cache

Disabled when `false`/unset. Pass `true` or an object to enable persistent + memory cache; see [Loading flow & cache](/packages/rolldown-require/cache) for details.

## Example configuration

```ts
import { bundleRequire } from 'rolldown-require'

const { mod } = await bundleRequire({
  cwd: process.cwd(),
  filepath: './tooling/config.ts',
  format: 'esm',
  tsconfig: './tsconfig.node.json',
  external: ['fsevents'],
  cache: {
    enabled: true,
    dir: './node_modules/.rolldown-require-cache',
    onEvent: e => console.log('[rolldown-require cache]', e),
  },
  rolldownOptions: {
    input: {
      plugins: [
        myCustomPlugin(),
      ],
    },
  },
})
```

This setup will:

1. Bundle `tooling/config.ts` as ESM using the specified `tsconfig`.
2. Mark `fsevents` as external while keeping the default externalization behaviour for others.
3. Cache the temp output in the given directory and emit cache events via `onEvent`.

---

---
url: /packages/rolldown-require/options.zh.md
description: >-
  rolldown-require 暴露了 bundleRequire / bundleFile / loadFromBundledFile 三个
  API，但推荐优先使用一站式的 bundleRequire。它会完成入口解析、rolldow…
---

# API 与选项说明

> 语言： [English](/packages/rolldown-require/options) | 中文

`rolldown-require` 暴露了 `bundleRequire` / `bundleFile` / `loadFromBundledFile` 三个 API，但推荐优先使用一站式的 `bundleRequire`。它会完成入口解析、rolldown 打包、临时产物生成与最终加载，并返回：

* `mod`: 已执行的模块（若存在 `default`，会自动返回 `default`）
* `dependencies`: 打包阶段命中的文件路径列表

## 常用选项

### filepath / cwd

* `filepath` 必填，支持相对路径或绝对路径。
* `cwd` 默认使用 `process.cwd()`，用于解析相对入口和 `tsconfig`。

### format

* 不传则自动根据后缀与 `package.json.type` 推断（`.mjs`/`.mts`/`type:module` -> `esm`，`.cjs`/`.cts` -> `cjs`）。
* 手动传入 `cjs`/`esm` 可跳过推断，例如希望强制以 ESM 方式加载 `.js`。

### require

自定义产物的加载方式，签名为 `(outfile, { format }) => any`。默认行为：

* ESM：`import(outfile)`（在打包时会写入临时文件或 data: URL）
* CJS：通过 `_require.extensions` 临时钩子编译并 `require` 源文件

典型用途：接入你自己的 loader、为 ESM 产物追加自定义 `import` 逻辑，或在测试环境中注入 mock。

### rolldownOptions

允许透传部分 rolldown 选项：

* `input`: 可加入自定义插件、`resolve` 规则、`transform` 等。内部会固定 `platform: 'node'`、`treeshake: false`，并注入 `define` 保持 `__dirname`/`__filename`/`import.meta.url`。
* `output`: 会与内部默认项合并，但 `format` 会被 `format` 选项覆盖，`inlineDynamicImports` 固定为 `true`。

> 避免覆写 `platform`、`input` 或 `inlineDynamicImports`，否则可能导致运行时与依赖收集异常。

### external

传递给 rolldown 的 `external` 配置。插件会自动外部化大部分 `node_modules` 依赖并保留 JSON 内联；通过该选项可进一步排除或强制内联特定依赖。

### tsconfig

* 默认自动向上查找 `tsconfig.json` 并读取 `paths`，让打包阶段能解析别名。
* 传入字符串可指定路径；传入 `false` 可禁用 `tsconfig` 解析。

### getOutputFile

自定义临时产物的落盘路径（默认生成到 `node_modules/.rolldown-require` 或系统临时目录，并带随机后缀）。可用于将产物写入更易调试的位置。

### preserveTemporaryFile

默认会在 CJS 加载完成或 ESM 加载后清理临时文件。将其设为 `true`（或设置环境变量 `BUNDLE_REQUIRE_PRESERVE`）可保留产物，便于问题排查。

### cache

`false`/未设置时关闭缓存。传入 `true` 或配置对象可以打开持久化 + 内存缓存，详见 [加载流程与缓存策略](/packages/rolldown-require/cache.zh)。

## 组合示例

```ts
import { bundleRequire } from 'rolldown-require'

const { mod } = await bundleRequire({
  cwd: process.cwd(),
  filepath: './tooling/config.ts',
  format: 'esm',
  tsconfig: './tsconfig.node.json',
  external: ['fsevents'],
  cache: {
    enabled: true,
    dir: './node_modules/.rolldown-require-cache',
    onEvent: e => console.log('[rolldown-require cache]', e),
  },
  rolldownOptions: {
    input: {
      plugins: [
        myCustomPlugin(),
      ],
    },
  },
})
```

上述配置会：

1. 强制以 ESM 格式打包 `tooling/config.ts` 并使用指定的 `tsconfig` 解析路径。
2. 将 `fsevents` 标记为外部依赖，其余依赖遵循默认外部化策略。
3. 把临时产物缓存到指定目录，并通过 `onEvent` 输出命中/失效信息。

---

---
url: /packages/weapi/wx-method-list.md
description: '@wevu/api 基于微信命名体系的全量 API 目录，包含每个 API 的用途、示例与微信开放文档搜索入口。'
---

# API 全量清单

本页按微信开放文档的能力域来组织 `@wevu/api` 当前收录的完整 API 目录。

能力域入口：

* [基础](/packages/weapi/wx-method-list/base)
* [路由](/packages/weapi/wx-method-list/route)
* [跳转](/packages/weapi/wx-method-list/navigate)
* [聊天工具](/packages/weapi/wx-method-list/chattool)
* [转发](/packages/weapi/wx-method-list/share)
* [界面](/packages/weapi/wx-method-list/ui)
* [网络](/packages/weapi/wx-method-list/network)
* [支付](/packages/weapi/wx-method-list/payment)
* [数据缓存](/packages/weapi/wx-method-list/storage)
* [数据分析](/packages/weapi/wx-method-list/data-analysis)
* [画布](/packages/weapi/wx-method-list/canvas)
* [媒体](/packages/weapi/wx-method-list/media)
* [位置](/packages/weapi/wx-method-list/location)
* [文件](/packages/weapi/wx-method-list/file)
* [开放接口](/packages/weapi/wx-method-list/open-api)
* [设备](/packages/weapi/wx-method-list/device)
* [AI](/packages/weapi/wx-method-list/ai)
* [Worker](/packages/weapi/wx-method-list/worker)
* [WXML](/packages/weapi/wx-method-list/wxml)
* [第三方平台](/packages/weapi/wx-method-list/ext)
* [广告](/packages/weapi/wx-method-list/ad)
* [XR-FRAME](/packages/weapi/wx-method-list/xr-frame)

每个能力域下都保留：

* API 是什么
* 一段最小用法示例
* 微信开放文档搜索入口
* 微信 / 支付宝 / 抖音三端的当前策略

---

---
url: /packages/weapi/wx-method-list/ai.md
description: '@wevu/api API 全量清单中的 AI 能力。'
---

# API 全量清单 · AI

---

---
url: /packages/weapi/wx-method-list/worker.md
description: '@wevu/api API 全量清单中的 Worker 能力。'
---

# API 全量清单 · Worker

---

---
url: /packages/weapi/wx-method-list/wxml.md
description: '@wevu/api API 全量清单中的 WXML 能力。'
---

# API 全量清单 · WXML

---

---
url: /packages/weapi/wx-method-list/xr-frame.md
description: '@wevu/api API 全量清单中的 XR-FRAME 能力。'
---

# API 全量清单 · XR-FRAME

---

---
url: /packages/weapi/wx-method-list/location.md
description: '@wevu/api API 全量清单中的位置能力。'
---

# API 全量清单 · 位置

---

---
url: /packages/weapi/wx-method-list/base.md
description: '@wevu/api API 全量清单中的基础能力。'
---

# API 全量清单 · 基础

---

---
url: /packages/weapi/wx-method-list/media.md
description: '@wevu/api API 全量清单中的媒体能力。'
---

# API 全量清单 · 媒体

---

---
url: /packages/weapi/wx-method-list/ad.md
description: '@wevu/api API 全量清单中的广告能力。'
---

# API 全量清单 · 广告

---

---
url: /packages/weapi/wx-method-list/open-api.md
description: '@wevu/api API 全量清单中的开放接口能力。'
---

# API 全量清单 · 开放接口

---

---
url: /packages/weapi/wx-method-list/payment.md
description: '@wevu/api API 全量清单中的支付能力。'
---

# API 全量清单 · 支付

---

---
url: /packages/weapi/wx-method-list/data-analysis.md
description: '@wevu/api API 全量清单中的数据分析能力。'
---

# API 全量清单 · 数据分析

---

---
url: /packages/weapi/wx-method-list/storage.md
description: '@wevu/api API 全量清单中的数据缓存能力。'
---

# API 全量清单 · 数据缓存

---

---
url: /packages/weapi/wx-method-list/file.md
description: '@wevu/api API 全量清单中的文件能力。'
---

# API 全量清单 · 文件

---

---
url: /packages/weapi/wx-method-list/canvas.md
description: '@wevu/api API 全量清单中的画布能力。'
---

# API 全量清单 · 画布

---

---
url: /packages/weapi/wx-method-list/ui.md
description: '@wevu/api API 全量清单中的界面能力。'
---

# API 全量清单 · 界面

---

---
url: /packages/weapi/wx-method-list/ext.md
description: '@wevu/api API 全量清单中的第三方平台能力。'
---

# API 全量清单 · 第三方平台

---

---
url: /packages/weapi/wx-method-list/network.md
description: '@wevu/api API 全量清单中的网络能力。'
---

# API 全量清单 · 网络

---

---
url: /packages/weapi/wx-method-list/chattool.md
description: '@wevu/api API 全量清单中的聊天工具能力。'
---

# API 全量清单 · 聊天工具

---

---
url: /packages/weapi/wx-method-list/device.md
description: '@wevu/api API 全量清单中的设备能力。'
---

# API 全量清单 · 设备

---

---
url: /packages/weapi/wx-method-list/route.md
description: '@wevu/api API 全量清单中的路由能力。'
---

# API 全量清单 · 路由

---

---
url: /packages/weapi/wx-method-list/navigate.md
description: '@wevu/api API 全量清单中的跳转能力。'
---

# API 全量清单 · 跳转

---

---
url: /packages/weapi/wx-method-list/share.md
description: '@wevu/api API 全量清单中的转发能力。'
---

# API 全量清单 · 转发

---

---
url: /wevu/api-reference.md
description: Wevu API 参考首页。按 Vue API 风格提供分组导航，先定位能力域，再跳转到对应 API 分页。
---

# Wevu API 参考

本页参考了 Vue 官方 API 导航方式：先按能力域分组，再进入具体条目。

## 全局 API

### 入口与应用

* [Core API（入口、组件、宏）](/wevu/api/core.html)
  * `defineComponent` / `createApp` / `defineProps` / `defineEmits` / `defineModel`

### 通用调度

* [Reactivity API（响应式与调度）](/wevu/api/reactivity.html)
  * `ref` / `reactive` / `computed` / `watch` / `nextTick`

## 组合式 API

### 生命周期

* [Lifecycle API（生命周期）](/wevu/api/lifecycle.html)
  * `onLoad` / `onShow` / `onReady` / `onUnload`

### setup 上下文

* [Setup Context API（setup 上下文）](/wevu/api/setup-context.html)
  * `ctx.emit` / `useBindModel` / `useIntersectionObserver` / `getCurrentInstance` / `provide` / `inject`

### 状态管理

* [Store API（状态管理）](/wevu/api/store.html)
  * `defineStore` / `createStore` / `storeToRefs`

## 进阶 API

### 运行时桥接

* [Runtime Bridge API（桥接与调试）](/wevu/api/runtime-bridge.html)
  * 小程序实例桥接、`setData` 策略、调试与性能开关

### 类型与工具

* [Type Reference（类型总览）](/wevu/api/types.html)
  * 核心类型、上下文类型、Store 类型、桥接类型

## 子路径导出

这些页面不属于 `wevu` 主入口的“逐函数分组 API”，但它们同样是 Wevu 当前公开的 namespace 导出：

* [wevu/api](/wevu/api-package)
  * 透传 `@wevu/api`，用于统一多端小程序 API 调用
* [wevu/fetch](/wevu/fetch)
  * 基于 `wpi.request` 的 Fetch 风格接口
* [wevu/router](/wevu/router)
  * 路径式导航、守卫、失败分类与调试能力
* [wevu/jsx-runtime](/wevu/jsx-runtime)
  * TSX / JSX 类型入口

## 建议阅读路径

1. 先读 `Core`，建立 Wevu 的组件与宏心智。
2. 再读 `Reactivity` + `Lifecycle`，形成页面更新与生命周期调度模型。
3. 业务接入 `Setup Context` + `Store`。
4. 需要排障或优化时再进入 `Runtime Bridge` 与 `Type Reference`。

## 使用约定

* 业务代码统一从 `wevu` 主入口导入。
* `wevu/compiler` 主要用于编译工具链，不建议在业务运行时代码中直接依赖。
* `wevu` 请安装在 `devDependencies` 中，而不是 `dependencies`。
* 本目录是“按场景组织”的人工参考；精确签名、泛型和重载以对应 API 分页为准。

---

---
url: /guide/directory-structure/app-bar.md
description: Skyline 全局工具栏的固定保留目录，与 appBar 配置一一对应。
---

# `app-bar/`

这是 Skyline 全局工具栏的固定目录。

## 触发条件

当 `app.json` 中声明了 `appBar` 配置时，`weapp-vite` 会把 `app-bar/index` 当成固定入口。

## 位置要求

* 目录名必须是 `app-bar`
* 必须和 `app.json` 处于同一个 `srcRoot` 下

## 它和普通页面的区别

* 不参与自动路由扫描
* 不应放进 `pages/`
* 语义来自平台配置，而不是约定式页面目录

---

---
url: /guide/directory-structure/app-style.md
description: 应用级全局样式入口，支持 CSS、WXSS 与常见预处理器后缀。
---

# `app.(css|scss|wxss|...)`

`app.(css|scss|wxss|...)` 是全局样式入口。

## 常见后缀

* `app.css`
* `app.wxss`
* `app.scss`
* `app.less`
* `app.sass`
* `app.styl`

## 常见用途

* reset
* 主题变量
* 公共样式 token
* tabBar、navigation 相关样式

它不是必须文件，但大多数项目值得保留一个全局样式入口。
如果你使用的是 `app.vue`，也可以通过 `<style>` 或 `src="./app.css"` 的方式把它并入 SFC 入口。

---

---
url: /guide/directory-structure/app-ts.md
description: 应用脚本入口，支持 JavaScript 与 TypeScript，承载 App 生命周期和全局初始化逻辑。
---

# `app.(js|ts)`

`app.(js|ts)` 是应用脚本入口。

## 适合放什么

* App 生命周期
* 全局启动逻辑
* 埋点初始化
* 和 `wevu`、router、全局状态相关的初始化

## 支持哪些后缀

* `app.js`
* `app.ts`

如果你项目使用的是原生小程序增强模式，这通常就是应用逻辑的主入口。

## 它和页面目录的关系

它不参与自动路由扫描，但它通常是全局行为的起点。
目录结构上，它与 `app.json(.js|.ts)?`、`app.(css|scss|wxss|...)` 一起构成应用入口三件套。

---

---
url: /guide/directory-structure/app-json.md
description: 应用配置入口，既支持原生 JSON，也支持 app.json.js 和 app.json.ts 这类脚本化形式。
---

# `app.json(.js|.ts)?`

`app.json(.js|.ts)?` 是小程序应用配置入口。

## 支持哪些形式

* `app.json`
* `app.json.js`
* `app.json.ts`

## 它通常负责

* `pages`
* `subPackages`
* `tabBar`
* `appBar`
* 全局窗口配置

## 和目录结构的关键关系

* `tabBar.custom === true` 时，会启用 [`custom-tab-bar/`](/guide/directory-structure/custom-tab-bar)
* 配置了 `appBar` 时，会启用 [`app-bar/`](/guide/directory-structure/app-bar)
* 如果你开启了自动路由，可以通过脚本方式把扫描结果写回这里

## 什么时候用脚本化形式

如果你的配置需要消费变量、函数结果或自动路由数据，`app.json.ts` / `app.json.js` 会比纯 JSON 更合适。

```ts
import autoRoutes from 'weapp-vite/auto-routes'
import { defineAppJson } from 'weapp-vite/json'

export default defineAppJson({
  pages: autoRoutes.pages,
  subPackages: autoRoutes.subPackages,
})
```

---

---
url: /guide/directory-structure/app-vue.md
description: Vue SFC 形式的应用入口，可在一个文件中组织脚本、defineAppJson 宏与样式。
---

# `app.vue`

`app.vue` 是 Weapp-vite + Vue SFC 场景下非常常见的应用入口。

## 它适合解决什么

* 希望把应用脚本、应用配置和样式放在一个 SFC 中维护
* 想直接在顶层使用 `defineAppJson`
* 想在应用入口里直接创建 router、store 或其他全局运行时能力

## 典型写法

```vue
<script setup lang="ts">
import { defineAppJson } from 'weapp-vite/json'

defineAppJson({
  pages: ['pages/index/index'],
})
</script>

<style src="./app.css"></style>
```

## 它和 `app.(js|ts)` / `app.json(.js|.ts)?` / `app.(css|scss|wxss|...)` 的关系

可以把 `app.vue` 理解为一种“组合式入口”：

* 脚本逻辑在 `<script setup>` 或普通 `<script>` 中表达
* JSON 配置通过 `defineAppJson` 或 `<json>` 块表达
* 全局样式通过 `<style>` 或 `src="./app.css"` 这类方式表达

如果你已经使用 `app.vue`，很多场景下就不需要再单独维护 `app.ts`。

---

---
url: /wevu/vue-sfc/class-style.md
description: >-
  Weapp-vite + Wevu 在小程序侧对齐 Vue 3 的 :class / :style
  绑定语法，支持字符串、数组、对象与嵌套组合，并会输出小程序可识别的字符串 class/style。
---

# class/style 绑定能力

`weapp-vite + Wevu` 在小程序侧对齐 Vue 3 的 `:class` / `:style` 绑定语法，支持字符串、数组、对象与嵌套组合，并会输出小程序可识别的字符串 class/style。

```vue
<template>
  <view
    v-show="visible"
    class="card base"
    :class="[active && 'active', { highlight, disabled: !ok }, extra]"
    :style="[
      { color: themeColor, fontSize: `${size}px` },
      { '--gap': gap },
      inlineStyle,
    ]"
  />
</template>
```

## 运行时模式

`class/style` 的运行时有两种实现，默认使用 JS：

* **WXS 运行时**：编译产物中注入 `__weapp_vite.cls/style` helper（WXS 文件），模板中调用 `__weapp_vite.cls()` / `__weapp_vite.style()`。
* **JS 运行时**：编译期注入 `computed`，在逻辑层计算字符串 class/style。

配置项：

```ts
// weapp-vite.config.ts
export default defineConfig({
  weapp: {
    vue: {
      template: {
        classStyleRuntime: 'js', // 'auto' | 'wxs' | 'js'
        classStyleWxsShared: true, // 是否复用 WXS helper
      },
    },
  },
})
```

默认 `js` 会在逻辑层注入 `computed` 来计算 class/style 字符串。

若配置为 `auto`，会在平台支持 WXS（`weapp.wxs !== false` 且 `outputExtensions.wxs` 存在）时启用 WXS，否则回退到 JS。若手动指定 `wxs` 但平台不支持，会回退到 JS 并输出中文告警。

`classStyleWxsShared` 默认开启：主包与非独立分包共享一份 `__weapp_vite_class_style.wxs`，独立分包会各自生成一份。关闭后会按页面目录生成，方便手动控制拷贝或排查问题。

## 实现细节与限制

* **v-show 拼接**：`v-show` 会被拼接到 style（`display: none`），与 Vue 行为一致。
* **v-for 下 index 注入**：JS 运行时需要稳定索引，若模板未提供 `index`，编译器会自动注入 `wx:for-index="__wv_index_N"`。
* **对象 v-for**：JS 运行时会按 `Object.keys` 枚举顺序生成映射结果，确保索引与渲染一致。
* **表达式安全**：不使用 `eval/new Function/with`。表达式由编译器解析并重写标识符（包括作用域插槽 `__wvOwner` / `__wvSlotPropsData`），解析失败会输出中文告警并回退为空字符串。

> 建议：优先保持表达式为可解析的 JS/TS 表达式，避免非常规语法或依赖运行时动态生成的表达式字符串。

---

---
url: /guide/cli.md
description: Weapp-vite CLI 命令参考，包含全局参数、原生命令、别名、常用示例，以及 weapp-ide-cli 透传规则。
---

# CLI 命令参考

本文汇总 `weapp-vite` 在当前版本可用的命令与参数，优先覆盖日常开发最常用场景。

> 需要调用微信开发者工具能力（`preview/upload/automator/config` 等）时，`weapp-vite` 会在未命中自身命令后自动透传到 `weapp-ide-cli`。

## 命令格式

```bash
weapp-vite [全局参数] <command> [command options]
```

默认命令是 `dev`，也就是：

```bash
weapp-vite
```

等价于：

```bash
weapp-vite dev
```

## 全局参数

| 参数                     | 说明                                        |
| ------------------------ | ------------------------------------------- |
| `-c, --config <file>`    | 指定配置文件                                |
| `--base <path>`          | 公共基础路径（默认 `/`）                    |
| `-l, --logLevel <level>` | 日志级别：`info/warn/error/silent`          |
| `--clearScreen`          | 控制是否清屏输出                            |
| `-d, --debug [feat]`     | 启用调试日志（可选调试分组）                |
| `-f, --filter <filter>`  | 过滤调试日志                                |
| `-m, --mode <mode>`      | 运行模式（如 `development` / `production`） |

## 原生命令

### 1) `dev` / `serve`（默认命令）

用于本地开发与监听构建。

```bash
weapp-vite dev [root]
weapp-vite serve [root]
weapp-vite [root]
```

参数：

| 参数                        | 说明                                       |
| --------------------------- | ------------------------------------------ |
| `--skipNpm`                 | 跳过 npm 构建                              |
| `-o, --open`                | 构建后尝试打开 IDE                         |
| `-p, --platform <platform>` | 目标平台（`weapp` | `h5`）                |
| `--project-config <path>`   | 小程序 `project.config.json` 路径          |
| `--host [host]`             | Web dev server host（`h5` 场景）           |
| `--analyze`                 | 启动分包分析仪表盘（实验特性，小程序场景） |

### 2) `build`

用于生产构建（支持 watch）。

```bash
weapp-vite build [root]
```

参数：

| 参数                        | 说明                                           |
| --------------------------- | ---------------------------------------------- |
| `--target <target>`         | 构建目标（默认 `modules`）                     |
| `--outDir <dir>`            | 输出目录（默认 `dist`）                        |
| `-p, --platform <platform>` | 目标平台（`weapp` | `h5`）                    |
| `--project-config <path>`   | 小程序 `project.config.json` 路径              |
| `--sourcemap [output]`      | 产出 sourcemap（`true/inline/hidden`）         |
| `--minify [minifier]`       | 代码压缩开关或压缩器（`false/terser/esbuild`） |
| `--emptyOutDir`             | 当 outDir 在 root 外时强制清空                 |
| `-w, --watch`               | 监听并增量重建                                 |
| `--skipNpm`                 | 跳过 npm 构建                                  |
| `-o, --open`                | 构建后尝试打开 IDE                             |
| `--analyze`                 | 输出分包分析仪表盘（小程序场景）               |

### 3) `analyze`

分析小程序分包产物映射，或输出 Web 静态分析结果。

```bash
weapp-vite analyze [root]
```

参数：

| 参数                        | 说明                              |
| --------------------------- | --------------------------------- |
| `--json`                    | 输出 JSON 结果（stdout）          |
| `--output <file>`           | 将分析结果写入文件                |
| `-p, --platform <platform>` | 目标平台（`weapp` | `h5`）       |
| `--project-config <path>`   | 小程序 `project.config.json` 路径 |

### 4) `open`

打开 IDE（微信或支付宝场景由平台决定）。

```bash
weapp-vite open [root]
```

参数：

| 参数                        | 说明                                    |
| --------------------------- | --------------------------------------- |
| `-p, --platform <platform>` | 目标平台（`weapp` | `h5` | `alipay`） |

### 5) `npm`（含别名）

调用 IDE 的 npm 构建能力。

```bash
weapp-vite npm
weapp-vite build:npm
weapp-vite build-npm
```

### 6) `generate` / `g`

生成 app / page / component 文件骨架。

```bash
weapp-vite generate [filepath]
weapp-vite g [filepath]
```

参数：

| 参数                | 说明             |
| ------------------- | ---------------- |
| `-a, --app`         | 按 app 模板生成  |
| `-p, --page`        | 按 page 模板生成 |
| `-n, --name <name>` | 指定文件名       |

### 7) `init`

初始化项目配置。

```bash
weapp-vite init
```

### 8) `mcp`

启动 `weapp-vite` MCP 服务（用于 AI 助手接入）。

```bash
weapp-vite mcp
```

参数：

| 参数                      | 说明                                                   |
| ------------------------- | ------------------------------------------------------ |
| `--transport <type>`      | 传输类型：`stdio` | `streamable-http`（默认 `stdio`） |
| `--host <host>`           | HTTP 模式监听地址                                      |
| `--port <port>`           | HTTP 模式端口                                          |
| `--endpoint <path>`       | HTTP 模式 endpoint（默认 `/mcp`）                      |
| `--unref`                 | HTTP 模式下 `unref` server（不阻塞进程退出）           |
| `--workspace-root <path>` | 指定 workspace 根目录（默认从当前目录自动向上定位）    |

示例：

```bash
weapp-vite mcp
weapp-vite mcp --transport streamable-http --host 127.0.0.1 --port 3088 --endpoint /mcp
```

不在仓库目录执行时，可选追加 `--workspace-root /path/to/weapp-vite`。

## `weapp-ide-cli` 透传规则

当你输入的命令不是 `weapp-vite` 原生命令时，CLI 会判断是否属于 `weapp-ide-cli` 顶层命令。若命中，则直接透传执行。

`weapp-vite` 内建命令优先级更高（不会被透传覆盖）：

* `dev`
* `serve`
* `build`
* `analyze`
* `init`
* `open`
* `npm`
* `build:npm`
* `build-npm`
* `generate`
* `g`
* `mcp`

你也可以显式使用命名空间透传：

```bash
weapp-vite ide preview --project ./dist -q terminal
weapp-vite ide upload --project ./dist -v 1.0.0 -d "ci upload"
```

完整 IDE 命令列表请参考：

* [/packages/weapp-ide-cli](/packages/weapp-ide-cli)

## 常用示例

```bash
# 小程序开发
weapp-vite dev -p weapp

# Web 开发（指定 host）
weapp-vite dev -p h5 --host 0.0.0.0

# 小程序生产构建（不压缩 + 产出 sourcemap）
weapp-vite build -p weapp --minify false --sourcemap

# 输出分析 JSON 到文件
weapp-vite analyze -p weapp --output ./reports/analyze.json

# 透传微信预览命令
weapp-vite preview --project ./dist -q terminal
```

---

---
url: /guide/directory-structure/components.md
description: 主包组件目录，默认参与自动导入组件扫描。
---

# `components/`

这是主包组件目录，也是自动导入组件的默认扫描入口之一。

## 默认扫描范围

当 `weapp.autoImportComponents` 默认开启时，会扫描：

* `<srcRoot>/components/**/*.wxml`
* 每个已声明分包 root 下的 `components/**/*.wxml`

## 它解决什么问题

你通常不必再手写 `usingComponents`，框架会在构建时完成自动注册与补全。

## 适合放什么

* 复用组件
* 本地设计系统组件
* 主包与多个页面共享的 UI 模块

相关文档：[自动导入组件](/guide/auto-import)

---

---
url: /wevu/api-reference/core.md
description: 本页聚焦 Wevu 的“最先接触”能力：应用入口、组件定义、宏，以及模板辅助函数。
---

# Core API（入口、组件、宏）

本页聚焦 `wevu` 的“最先接触”能力：应用入口、组件定义、`<script setup>` 宏，以及模板辅助函数。

## 1. 入口与组件定义

| API               | 类型入口                                         | 说明                                         |
| ----------------- | ------------------------------------------------ | -------------------------------------------- |
| `createApp`       | `CreateAppOptions` / `RuntimeApp`                | 创建并注册小程序 App，桥接全局生命周期。     |
| `defineComponent` | `DefineComponentOptions` / `ComponentDefinition` | 定义页面或组件（统一注册为 `Component()`）。 |

## 2. `<script setup>` 宏

这些 API 主要用于 SFC 编译阶段，运行时多数会被擦除或改写。建议和 `weapp-vite/volar` 一起使用以获得更完整类型提示。

| API             | 类型入口                                     | 说明                                                    |
| --------------- | -------------------------------------------- | ------------------------------------------------------- |
| `defineProps`   | `ComponentPropsOptions` / `ExtractPropTypes` | 声明 props（对象写法或泛型写法）。                      |
| `withDefaults`  | `ExtractDefaultPropTypes`                    | 给类型化 props 设置默认值。                             |
| `defineEmits`   | `EmitsOptions` / `TriggerEventOptions`       | 声明 emit，支持数组、对象、函数签名、named tuple 泛型。 |
| `defineSlots`   | `VNode`                                      | 声明 slots 类型。                                       |
| `defineExpose`  | `ComponentPublicInstance`                    | 暴露实例字段给父组件引用。                              |
| `defineModel`   | `ModelBinding`                               | 定义 `v-model` 对应模型（含默认键）。                   |
| `defineOptions` | `MiniProgramComponentOptions`                | 在 `<script setup>` 中声明组件选项（含 `behaviors`）。  |
| `mergeModels`   | `ModelBindingPayload`                        | 合并多路 model 绑定结果。                               |
| `useModel`      | `ModelBinding`                               | 运行时读取/写入某个 model。                             |

### 宏能力示例（script setup）

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { useTemplateRef } from 'wevu'

// [TS-only] interface 类型声明仅支持 lang="ts"
interface Props {
  title?: string
  modelValue: number
}

// [TS-only] defineProps 泛型写法仅支持 lang="ts"
const props = withDefaults(defineProps<Props>(), {
  title: '默认标题',
})

// [TS-only] defineEmits 泛型（含 named tuple）仅支持 lang="ts"
const emit = defineEmits<{
  'submit': [value: string]
  'update:modelValue': [value: number]
}>()

// [TS-only] defineModel 泛型仅支持 lang="ts"
const model = defineModel<number>()
const inputRef = useTemplateRef('input')

// [TS-only] 参数类型注解仅支持 lang="ts"
function onSubmit(value: string) {
  emit('submit', value)
  emit('update:modelValue', model.value ?? 0)
  console.log(props.title, inputRef.value)
}

defineExpose({ onSubmit })
</script>
```

```vue [JavaScript]
<script setup>
import { useTemplateRef } from 'wevu'

const props = defineProps({
  title: String,
  modelValue: Number,
})

const emit = defineEmits(['submit', 'update:modelValue'])
const model = defineModel()
const inputRef = useTemplateRef('input')

function onSubmit(value) {
  emit('submit', value)
  emit('update:modelValue', model.value ?? 0)
  console.log(props.title, inputRef.value)
}

defineExpose({ onSubmit })
</script>
```

:::

## 3. 模板和 class/style 工具

| API                 | 类型入口                           | 说明                                                        |
| ------------------- | ---------------------------------- | ----------------------------------------------------------- |
| `useAttrs`          | `SetupContext`                     | 获取 attrs（透传属性）。                                    |
| `useSlots`          | `TemplateRefs`                     | 获取 slots。                                                |
| `useTemplateRef`    | `TemplateRef` / `TemplateRefValue` | 获取模板 `ref` 对应实例。                                   |
| `useNativeInstance` | `SetupContextNativeInstance`       | 访问 setup 绑定的原生实例。                                 |
| `useRouter`         | `Router`                           | 组件路径语义 Router（`router -> pageRouter -> wx/my/tt`）。 |
| `usePageRouter`     | `Router`                           | 页面路径语义 Router（`pageRouter -> router -> wx/my/tt`）。 |
| `normalizeClass`    | `string`                           | 归一化 class 输入（对象/数组/字符串）。                     |
| `normalizeStyle`    | `Record<string, string>`           | 归一化 style 输入。                                         |

### 模板工具示例（script setup）

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { computed, normalizeClass, normalizeStyle, useAttrs, useSlots } from 'wevu'

// [TS-only] 此示例无专属语法，TS/JS 写法一致。
const attrs = useAttrs()
const slots = useSlots()
const isActive = true

const className = computed(() => normalizeClass(['card', { active: isActive }]))
const styleText = computed(() => normalizeStyle([{ color: '#1f2937', fontWeight: 600 }]))
</script>

<template>
  <view :class="className" :style="styleText" v-bind="attrs">
    <slot v-if="slots.default" />
  </view>
</template>
```

```vue [JavaScript]
<script setup>
import { computed, normalizeClass, normalizeStyle, useAttrs, useSlots } from 'wevu'

const attrs = useAttrs()
const slots = useSlots()
const isActive = true

const className = computed(() => normalizeClass(['card', { active: isActive }]))
const styleText = computed(() => normalizeStyle([{ color: '#1f2937', fontWeight: 600 }]))
</script>

<template>
  <view :class="className" :style="styleText" v-bind="attrs">
    <slot v-if="slots.default" />
  </view>
</template>
```

:::

## 4. 相关页

* 响应式能力：[/wevu/api-reference/reactivity](/wevu/api-reference/reactivity)
* setup 上下文与原生实例：[/wevu/api-reference/setup-context](/wevu/api-reference/setup-context)
* 完整函数索引：/wevu/api/

---

---
url: /wevu/api/core.md
description: 本页聚焦 Wevu 的入口能力、组件定义、script setup 宏与模板工具，采用逐 API 讲解结构。
---

# Core API（入口、组件、宏）

本页覆盖 `wevu` 中最先接触的一组 API：应用入口、组件定义、`<script setup>` 宏与模板工具。每个 API 单独成段，便于按需跳转。

## 入口与组件定义

### `createApp()` {#createapp}

* 类型入口：`CreateAppOptions` / `RuntimeApp`
* 用途：创建并注册小程序 App 运行时入口。
* 说明：通常在 App 侧只调用一次。

### `defineComponent()` {#definecomponent}

* 类型入口：`DefineComponentOptions` / `ComponentDefinition`
* 用途：定义页面/组件并接入 Wevu 生命周期与响应式。
* 说明：Wevu 统一使用 `Component()` 模型。

## Script Setup 宏

### `defineProps()` {#defineprops}

* 类型入口：`ComponentPropsOptions` / `ExtractPropTypes`
* 用途：声明组件 props。
* 说明：支持对象写法与 TS 泛型写法。

### `withDefaults()` {#withdefaults}

* 类型入口：`ExtractDefaultPropTypes`
* 用途：给类型化 props 设置默认值。
* 说明：通常与 `defineProps<T>()` 配套。

### `defineEmits()` {#defineemits}

* 类型入口：`EmitsOptions` / `TriggerEventOptions`
* 用途：声明事件与参数类型。
* 说明：支持对象/数组/泛型（含 named tuple）。

### `defineSlots()` {#defineslots}

* 类型入口：`VNode`
* 用途：声明 slots 类型。

### `defineExpose()` {#defineexpose}

* 类型入口：`ComponentPublicInstance`
* 用途：显式暴露实例字段。

### `defineModel()` {#definemodel}

* 类型入口：`ModelBinding`
* 用途：声明 `v-model` 绑定。

### `defineOptions()` {#defineoptions}

* 类型入口：`MiniProgramComponentOptions`
* 用途：在 `<script setup>` 中定义组件配置项。
* Behavior 说明：可直接声明 `behaviors`。当条目来自原生 `Behavior()` 返回值时，编译阶段会保留该表达式并继续后续转换。

### `mergeModels()` {#mergemodels}

* 类型入口：`ModelBindingPayload`
* 用途：合并多路 model 绑定结果。

### `useModel()` {#usemodel}

* 类型入口：`ModelBinding`
* 用途：运行时读取/写入某个 model。

## 模板工具

### `useAttrs()` {#useattrs}

* 类型入口：`SetupContext`
* 用途：获取透传属性 attrs。

### `useSlots()` {#useslots}

* 类型入口：`TemplateRefs`
* 用途：读取 slots。

### `useTemplateRef()` {#usetemplateref}

* 类型入口：`TemplateRef` / `TemplateRefValue`
* 用途：读取模板 ref 对应实例。

### `useNativeInstance()` {#usenativeinstance}

* 类型入口：`SetupContextNativeInstance`
* 用途：在 setup 中访问原生页面/组件实例。

### `useRouter()` {#userouter}

* 类型入口：`WechatMiniprogram.Component.Router`
* 用途：获取组件路径语义的路由器对象。
* 说明：优先命中实例 `router`，然后回退 `pageRouter`，低版本基础库再降级到全局 `wx/my/tt` 路由方法。

### `usePageRouter()` {#usepagerouter}

* 类型入口：`WechatMiniprogram.Component.Router`
* 用途：获取页面路径语义的路由器对象。
* 说明：优先命中实例 `pageRouter`，然后回退 `router`，低版本基础库再降级到全局 `wx/my/tt` 路由方法。

### `normalizeClass()` {#normalizeclass}

* 类型入口：`string`
* 用途：归一化 class 输入（对象/数组/字符串）。

### `normalizeStyle()` {#normalizestyle}

* 类型入口：`string`
* 用途：归一化 style 输入。

## 示例

### 宏能力示例（script setup）

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { useTemplateRef } from 'wevu'

interface Props {
  title?: string
  modelValue: number
}

const props = withDefaults(defineProps<Props>(), {
  title: '默认标题',
})

const emit = defineEmits<{
  'submit': [value: string]
  'update:modelValue': [value: number]
}>()

const model = defineModel<number>()
const inputRef = useTemplateRef('input')

function onSubmit(value: string) {
  emit('submit', value)
  emit('update:modelValue', model.value ?? 0)
  console.log(props.title, inputRef.value)
}

defineExpose({ onSubmit })
</script>
```

```vue [JavaScript]
<script setup>
import { useTemplateRef } from 'wevu'

const props = defineProps({ title: String, modelValue: Number })
const emit = defineEmits(['submit', 'update:modelValue'])
const model = defineModel()
const inputRef = useTemplateRef('input')

function onSubmit(value) {
  emit('submit', value)
  emit('update:modelValue', model.value ?? 0)
  console.log(props.title, inputRef.value)
}

defineExpose({ onSubmit })
</script>
```

:::

---

---
url: /packages/create-weapp-vite.md
description: create-weapp-vite 是官方脚手架，用于快速创建小程序工程，并在模板中对齐 Weapp-vite / Wevu 的版本组合。
---

# create-weapp-vite

`create-weapp-vite` 是官方脚手架，用于快速创建小程序工程，并在模板中对齐 `weapp-vite` / `wevu` 的版本组合。

> \[!IMPORTANT]
> 如果你在已有项目里手动安装 `weapp-vite` 与 `wevu`，也请保持两者版本号一致（例如 `weapp-vite@x.y.z` 与 `wevu@x.y.z`）。

## 何时使用

* 你想快速初始化新项目
* 你希望通过模板统一团队目录结构与依赖版本
* 你要在 CI 或自动化脚本里做非交互创建

## 快速开始

```bash
pnpm create weapp-vite
# 或 npx create-weapp-vite
```

### 非交互模式

```bash
pnpm create weapp-vite my-app wevu
```

第二个参数是模板名，内部对应 `TemplateName` 枚举。

## 可编程 API

```ts
import { createProject, TemplateName } from 'create-weapp-vite'

await createProject('my-app', TemplateName.wevu)
```

## 可选模板（当前实现）

* `default`
* `wevu`
* `tailwindcss`
* `vant`
* `tdesign`
* `wevu-tdesign`
* `wevu-retail`

## 与主文档的关系

* 工程创建后，日常开发请转到 [指引](/guide/) 与 [配置](/config/)。

---

---
url: /guide/directory-structure/custom-tab-bar.md
description: 微信自定义 tabBar 的固定保留目录，必须与 app.json 处于同一个 srcRoot 下。
---

# `custom-tab-bar/`

这是微信自定义 tabBar 的固定目录。

## 触发条件

当 `app.json` 中存在：

```json
{
  "tabBar": {
    "custom": true
  }
}
```

`weapp-vite` 会把 `custom-tab-bar/index` 当成固定入口分析。

## 位置要求

* 目录名必须是 `custom-tab-bar`
* 必须和 `app.json` 位于同一个 `srcRoot` 下

如果 `app.json` 在 `<srcRoot>/`，那它就应该是：

```text
<srcRoot>/
  app.json
  custom-tab-bar/
    index.vue
```

它不是普通页面目录，也不通过自动路由发现。

---

---
url: /dashboard.md
description: >-
  const Dashboard = defineClientComponent(()=>{ return
  import('./.vitepress/components/Dashboard.vue') }) // import Dashb…
---


---

---
url: /wevu/component.md
description: >-
  defineComponent() 是对原生 Component() 的一层封装/增强：在组件 lifetimes.created
  阶段初始化运行时并同步执行 setup()；setup() 返回对象会合并到组件实例，模板可直接使用。
---

# defineComponent（组件）

`defineComponent()` 是对原生 `Component()` 的一层封装/增强：在组件 `lifetimes.created` 阶段初始化运行时并同步执行 `setup()`；`setup()` 返回对象会合并到组件实例，模板可直接使用。

> 注意：小程序在 `created` 阶段禁止调用 `setData`。因此 Wevu 会在 `created` 阶段**缓冲**由响应式更新产生的 `setData`，并在首次安全时机（组件 `attached` / 页面 `onLoad`）再统一 flush。

此外，`defineComponent` 的 `data` **必须是函数**（与 Vue 3 一致，和小程序原生对象写法不同）。原因是原生小程序会在实例化时拷贝 `data` 对象以隔离实例；Wevu 需要为每个实例创建独立的响应式 state/代理与快照 diff，因此要求返回新对象，避免共享引用污染与 diff 不稳定。

本页主要回答两类问题：

* “我原来写 `Component({ ... })` 的字段，放到 `defineComponent({ ... })` 里怎么写？”
* “组件/页面生命周期到底什么时候触发？为什么 created 里更新不生效？”

## 页面也用 defineComponent（统一模型）

在 Wevu 里，页面与组件都通过 `Component()` 注册，这是统一模型的一部分：

* 页面特有能力（滚动/分享/触底/下拉刷新等）通过 Wevu 的页面 hooks 注册（详见 `/wevu/runtime`）。
* 小程序“按需派发”的页面事件，需要对应页面方法存在才会触发；配合 Weapp-vite 构建时，通常由编译阶段自动补齐 `features.enableOnXxx`（详见 `/wevu/vue-sfc`）。

## 原生 Component 选项在 Wevu 的写法

结论先说：除了 `data / computed / methods / watch / setup / props` 这些由 Wevu 接管的“增强选项”外，其余原生 `Component({ ... })` 的字段，都可以**直接写到** `defineComponent({ ... })` 里（Wevu 会透传给原生 `Component()`）。

下面按你列出的字段逐项对照（类型定义可参考 `miniprogram-api-typings` 中的 `WechatMiniprogram.Component.*`）。

| 原生字段           | Wevu 写法                                                                                                                         | 说明                                                                                                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `behaviors`        | `defineComponent({ behaviors: [...] })`                                                                                           | 原样透传给 `Component()`。                                                                                                                                                                                                               |
| `data`             | `defineComponent({ data: () => ({ ... }) })` 或 `setup()` return 非函数字段                                                       | `data` 必须是函数（Vue 3 一致）；`setup()` 返回的非函数字段会进入运行时 state。原生小程序会拷贝对象避免实例间共享，而 Wevu 需创建独立响应式 state/快照 diff。                                                                            |
| `methods`          | `defineComponent({ methods: { ... } })` 或 `setup()` return 函数                                                                  | `methods` 与 `setup()` 返回函数都会成为实例方法；同名时原生 `methods` 会在 Wevu 包装后仍可执行（内部会先尝试运行 Wevu 方法）。                                                                                                           |
| `definitionFilter` | `defineComponent({ definitionFilter(defFields, arr) { ... } })`                                                                   | 原生组件扩展能力，Wevu 不改写，直接透传。                                                                                                                                                                                                |
| `export`           | `defineComponent({ export() { return ... } })` 或 `setup(_, { expose }) { expose({ ... }) }`                                      | 原生导出用于 `behavior: wx://component-export`：Wevu 默认会把 `setup()` 里 `expose({ ... })` 的结果作为 `export()` 返回值，因此通常无需再手写 `export()`；若同时提供了 `export()`，会与 `expose()` 结果浅合并（`export()` 优先级更高）。 |
| `externalClasses`  | `defineComponent({ externalClasses: [...] })`                                                                                     | 原样透传。                                                                                                                                                                                                                               |
| `lifetimes`        | 推荐用 `setup()` + Wevu hooks；也可写 `defineComponent({ lifetimes: { ... } })`                                                   | `lifetimes.ready/detached/moved/error` 会被 Wevu 包装以派发对应 hook，但你的原生回调仍会被调用；`lifetimes.created` 用于执行 Wevu 的 `setup()`，并会在后续首次安全时机（`attached/onLoad`）flush 缓冲的 `setData`。                      |
| `observers`        | 推荐用 `watch()`/`watchEffect()` 或 `defineComponent({ watch: { 'a.b': fn } })`；也可写 `defineComponent({ observers: { ... } })` | `observers` 是原生数据监听器（支持更复杂的表达式/通配），Wevu 不改写，直接透传；Wevu 的 `watch` 是基于运行时代理的路径监听（更像 Vue 的 `watch` 选项）。                                                                                 |
| `options`          | `defineComponent({ options: { ... } })`                                                                                           | 原生 `ComponentOptions`（`multipleSlots/styleIsolation/pureDataPattern/virtualHost/...`）。注意：Wevu 默认会把 `options.multipleSlots` 置为 `true`（用户显式传入则以用户为准）。                                                         |
| `pageLifetimes`    | 推荐用 `onShow/onHide/onResize/onRouteDone`；也可写 `defineComponent({ pageLifetimes: { ... } })`                                 | `show/hide/resize/routeDone` 会被 Wevu 包装以派发 hook；其他字段按原生透传执行。                                                                                                                                                         |
| `properties`       | 推荐：`props`；也可：`defineComponent({ properties: { ... } })`                                                                   | `props` 会被 Wevu 规范化为原生 `properties`；如果同时传了 `props` 与 `properties`，以 `props` 生成的 `properties` 为准。                                                                                                                 |
| `relations`        | `defineComponent({ relations: { ... } })`                                                                                         | 原样透传。                                                                                                                                                                                                                               |

> 小提示：如果你在 Wevu 里需要使用“原生 this”（例如访问 `this.setData`、`this.triggerEvent`、`selectComponent` 等），可以在 `setup(props, ctx)` 里通过 `ctx.instance` 访问小程序实例。

## Behavior 迁移补充（SFC 场景）

结论先说：

* `wevu` 运行时不会重写 `behaviors` 合并规则，`behaviors` 仍由小程序原生 `Component()` 处理。
* 迁移原生 `Behavior()` 时，推荐优先保持“Behavior 文件 + 组件引用”模式，不要把 behavior 内容手动改写成 Wevu 私有逻辑。

### 写法 1：`<script>` + `defineComponent`（最直观）

```vue
<script lang="ts">
import { defineComponent } from 'wevu'
import SkylineBehavior from '@/behaviors/skyline'

export default defineComponent({
  behaviors: [SkylineBehavior],
})
</script>
```

### 写法 2：`<script setup>` + `defineOptions`

```vue
<script setup lang="ts">
import SkylineBehavior from '@/behaviors/skyline'

defineOptions({
  behaviors: [SkylineBehavior],
})
</script>
```

补充说明：

* 如果 `behaviors` 里是内建 behavior（例如 `wx://component-export`），直接写字符串数组即可。
* 如果 `behaviors` 来自原生 `Behavior()` 返回值，`defineOptions` 会在编译阶段保留该表达式并继续编译，不会因为构建环境没有全局 `Behavior` 而中断。
* `definitionFilter`、`observers`、`lifetimes` 的执行顺序与覆盖关系，仍以微信官方 `behaviors` 规则为准。

## lifetimes / pageLifetimes 对应的 hooks

> 说明：Wevu 的 `onXXX()` 必须在 `setup()` **同步阶段**注册；由于 Wevu 会在 `lifetimes.created` 内执行 `setup()`，因此你可以在 `setup()` 里注册所有 Wevu hooks（包括 `onBeforeMount` 等）。

### lifetimes（组件生命周期）

| 小程序字段           | 回调名     | 对应 Wevu hook             | 说明                                                                           |
| -------------------- | ---------- | -------------------------- | ------------------------------------------------------------------------------ |
| `lifetimes.created`  | `created`  | `setup()`                  | Wevu 在此阶段 mount 并执行 `setup()`（`setData` 会被延迟到 `attached/onLoad`） |
| `lifetimes.attached` | `attached` | -                          | 组件进入节点树；Wevu 会在此阶段 flush `created` 阶段缓冲的 `setData`           |
| `lifetimes.ready`    | `ready`    | `onReady` / `onMounted`    | 组件就绪（内部做了重复触发去重）                                               |
| `lifetimes.moved`    | `moved`    | `onMoved`                  | 组件移动（例如在节点树中被移动）                                               |
| `lifetimes.detached` | `detached` | `onUnload` / `onUnmounted` | detached 时 teardown，并触发 `onUnload`                                        |
| `lifetimes.error`    | `error`    | `onError`                  | 组件错误（参数透传原生回调）                                                   |

### pageLifetimes（页面对组件的影响）

| 小程序字段                | 回调名      | 对应 Wevu hook             | 说明                                     |
| ------------------------- | ----------- | -------------------------- | ---------------------------------------- |
| `pageLifetimes.show`      | `show`      | `onShow` / `onActivated`   | 所在页面显示                             |
| `pageLifetimes.hide`      | `hide`      | `onHide` / `onDeactivated` | 所在页面隐藏                             |
| `pageLifetimes.resize`    | `resize`    | `onResize`                 | 所在页面尺寸变化（参数透传原生回调）     |
| `pageLifetimes.routeDone` | `routeDone` | `onRouteDone`              | 所在页面路由动画完成（基础库 `2.31.2+`） |

---

---
url: /config/js.md
description: >-
  Weapp-vite 默认使用 Vite 8 原生的 resolve.tsconfigPaths 读取
  tsconfig.json/jsconfig.json 的 paths/baseUrl，并在需要高级选项时兼容 vite-tsconfig-paths。
---

# JS 配置 {#js-config}

`weapp-vite` 默认使用 Vite 8 原生的 `resolve.tsconfigPaths` 读取 `tsconfig.json/jsconfig.json` 的 `paths/baseUrl`，把别名映射到 Vite / Rolldown 流程中；只有在你传入高级选项对象时，才会回退到 `vite-tsconfig-paths` 插件。

\[\[toc]]

## `weapp.tsconfigPaths` {#weapp-tsconfigpaths}

* **类型**：`boolean | TsconfigPathsOptions | false`
* **默认值**：`undefined`（按需自动启用）

启用规则：

* 当 `tsconfig.json` 或 `jsconfig.json` **存在 `paths` 或 `baseUrl`** 时，会自动启用 Vite 原生 `resolve.tsconfigPaths`；
* 传入 `true` 时，会强制启用原生 `resolve.tsconfigPaths`；
* 传入对象时，会启用 `vite-tsconfig-paths` 插件以支持 `projects`、`exclude` 等高级选项；
* 传入 `false` 可完全禁用（适合没有别名需求、追求更快启动的项目）。

推荐优先使用默认行为或 `true`，这样不会触发 Vite 8 对 `vite-tsconfig-paths` 的提示信息。

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

export default defineConfig({
  weapp: {
    tsconfigPaths: true,
  },
})
```

```ts
import { defineConfig } from 'weapp-vite/config'
import type { PluginOptions } from 'vite-tsconfig-paths'

const tsconfigOptions: PluginOptions = {
  projects: ['./tsconfig.base.json'],
  extensions: ['.ts', '.js', '.vue'],
  exclude: ['**/__tests__/**'],
}

export default defineConfig({
  weapp: {
    tsconfigPaths: tsconfigOptions,
  },
})
```

### 与 `resolve.alias` 的关系

* `weapp.tsconfigPaths` / `resolve.tsconfigPaths` 负责把 **tsconfig 的 paths/baseUrl** 转成 Vite alias。
* 你仍然可以在 `resolve.alias` 中补充或覆盖特定映射，两者可共存。

```ts
export default defineConfig({
  resolve: {
    alias: {
      '@shared': '/packages/shared/src',
    },
  },
  weapp: {
    tsconfigPaths: {
      projects: ['./tsconfig.base.json'],
    },
  },
})
```

### 常见问题

* **修改 `paths` 没生效？** 需要重启 `pnpm dev`，并确认 tsconfig 在 `projects` 列表内。
* **JSON 别名怎么配？** JSON 使用 `weapp.jsonAlias`（见 [JSON 配置](/config/json.md#weapp-jsonalias)），与 JS/TS 别名相互独立。

***

更多 alias 实战与疑难排查，请参考 [路径别名指南](/guide/alias)。

---

---
url: /config/json.md
description: >-
  Weapp-vite 支持原生 json/jsonc，并提供 **JSON 别名** 与 **JSON 合并策略**，方便在 app.json /
  page.json / component.json 中复用配置。
---

# JSON 配置 {#json-config}

`weapp-vite` 支持原生 `json/jsonc`，并提供 **JSON 别名** 与 **JSON 合并策略**，方便在 `app.json / page.json / component.json` 中复用配置。

\[\[toc]]

## `weapp.jsonAlias` {#weapp-jsonalias}

* **类型**：`{ entries?: Record<string, string> | { find: string | RegExp; replacement: string }[] }`
* **默认值**：`undefined`
* **作用范围**：**仅作用于 `usingComponents`**（其他字段保持原样）。

```ts
import path from 'node:path'
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    jsonAlias: {
      entries: [
        { find: '@/components/', replacement: path.resolve(import.meta.dirname, 'src/components/') },
        { find: /^@icons\//, replacement: path.resolve(import.meta.dirname, 'src/assets/icons/') },
      ],
    },
  },
})
```

JSON/JSONC 中可直接使用别名：

```jsonc
{
  "usingComponents": {
    "nav-bar": "@/components/navigation-bar",
    "logo-icon": "@icons/logo"
  }
}
```

构建产物会转换为相对路径：

```json
{
  "usingComponents": {
    "nav-bar": "../../components/navigation-bar",
    "logo-icon": "../../assets/icons/logo"
  }
}
```

> \[!TIP]
> `replacement` 推荐使用**绝对路径**，避免因工作目录变化导致解析失败。

## `weapp.json.defaults` {#weapp-json-defaults}

* **类型**：`{ app?: Record<string, any>; page?: Record<string, any>; component?: Record<string, any> }`
* **默认值**：`undefined`
* **作用**：给 app/page/component JSON 注入统一默认值。

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

export default defineConfig({
  weapp: {
    json: {
      defaults: {
        app: {
          entryPagePath: 'pages/index/index',
        },
        page: {
          navigationStyle: 'custom',
        },
        component: {
          styleIsolation: 'apply-shared',
        },
      },
    },
  },
})
```

说明：

* 默认值会在生成 `.json` 产物时合并。
* 页面/组件自身的 JSON（或 SFC `<json>` / 宏）会覆盖默认值。

## `weapp.json.mergeStrategy` {#weapp-json-merge-strategy}

* **类型**：`'deep' | 'assign' | 'replace' | (target, source, ctx) => Record<string, any> | void`
* **默认值**：`'deep'`

```ts
export default defineConfig({
  weapp: {
    json: {
      mergeStrategy: 'assign',
    },
  },
})
```

函数策略会收到上下文：

```ts
export default defineConfig({
  weapp: {
    json: {
      mergeStrategy(target, source, ctx) {
        if (ctx.kind === 'page' && ctx.stage === 'defaults') {
          return { ...target, ...source }
        }
        return { ...source, ...target }
      },
    },
  },
})
```

常见 `ctx.stage`：`defaults` / `json-block` / `auto-using-components` / `component-generics` / `macro` / `emit` / `merge-existing`。

***

需要配置脚本别名？请前往 [JS 配置](/config/js.md#weapp-tsconfigpaths)。

---

---
url: /guide/json-intelli-sense.md
description: 给 app.json、page.json 等文件加上 $schema 字段后，VS Code、微信开发者工具等编辑器就能提供：
---

# JSON 配置文件的智能提示

给 `app.json`、`page.json` 等文件加上 `$schema` 字段后，VS Code、微信开发者工具等编辑器就能提供：

* 字段补全
* 取值提示
* 错误校验

本页提供现成的 Schema 地址，复制到文件开头即可使用。

> \[!TIP]
> 使用 Weapp-vite 的脚手架（`pnpm g`）生成的页面/组件，默认已经包含对应的 `$schema`，你只需确认编辑器支持 JSON Schema 即可。工作区已在 `.vscode/settings.json` 里把在线地址映射到本地 `node_modules/@weapp-core/schematics/schemas/*.json`，既保留短链接又支持离线补全。

## 如何添加 `$schema`

在目标配置文件的开头写入对应的 `$schema` 字段，例如：

```jsonc
{
  "$schema": "https://vite.icebreaker.top/page.json",
  "navigationBarTitleText": "Home"
}
```

`$schema` 只在编辑器里生效；构建阶段会自动剥离，不会影响最终产物。

## 常用 Schema 列表

| 文件             | `$schema` 地址                                   |
| ---------------- | ----------------------------------------------- |
| 组件 `component.json` | `"https://vite.icebreaker.top/component.json"` |
| 页面 `page.json`      | `"https://vite.icebreaker.top/page.json"`      |
| 应用 `app.json`       | `"https://vite.icebreaker.top/app.json"`       |
| `sitemap.json`        | `"https://vite.icebreaker.top/sitemap.json"`   |
| `theme.json`          | `"https://vite.icebreaker.top/theme.json"`     |

直接复制右侧的地址粘贴即可。如果编辑器支持“悬浮后复制按钮”，也可以将整行复制下来放入文件中。VS Code 用户无需修改 `$schema`，工作区设置会自动将在线地址重定向到本地 Schema 文件。

## 效果展示

![vscode-json-intel](/vscode-json-intel.png)

## 常见问题

* **需要联网吗？** 默认 `$schema` 仍是在线地址，但 VS Code 会把它映射到本地 `node_modules/@weapp-core/schematics/schemas/*.json`，离线也能补全。如果换用其他编辑器，可手动做类似映射或直接改成本地路径。
* **生成器能输出本地 `$schema` 吗？** 可以，通过环境变量 `WEAPP_SCHEMA_BASE=file:///<你的项目绝对路径>/node_modules/@weapp-core/schematics/schemas` 让 `@weapp-core/schematics` 生成时使用本地 Schema（非必需，仅想让文件自带本地路径时启用）。
* **脚手架已生成 `$schema`，但仍没有提示？** 请确认编辑器启用了 JSON Schema 支持：VS Code 需安装官方小程序扩展或开启原生 JSON 支持；微信开发者工具需升级到较新的版本。
* **和 `json.ts` / `json.js` 配合？** 可以。在脚本文件里同样可以导出 `$schema` 字段，Weapp-vite 在构建时会一并剥离。

---

---
url: /wevu/api-reference/lifecycle.md
description: Wevu 生命周期 API 都需要在 setup() 的同步阶段调用。
---

# Lifecycle API（生命周期）

`wevu` 生命周期 API 都需要在 `setup()` 的同步阶段调用。

## 1. App 生命周期

| API                    | 类型入口           | 说明                       |
| ---------------------- | ------------------ | -------------------------- |
| `onLaunch`             | `DefineAppOptions` | 小程序 App 启动。          |
| `onShow`               | `RuntimeApp`       | App 进入前台。             |
| `onHide`               | `RuntimeApp`       | App 进入后台。             |
| `onError`              | `RuntimeApp`       | 运行时错误回调。           |
| `onPageNotFound`       | `RuntimeApp`       | 路由未命中。               |
| `onUnhandledRejection` | `RuntimeApp`       | 未处理 Promise rejection。 |
| `onThemeChange`        | `RuntimeApp`       | 系统主题变化。             |
| `onMemoryWarning`      | `RuntimeApp`       | 内存告警回调。             |

## 2. 页面与组件通用生命周期

| API        | 类型入口          | 说明                       |
| ---------- | ----------------- | -------------------------- |
| `onLoad`   | `RuntimeInstance` | 页面参数加载（页面常用）。 |
| `onReady`  | `RuntimeInstance` | 首次渲染完成。             |
| `onShow`   | `RuntimeInstance` | 页面/组件显示。            |
| `onHide`   | `RuntimeInstance` | 页面/组件隐藏。            |
| `onUnload` | `RuntimeInstance` | 页面卸载。                 |

## 3. 组件渲染阶段（Vue 风格）

| API                | 类型入口          | 说明                      |
| ------------------ | ----------------- | ------------------------- |
| `onBeforeMount`    | `RuntimeInstance` | 挂载前。                  |
| `onMounted`        | `RuntimeInstance` | 挂载后。                  |
| `onBeforeUpdate`   | `RuntimeInstance` | 更新前。                  |
| `onUpdated`        | `RuntimeInstance` | 更新后。                  |
| `onBeforeUnmount`  | `RuntimeInstance` | 卸载前。                  |
| `onUnmounted`      | `RuntimeInstance` | 卸载后。                  |
| `onActivated`      | `RuntimeInstance` | 激活（缓存场景）。        |
| `onDeactivated`    | `RuntimeInstance` | 失活（缓存场景）。        |
| `onErrorCaptured`  | `RuntimeInstance` | 捕获子树错误。            |
| `onServerPrefetch` | `RuntimeInstance` | 兼容 Vue 语义的预取钩子。 |

## 4. 小程序特有页面事件

| API                 | 类型入口       | 说明           |
| ------------------- | -------------- | -------------- |
| `onPageScroll`      | `PageFeatures` | 页面滚动。     |
| `onPullDownRefresh` | `PageFeatures` | 下拉刷新。     |
| `onReachBottom`     | `PageFeatures` | 触底事件。     |
| `onRouteDone`       | `PageFeatures` | 页面路由完成。 |
| `onTabItemTap`      | `PageFeatures` | Tab 点击。     |
| `onResize`          | `PageFeatures` | 视图尺寸变化。 |

## 5. 带返回值的页面钩子

| API                 | 类型入口       | 说明                   |
| ------------------- | -------------- | ---------------------- |
| `onShareAppMessage` | `PageFeatures` | 自定义转发内容。       |
| `onShareTimeline`   | `PageFeatures` | 自定义朋友圈分享内容。 |
| `onAddToFavorites`  | `PageFeatures` | 添加收藏。             |
| `onSaveExitState`   | `PageFeatures` | 离开时保存状态。       |

## 6. 小程序组件生命周期（lifetimes / pageLifetimes）

### 6.1 官方生命周期清单（组件侧）

| 分类            | 官方生命周期                                            |
| --------------- | ------------------------------------------------------- |
| `lifetimes`     | `created / attached / ready / moved / detached / error` |
| `pageLifetimes` | `show / hide / resize / routeDone`                      |

### 6.2 Wevu 对应能力（组合式 + 桥接）

| 官方生命周期              | Wevu 对应能力                                      | 说明                                         |
| ------------------------- | -------------------------------------------------- | -------------------------------------------- |
| `lifetimes.created`       | 组件注册时内部桥接（无独立 `onCreated` Hook）      | 已覆盖；可继续使用原生 `lifetimes.created`。 |
| `lifetimes.attached`      | 组件注册时内部桥接 + `onMounted`（组合式）         | 已覆盖；常用组合式写法是 `onMounted`。       |
| `lifetimes.ready`         | `onReady`                                          | 已覆盖。                                     |
| `lifetimes.moved`         | `onMoved`                                          | 已覆盖。                                     |
| `lifetimes.detached`      | 组件注册时内部桥接 + `onBeforeUnmount/onUnmounted` | 已覆盖。                                     |
| `lifetimes.error`         | `onError`                                          | 已覆盖。                                     |
| `pageLifetimes.show`      | `onShow`                                           | 已覆盖。                                     |
| `pageLifetimes.hide`      | `onHide`                                           | 已覆盖。                                     |
| `pageLifetimes.resize`    | `onResize`                                         | 已覆盖。                                     |
| `pageLifetimes.routeDone` | `onRouteDone`                                      | 已覆盖（微信官方基础库 `2.31.2+`）。         |

## 7. 小程序组件扩展 Hook（组合式）

| API               | 类型入口                   | 说明                                                           |
| ----------------- | -------------------------- | -------------------------------------------------------------- |
| `onAttached`      | `RuntimeInstance`          | 组件 attached 时触发（对应 `lifetimes.attached`）。            |
| `onDetached`      | `RuntimeInstance`          | 组件 detached 时触发（对应 `lifetimes.detached`）。            |
| `onMoved`         | `MiniProgramPageLifetimes` | 组件节点位置变更。                                             |
| `onError`         | `MiniProgramPageLifetimes` | 组件或 App 错误（按上下文桥接）。                              |
| `onShow`          | `RuntimeInstance`          | 组件在页面 show 时触发（由 `pageLifetimes.show` 桥接）。       |
| `onHide`          | `RuntimeInstance`          | 组件在页面 hide 时触发（由 `pageLifetimes.hide` 桥接）。       |
| `onResize`        | `PageFeatures`             | 组件所在页面 resize 时触发（由 `pageLifetimes.resize` 桥接）。 |
| `onMounted`       | `RuntimeInstance`          | 组件 attached 后触发（对应 `lifetimes.attached`）。            |
| `onBeforeUnmount` | `RuntimeInstance`          | 组件 detached 前触发（对应 `lifetimes.detached`）。            |
| `onUnmounted`     | `RuntimeInstance`          | 组件 detached 后触发（对应 `lifetimes.detached`）。            |
| `onRouteDone`     | `PageFeatures`             | 页面路由动画完成时触发（微信官方基础库 `2.31.2+`）。           |

## 8. 示例：滚动 + 分享（script setup）

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { onPageScroll, onShareAppMessage, onShow, ref } from 'wevu'

// [TS-only] 此示例无专属语法，TS/JS 写法一致。
const scrollTop = ref(0)

onShow(() => {
  console.log('page show')
})

onPageScroll((e) => {
  scrollTop.value = e.scrollTop
})

onShareAppMessage(() => ({
  title: 'wevu 页面分享',
  path: '/pages/index/index',
}))
</script>

<template>
  <view>scrollTop: {{ scrollTop }}</view>
</template>
```

```vue [JavaScript]
<script setup>
import { onPageScroll, onShareAppMessage, onShow, ref } from 'wevu'

const scrollTop = ref(0)

onShow(() => {
  console.log('page show')
})

onPageScroll((e) => {
  scrollTop.value = e.scrollTop
})

onShareAppMessage(() => ({
  title: 'wevu 页面分享',
  path: '/pages/index/index',
}))
</script>

<template>
  <view>scrollTop: {{ scrollTop }}</view>
</template>
```

:::

---

---
url: /wevu/api/lifecycle.md
description: >-
  本页仅覆盖 wevu 实际导出的生命周期 Hook（源码：runtime/hooks.ts），并补充与小程序 lifetimes/pageLifetimes
  的映射说明。
---

# Lifecycle API（生命周期）

以下条目严格对应 `packages/wevu/src/runtime/hooks.ts` 的导出函数。所有 Hook 都要求在 `setup()` 同步阶段调用。

## App 生命周期 Hook

### `onLaunch()` {#onlaunch}

* 作用域：`App`
* 源码行为：注册到 `onLaunch`。

### `onShow()` {#onshow}

* 作用域：`App / Page / Component`
* 源码行为：统一注册到 `onShow`（App 与页面/组件共用函数名）。

### `onHide()` {#onhide}

* 作用域：`App / Page / Component`
* 源码行为：统一注册到 `onHide`。

### `onError()` {#onerror}

* 作用域：`App / Component`
* 源码行为：注册到 `onError`。

### `onPageNotFound()` {#onpagenotfound}

* 作用域：`App`
* 源码行为：注册到 `onPageNotFound`。

### `onUnhandledRejection()` {#onunhandledrejection}

* 作用域：`App`
* 源码行为：注册到 `onUnhandledRejection`。

### `onThemeChange()` {#onthemechange}

* 作用域：`App`
* 源码行为：注册到 `onThemeChange`。

### `onMemoryWarning()` {#onmemorywarning}

* 作用域：`App`
* 源码行为：通过 `wx.onMemoryWarning` 注册监听，并在重复绑定时自动调用 `wx.offMemoryWarning` 清理旧监听。
* 建议：回调内优先释放大缓存、长列表临时数据与不必要的订阅/定时器。

## 页面生命周期 Hook

### `onLoad()` {#onload}

* 作用域：`Page`
* 源码行为：注册到页面 `onLoad`。

### `onReady()` {#onready}

* 作用域：`Page / Component`
* 源码行为：注册到 `onReady`；组件通过 `lifetimes.ready` 触发。

### `onUnload()` {#onunload}

* 作用域：`Page / Component`
* 源码行为：在页面 `onUnload` 或组件 teardown 时统一触发。

## 页面事件 Hook

### `onPullDownRefresh()` {#onpulldownrefresh}

* 作用域：`Page`
* 源码行为：注册到页面 `onPullDownRefresh`。

### `onReachBottom()` {#onreachbottom}

* 作用域：`Page`
* 源码行为：注册到页面 `onReachBottom`。

### `onPageScroll()` {#onpagescroll}

* 作用域：`Page`
* 源码行为：注册到页面 `onPageScroll`。

### `onRouteDone()` {#onroutedone}

* 作用域：`Page / Component`
* 源码行为：注册到 `onRouteDone`；组件通过 `pageLifetimes.routeDone` 桥接触发。

### `onTabItemTap()` {#ontabitemtap}

* 作用域：`Page`
* 源码行为：注册到页面 `onTabItemTap`。

### `onResize()` {#onresize}

* 作用域：`Page / Component`
* 源码行为：注册到 `onResize`；组件通过 `pageLifetimes.resize` 桥接触发。

## 返回值型页面 Hook

### `onShareAppMessage()` {#onshareappmessage}

* 作用域：`Page`
* 源码行为：单实例 Hook（`single: true`），返回值用于分享配置。

### `onShareTimeline()` {#onsharetimeline}

* 作用域：`Page`
* 源码行为：单实例 Hook（`single: true`），返回值用于朋友圈分享配置。

### `onAddToFavorites()` {#onaddtofavorites}

* 作用域：`Page`
* 源码行为：单实例 Hook（`single: true`），返回值用于收藏配置。

### `onSaveExitState()` {#onsaveexitstate}

* 作用域：`Page`
* 源码行为：单实例 Hook（`single: true`），返回值用于退出状态保存。

## 组件扩展 Hook

### `onAttached()` {#onattached}

* 作用域：`Component`
* 源码行为：在组件 `lifetimes.attached` 阶段触发。

### `onDetached()` {#ondetached}

* 作用域：`Component`
* 源码行为：在组件 `lifetimes.detached` 阶段触发。

### `onMoved()` {#onmoved}

* 作用域：`Component`
* 源码行为：注册到 `lifetimes.moved`。

## Vue 语义对齐 Hook

### `onBeforeMount()` {#onbeforemount}

* 对齐语义：Vue `beforeMount`
* 源码行为：在 `setup()` 内同步立即执行。

### `onMounted()` {#onmounted}

* 对齐语义：Vue `mounted`
* 源码行为：映射到 `onReady`。

### `onBeforeUpdate()` {#onbeforeupdate}

* 对齐语义：Vue `beforeUpdate`
* 源码行为：映射到内部 `__wevuOnBeforeUpdate`。

### `onUpdated()` {#onupdated}

* 对齐语义：Vue `updated`
* 源码行为：映射到内部 `__wevuOnUpdated`。

### `onBeforeUnmount()` {#onbeforeunmount}

* 对齐语义：Vue `beforeUnmount`
* 源码行为：在 `setup()` 内同步立即执行（小程序无对应原生 before-unmount）。

### `onUnmounted()` {#onunmounted}

* 对齐语义：Vue `unmounted`
* 源码行为：映射到 `onUnload`。

### `onActivated()` {#onactivated}

* 对齐语义：Vue `activated`
* 源码行为：映射到 `onShow`。

### `onDeactivated()` {#ondeactivated}

* 对齐语义：Vue `deactivated`
* 源码行为：映射到 `onHide`。

### `onErrorCaptured()` {#onerrorcaptured}

* 对齐语义：Vue `errorCaptured`
* 源码行为：映射到 `onError` 包装调用。

### `onServerPrefetch()` {#onserverprefetch}

* 对齐语义：Vue `serverPrefetch`
* 源码行为：保留 API 形态，仅做调用时机校验，不执行实际逻辑。

## 小程序原生生命周期映射（说明）

以下是桥接关系说明，不是 `wevu` 直接导出的 Hook API。

### `lifetimes.created` {#lifetimes-created}

* 映射：组件初始化桥接（无独立 `onCreated` 导出）。

### `lifetimes.attached` {#lifetimes-attached}

* 映射：组件挂载流程（可使用 `onAttached`；`onMounted` 仍映射 `onReady`）。

### `lifetimes.ready` {#lifetimes-ready}

* 映射：`onReady`。

### `lifetimes.moved` {#lifetimes-moved}

* 映射：`onMoved`。

### `lifetimes.detached` {#lifetimes-detached}

* 映射：组件 teardown（可使用 `onDetached`）+ `onUnload` 钩子链（含 `onUnmounted`）。

### `lifetimes.error` {#lifetimes-error}

* 映射：`onError`。

### `pageLifetimes.show` {#pagelifetimes-show}

* 映射：`onShow`。

### `pageLifetimes.hide` {#pagelifetimes-hide}

* 映射：`onHide`。

### `pageLifetimes.resize` {#pagelifetimes-resize}

* 映射：`onResize`。

### `pageLifetimes.routeDone` {#pagelifetimes-routedone}

* 映射：`onRouteDone`。

## 示例

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import {
  onMounted,
  onPageScroll,
  onRouteDone,
  onShareAppMessage,
  onShow,
  ref,
} from 'wevu'

const scrollTop = ref(0)

onShow(() => {
  console.log('page show')
})

onMounted(() => {
  console.log('mounted')
})

onPageScroll((e) => {
  scrollTop.value = e.scrollTop
})

onRouteDone(() => {
  console.log('route done')
})

onShareAppMessage(() => ({
  title: 'Wevu 页面分享',
  path: '/pages/index/index',
}))
</script>

<template>
  <view>scrollTop: {{ scrollTop }}</view>
</template>
```

```vue [JavaScript]
<script setup>
import {
  onMounted,
  onPageScroll,
  onRouteDone,
  onShareAppMessage,
  onShow,
  ref,
} from 'wevu'

const scrollTop = ref(0)

onShow(() => {
  console.log('page show')
})

onMounted(() => {
  console.log('mounted')
})

onPageScroll((e) => {
  scrollTop.value = e.scrollTop
})

onRouteDone(() => {
  console.log('route done')
})

onShareAppMessage(() => ({
  title: 'Wevu 页面分享',
  path: '/pages/index/index',
}))
</script>

<template>
  <view>scrollTop: {{ scrollTop }}</view>
</template>
```

:::

---

---
url: /packages/rolldown-require/cache.md
description: >-
  This page outlines how bundleRequire bundles, writes, and loads under the
  hood, plus practical cache settings.
---

# Loading flow & cache

> Language: English | [中文](/packages/rolldown-require/cache.zh)

This page outlines how `bundleRequire` bundles, writes, and loads under the hood, plus practical cache settings.

## End-to-end flow

1. **Resolve entry**: turn `filepath` + `cwd` into an absolute path and infer `format` from the extension/`package.json.type` (overrideable).
2. **Bundle with rolldown**:
   * Fix `platform: 'node'`, `inlineDynamicImports: true`, `treeshake: false` to emit a single entry output and collect dependencies.
   * Inject `__dirname`/`__filename`/`import.meta.url` so runtime code sees the real source path.
   * Externalize most `node_modules` via the externalize-deps plugin, keep JSON inlined, and respect `module-sync` conditions.
3. **Execute the temp output**:
   * ESM: write a temp `.mjs`/`.cjs` or data URL, then `import()` it.
   * CJS: compile the source via a temporary `_require.extensions` hook.
4. **Return results**: provide `mod` plus `dependencies` (excluding the entry) for watching or debugging.

## Externalization & resolution

* Resolution aligns with Vite/rolldown: same main-field priority and `tsconfig` path support (when enabled).
* Node built-ins and `node:`/`npm:` namespace imports are marked external.
* Dependencies inside nested `node_modules` under the entry directory are inlined to keep the temp output runnable.
* JSON resources are always handled by rolldown (never externalized).

## Temp output control

* Defaults to the nearest `node_modules/.rolldown-require`; falls back to the system temp dir. Filenames include a random hash to avoid contention.
* Customize the path via `getOutputFile`; set `preserveTemporaryFile: true` to skip cleanup for direct inspection.
* If all disk attempts fail for ESM, it falls back to a `data:` URL.

## Cache strategy

Caching is off by default. Set `cache: true` or pass an object to enable persistent + in-memory cache:

* **Location**: nearest `node_modules/.rolldown-require-cache`, else `os.tmpdir()/rolldown-require-cache`; override with `cache.dir`.
* **Cache key**: entry path, `mtime`/`size`, `format`, `tsconfig` path, Node version, and a hash of `rolldownOptions`.
* **Validation**: after a hit, each entry/dependency `mtime`/`size` is compared; any change invalidates the cache.
* **Memory cache**: on by default (`cache.memory !== false`); returns the loaded module directly to avoid extra fs I/O.
* **Reset & events**:
  * `cache.reset: true` removes prior code/meta before writing.
  * `cache.onEvent` receives `hit`/`miss`/`store`/`skip-invalid`; `skip-invalid.reason` may be `missing-entry`, `format-mismatch`, `stale-deps`, etc.

Example: log cache events and set a custom directory

```ts
await bundleRequire({
  filepath: './config/vite.config.ts',
  cache: {
    enabled: true,
    dir: './.cache/rolldown-require',
    onEvent: (e) => {
      console.log(`[cache] ${e.type}`, e)
    },
  },
})
```

## Debugging tips

* Watch `dependencies` to decide when to call `bundleRequire` again.
* Pair with `preserveTemporaryFile: true` to inspect temp code, or compare `*.code.mjs/cjs` directly inside the cache dir.
* To debug suspicious hits, temporarily set `cache.reset: true` or disable cache entirely.
* When the entry extension and `package.json.type` disagree, pass `format` explicitly to avoid Node/rolldown differences.

---

---
url: /integration/miniprogram-computed.md
description: >-
  miniprogram-computed
  的用法基本和官方一致。需要注意的是：为了确保构建产物里依赖齐全，建议把它的运行时依赖也显式安装到项目里（避免构建时被裁剪/遗漏）。
---

# miniprogram-computed 集成

`miniprogram-computed` 的用法基本和官方一致。需要注意的是：为了确保构建产物里依赖齐全，建议把它的运行时依赖也显式安装到项目里（避免构建时被裁剪/遗漏）。

## 安装

```sh
pnpm add miniprogram-computed fast-deep-equal rfdc
```

> \[!TIP]
> `miniprogram-computed` 是运行时要用的库，更推荐放在 `dependencies` 而不是 `devDependencies`。

## 使用方式

```ts
import { ComponentWithComputed } from 'miniprogram-computed'
// js 中也可以使用 import { behavior as computedBehavior } from 'miniprogram-computed'
ComponentWithComputed({
  data: {
    a: 1,
    b: 1,
  },
  computed: {
    sum(data) {
      // 注意： computed 函数中不能访问 this ，只有 data 对象可供访问
      // 这个函数的返回值会被设置到 this.data.sum 字段中
      return data.a + data.b
    },
  },
  methods: {
    onTap() {
      this.setData({
        a: this.data.b,
        b: this.data.a + this.data.b,
      })
    },
  },
})
```

相关 `issues`:

1. [miniprogram-computed](https://github.com/weapp-vite/weapp-vite/issues/65)
2. [fast-deep-equal和rfdc可以放在peer-dependencies里面吗？](https://github.com/wechat-miniprogram/computed/issues/87)

---

---
url: /guide/npm.md
description: Weapp-vite 会尽量帮你把“npm 依赖怎么进小程序”这件事自动化：默认提供 **2 种自动策略**，以及 **1 个手动触发**命令。
---

# npm 自动构建

`weapp-vite` 会尽量帮你把“npm 依赖怎么进小程序”这件事自动化：默认提供 **2 种自动策略**，以及 **1 个手动触发**命令。

::: tip 配置速记
若需要关闭自动打包、切换缓存策略或为特定依赖覆写 Vite 库模式的构建选项，请在 `vite.config.ts` 中调整 [`weapp.npm`](/config/npm.md#weapp-npm)。
:::

## 自动构建

自动构建时会发生两类事情（你不需要手动二选一，框架会按规则处理）：

1. **把依赖构建到 `miniprogram_npm`**（适合保留 `require('xxx')` 的形式）
2. **把依赖内联进页面/组件脚本**（适合减少 npm 目录或处理非运行时依赖）

### 1. 构建到 `miniprogram_npm`（来自 `dependencies`）

你在 `package.json.dependencies` 里声明的依赖，会在构建时被打包成小程序可用的格式，并输出到 `project.config.json` 的 `miniprogramNpmDistDir` 目录下（也就是 `miniprogram_npm/`）。

### 2. 内联到脚本产物（不在 `dependencies` 的依赖）

没有出现在 `package.json.dependencies` 里的依赖（例如写在 `devDependencies`、或来自 monorepo 更上层的依赖），在被 `import`/`require` 后会被构建器打包并**内联**到对应的页面/组件脚本里。

### 详细解释

看一个最常见的例子：

```json
{
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "lodash-es": "^4.17.21"
  }
}
```

其中 `lodash` 在 `dependencies`，`lodash-es` 在 `devDependencies`。在页面里分别引入它们时，Weapp-vite 的处理方式不同：

* **`dependencies` → 构建 `miniprogram_npm`**：产物保留 `require('lodash')`，依赖会被同步到 `miniprogram_npm`，保持最小化的页面代码。
  ```js
  const lodash = require('lodash')
  Page({
    data: {
      num0: lodash.add(1, 1),
    },
  })
  ```
* **`devDependencies` → 内联到页面脚本**：开发依赖会在构建时转成普通 JavaScript，并直接合并进页面入口，避免额外的 npm 目录。
  ```js
  var add = /* lodash-es add 的实现主体 */
  Page({
    data: {
      num1: add(2, 2),
    },
  })
  ```

> \[!TIP]
> 实际内联出来的代码会比示例长得多（可能包含工具函数等），但你不需要手动维护。只要把依赖放在合适的字段里，Weapp-vite 会自动选择“进 `miniprogram_npm`”还是“直接内联”。

### 怎么选（建议）

* **运行时确实要用、并且希望复用的库**：放进 `dependencies`，让它进 `miniprogram_npm`。
* **仅开发/构建期使用的工具**：放进 `devDependencies`。
* **想减少 `miniprogram_npm`，接受包体变大**：也可以把运行时依赖放到非 `dependencies`，让它被内联（不推荐作为默认策略）。

## 手动构建

执行命令 `weapp-vite npm` 会调用「微信开发者工具 → 工具 → 构建 npm」，手动构建 `miniprogram_npm`。

这相当于你在开发者工具里手动点了一遍“构建 npm”。

> `weapp-vite npm` 别名 `weapp-vite build:npm` / `weapp-vite build-npm`

---

---
url: /config/npm.md
description: >-
  Weapp-vite 会自动把 **dependencies** 里的依赖构建成 miniprogram_npm/，而把
  **devDependencies** 视为“仅构建期依赖”，直接内联进产物。
---

# npm 配置 {#config-npm}

`weapp-vite` 会自动把 **dependencies** 里的依赖构建成 `miniprogram_npm/`，而把 **devDependencies** 视为“仅构建期依赖”，直接内联进产物。

\[\[toc]]

## 依赖分类规则（默认）

```jsonc
{
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "lodash-es": "^4.17.21"
  }
}
```

* 引入 `lodash` ⇒ 产物保留 `require('lodash')`，并生成 `miniprogram_npm/lodash`。
* 引入 `lodash-es` ⇒ 相关实现会被打包并内联到页面/组件脚本。

> \[!TIP]
> 建议团队统一约定：**运行时依赖放 `dependencies`**，构建期依赖放 `devDependencies`。

## `weapp.npm` {#weapp-npm}

* **类型**：
  ```ts
  {
    enable?: boolean
    cache?: boolean
    mainPackage?: {
      dependencies?: false | (string | RegExp)[]
    }
    subPackages?: Record<string, {
      dependencies?: (string | RegExp)[]
    }>
    buildOptions?: (options: NpmBuildOptions, meta: { name: string; entry: InputOption }) => NpmBuildOptions | undefined
    alipayNpmMode?: 'node_modules' | 'miniprogram_npm'
  }
  ```
* **默认值**：`{ enable: true, cache: true, alipayNpmMode: 'node_modules' }`

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

export default defineConfig({
  weapp: {
    npm: {
      enable: true,
      cache: true,
      mainPackage: {
        dependencies: false,
      },
      subPackages: {
        'packages/order': {
          dependencies: [/^tdesign-miniprogram/],
        },
      },
      buildOptions(options, { name }) {
        if (name === 'lodash') {
          return {
            ...options,
            build: {
              ...options.build,
              target: 'es2018',
            },
          }
        }
        return options
      },
    },
  },
})
```

字段说明：

* `enable`：关闭后 **不会自动构建** `miniprogram_npm`。如果你的代码仍保留 `require('pkg')`，需要自行处理（如 devtools 构建 npm）。
* `cache`：是否启用 npm 构建缓存（缓存目录：`node_modules/weapp-vite/.cache/`）。
* `mainPackage.dependencies`：
  * `undefined`：默认行为，按根 `package.json.dependencies` 输出到主包；
  * `false`：禁止输出主包 `miniprogram_npm`；
  * `string[] | RegExp[]`：只把命中的依赖输出到主包。
* `subPackages`：为特定分包声明本地 npm 依赖范围。命中的分包会输出自己的 `miniprogram_npm`，并将分包内命中的 npm 引用重写到本地目录。
* `buildOptions`：为单个包覆写 Vite 库模式构建参数。
* `alipayNpmMode`：支付宝平台 npm 目录风格。默认 `node_modules`，若要兼容微信风格目录，可切到 `miniprogram_npm`。

## 主包 / 分包依赖落位

默认情况下，`weapp-vite` 会把根 `package.json.dependencies` 视为运行时依赖，输出到主包 `miniprogram_npm`。

如果你希望把依赖尽量下沉到独立分包，可以这样做：

```ts
export default defineConfig({
  weapp: {
    npm: {
      mainPackage: {
        dependencies: false,
      },
      subPackages: {
        'packages/order': {
          dependencies: [/^tdesign-miniprogram/, 'dayjs'],
        },
        'packages/member': {
          dependencies: ['@scope/member-sdk'],
        },
      },
    },
  },
})
```

适用场景：

* 想把只被独立分包使用的依赖留在分包内，减少主包体积。
* 想精确控制不同分包的 `miniprogram_npm` 内容。

## 控制 npm 依赖的压缩与 sourcemap

`weapp.npm` 内部依赖构建默认是：

* `minify: true`
* `sourcemap: false`

如果你希望 `miniprogram_npm` 里的某些包不压缩并生成 sourcemap，可以在 `buildOptions` 中覆写：

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

export default defineConfig({
  weapp: {
    npm: {
      buildOptions(options, { name }) {
        if (name === 'lodash') {
          return {
            ...options,
            build: {
              ...options.build,
              minify: false,
              sourcemap: true,
            },
          }
        }
        return options
      },
    },
  },
})
```

> \[!NOTE]
> `build.minify/build.sourcemap` 只影响你的主项目产物；\
> `weapp.npm.buildOptions` 用于控制 `miniprogram_npm` 依赖包的构建行为。

## 手动构建命令

如需在命令行触发开发者工具的 npm 构建：

```json
{
  "scripts": {
    "build:npm": "weapp-vite build:npm",
    "npm": "weapp-vite npm"
  }
}
```

> \[!NOTE]
> 该命令依赖 **weapp-ide-cli**，请确保微信开发者工具已开启“服务端口”。

## 常见问题

* **npm 构建内容未更新**：尝试将 `cache` 设为 `false`，或清理 `node_modules/weapp-vite/.cache/`。
* **分包体积过大**：使用 `weapp.npm.mainPackage.dependencies` 和 `weapp.npm.subPackages.<root>.dependencies` 精确控制依赖落位。
* **支付宝平台下 npm 目录不符合预期**：检查 `weapp.npm.alipayNpmMode`，默认是 `node_modules` 而不是 `miniprogram_npm`。

***

下一步：需要分包能力？请前往 [分包配置](./subpackages.md)。

---

---
url: /guide/directory-structure/package-json.md
description: 项目脚本与依赖入口，通常承载 dev、build、open 等 weapp-vite 命令。
---

# `package.json`

`package.json` 不负责页面扫描，但它是项目工作流的入口。

## 通常会放什么

* `dev`
* `build`
* `open`
* `analyze`

```json
{
  "scripts": {
    "dev": "weapp-vite dev",
    "build": "weapp-vite build",
    "open": "weapp-vite open"
  }
}
```

## 为什么目录结构页要提它

因为它和 `vite.config.ts` 一起构成了项目根目录的最小工程化入口。
如果别人接手你的项目，通常先看这两个文件。

---

---
url: /guide/directory-structure/pages.md
description: 主包页面目录，是自动路由的默认扫描入口之一。
---

# `pages/`

这是主包页面目录，也是自动路由的默认扫描入口之一。

## 默认扫描规则

开启 `weapp.autoRoutes` 后，默认只扫描：

* `<srcRoot>/pages/**`
* 已声明分包 root 下的 `pages/**`

不会直接扫描全局 `**/pages/**`。

## 这样设计的原因

为了避免误伤，例如这些目录不应该被当成页面：

* `<srcRoot>/components/pages/**`
* `<srcRoot>/features/demo/pages/**`

## 页面目录的常见形态

```text
<srcRoot>/
  pages/
    profile/
      index.ts
      index.wxml
      index.json
      index.scss
```

或：

```text
<srcRoot>/
  pages/
    profile/
      index.vue
      index.json
```

## 识别规则

只要命中页面扫描规则，并且同一路径下存在脚本、模板、配置之一，就可以被识别成页面；但如果 `json.component === true`，则会被视为组件。

---

---
url: /guide/directory-structure/project-config.md
description: 微信开发者工具项目配置文件，定义 miniprogramRoot、appid 等平台侧参数。
---

# `project.config.json`

这是微信开发者工具项目配置，不属于 `weapp-vite` 的目录约定能力本身，但它决定开发者工具怎样打开和编译你的项目。

## 常见职责

* 指定 `miniprogramRoot`
* 保存 `appid`
* 控制开发者工具的编译选项

## 与目录结构的关系

最常见的一点是：它通常需要把 `miniprogramRoot` 指向 `dist/`，因为 `weapp-vite` 的源码目录和最终小程序运行目录不是同一个位置。

```json
{
  "miniprogramRoot": "dist/",
  "compileType": "miniprogram"
}
```

如果你发现开发者工具打开后目录不对、页面不出现，先检查这里。

---

---
url: /guide/directory-structure/public.md
description: 构建时原样复制到产物目录的静态资源目录。
---

# `public/`

`public/` 用来放不需要参与模块依赖分析的静态资源。

## 适合放这里的内容

* 图标
* 纯静态配置
* 需要按原文件名复制的资源

## 不适合放这里的内容

* 页面
* 组件
* 想通过 `import` 参与构建处理的资源

它不会被自动路由扫描，也不会被自动导入组件扫描。

---

---
url: /wevu/api-reference/reactivity.md
description: 本页覆盖 Wevu 响应式层的公共 API，聚焦业务可直接使用的能力。
---

# Reactivity API（响应式与调度）

本页覆盖 `wevu` 响应式层的公共 API，聚焦业务可直接使用的能力。

## 1. 状态创建与派生

| API               | 类型入口                              | 说明                        |
| ----------------- | ------------------------------------- | --------------------------- |
| `ref`             | `Ref`                                 | 创建基础响应式引用。        |
| `reactive`        | `object`                              | 创建深层响应式对象。        |
| `shallowRef`      | `ShallowRef`                          | 只追踪 `.value` 变更。      |
| `shallowReactive` | `object`                              | 仅顶层属性响应式。          |
| `readonly`        | `Readonly<T>`                         | 只读代理。                  |
| `computed`        | `ComputedRef` / `WritableComputedRef` | 声明计算属性（只读/可写）。 |

## 2. 监听与副作用

| API               | 类型入口                           | 说明                       |
| ----------------- | ---------------------------------- | -------------------------- |
| `watch`           | `WatchOptions` / `WatchStopHandle` | 侦听 source 变化。         |
| `watchEffect`     | `WatchStopHandle`                  | 自动收集依赖并执行副作用。 |
| `effect`          | `WatchStopHandle`                  | 底层副作用 API。           |
| `effectScope`     | `EffectScope`                      | 作用域级管理 effect。      |
| `getCurrentScope` | `EffectScope`                      | 获取当前 effect scope。    |
| `onScopeDispose`  | `() => void`                       | scope 销毁时回调。         |
| `stop`            | `void`                             | 停止某个 effect/watch。    |

## 3. Ref/Proxy 工具

| API          | 类型入口           | 说明                       |
| ------------ | ------------------ | -------------------------- |
| `toRef`      | `Ref`              | 把对象属性转换为 ref。     |
| `toRefs`     | `ToRefs`           | 批量转换对象属性为 ref。   |
| `unref`      | `T`                | 取 ref.value 或原值。      |
| `toValue`    | `MaybeRefOrGetter` | 统一展开值/Ref/getter。    |
| `triggerRef` | `void`             | 手动触发 shallowRef 更新。 |
| `toRaw`      | `T`                | 获取原始对象。             |
| `markRaw`    | `T`                | 标记对象跳过代理。         |

## 4. 响应式判定

| API                 | 类型入口       | 说明                       |
| ------------------- | -------------- | -------------------------- |
| `isRef`             | type predicate | 判定是否 Ref。             |
| `isReactive`        | type predicate | 判定是否 reactive 代理。   |
| `isShallowRef`      | type predicate | 判定是否 shallowRef。      |
| `isShallowReactive` | type predicate | 判定是否 shallowReactive。 |
| `isRaw`             | `boolean`      | 判定对象是否被 `markRaw`。 |

## 5. 批处理与调度

| API          | 类型入口        | 说明                     |
| ------------ | --------------- | ------------------------ |
| `nextTick`   | `Promise<void>` | 等待当前微任务批次完成。 |
| `batch`      | `() => void`    | 在单次批处理中执行函数。 |
| `startBatch` | `void`          | 手动开始批处理。         |
| `endBatch`   | `void`          | 手动结束批处理。         |

## 6. 内部能力说明

`wevu` 在响应式实现里存在少量内部能力，用于框架运行时与测试场景；这些接口不属于业务稳定 API，不建议在应用代码中直接调用。

## 7. 组合示例（script setup）

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { computed, nextTick, reactive, toRefs, watch, watchEffect } from 'wevu'

// [TS-only] 此示例无专属语法，TS/JS 写法一致。
const state = reactive({ count: 0, unit: 2 })
const { count } = toRefs(state)
const doubled = computed(() => count.value * state.unit)

watch(count, (n) => {
  console.log('count changed:', n)
})

watchEffect(() => {
  console.log('preview:', doubled.value)
})

async function inc() {
  count.value += 1
  await nextTick()
}
</script>

<template>
  <button @tap="inc">
    count: {{ count }} / doubled: {{ doubled }}
  </button>
</template>
```

```vue [JavaScript]
<script setup>
import { computed, nextTick, reactive, toRefs, watch, watchEffect } from 'wevu'

const state = reactive({ count: 0, unit: 2 })
const { count } = toRefs(state)
const doubled = computed(() => count.value * state.unit)

watch(count, (n) => {
  console.log('count changed:', n)
})

watchEffect(() => {
  console.log('preview:', doubled.value)
})

async function inc() {
  count.value += 1
  await nextTick()
}
</script>

<template>
  <button @tap="inc">
    count: {{ count }} / doubled: {{ doubled }}
  </button>
</template>
```

:::

---

---
url: /wevu/api/reactivity.md
description: 本页覆盖 Wevu 响应式层的全部公开函数，包括状态创建、监听副作用、工具函数与调度能力。
---

# Reactivity API（响应式与调度）

本页按「一个 API 一个小节」组织，结构参考 Vue 官方 API 文档。每个小节都包含用途、类型入口与使用建议，便于快速定位与深入阅读。

## 状态创建与派生

### `ref()` {#ref}

* 类型入口：`Ref<T>`
* 用途：创建最常用的基础响应式引用，适合原始值或独立状态。
* 说明：读取使用 `ref.value`；在模板中会自动解包。

### `customRef()` {#customref}

* 类型入口：`CustomRefFactory<T>` / `CustomRefOptions<T>`
* 用途：自定义 `track/trigger` 行为。
* 说明：适合防抖输入、手动控制触发时机等高级场景。

### `reactive()` {#reactive}

* 类型入口：`object`
* 用途：创建深层响应式对象，适合聚合状态。
* 说明：对嵌套对象也会做代理；适合表单、复杂页面状态。

### `shallowRef()` {#shallowref}

* 类型入口：`ShallowRef<T>`
* 用途：只追踪 `.value` 本身是否变更，不做深层代理。
* 说明：用于大对象/第三方实例，减少深层响应式开销。

### `shallowReactive()` {#shallowreactive}

* 类型入口：`object`
* 用途：仅顶层属性响应式，内部对象保持原值。
* 说明：常用于“只关心顶层替换”的场景。

### `readonly()` {#readonly}

* 类型入口：`Readonly<T>`
* 用途：创建只读代理，防止误修改。
* 说明：常用于向下游暴露状态快照。

### `computed()` {#computed}

* 类型入口：`ComputedRef<T>` / `WritableComputedRef<T>`
* 用途：声明派生状态，自动缓存并按依赖更新。
* 说明：支持只读与可写两种形式；优先用于“纯函数派生”。

## 监听与副作用

### `watch()` {#watch}

* 类型入口：`WatchOptions` / `WatchStopHandle`
* 用途：侦听 source 变化并执行回调。
* 说明：适合精确观察某个字段、computed 或 getter。

### `watchEffect()` {#watcheffect}

* 类型入口：`WatchStopHandle`
* 用途：自动收集依赖并立即执行副作用。
* 说明：适合快速联动逻辑与调试输出。

### `effect()` {#effect}

* 类型入口：`WatchStopHandle`
* 用途：底层副作用 API，通常框架层/高级场景使用。
* 说明：业务代码优先使用 `watchEffect`。

### `effectScope()` {#effectscope}

* 类型入口：`EffectScope`
* 用途：把一组 effect/watch 放在同一作用域统一管理。
* 说明：在组件外组合逻辑、插件场景很有用。

### `getCurrentScope()` {#getcurrentscope}

* 类型入口：`EffectScope | undefined`
* 用途：获取当前激活的 effect scope。
* 说明：常与 `onScopeDispose` 配合使用。

### `onScopeDispose()` {#onscopedispose}

* 类型入口：`() => void`
* 用途：在 scope 销毁时执行清理逻辑。
* 说明：适合解绑事件、释放资源。

### `stop()` {#stop}

* 类型入口：`void`
* 用途：停止指定 effect/watch。
* 说明：用于手动中断监听链路。

## Ref / Proxy 工具

### `toRef()` {#toref}

* 类型入口：`Ref<T>`
* 用途：把对象某个属性映射为 ref。
* 说明：常用于解构后保持响应式引用。

### `toRefs()` {#torefs}

* 类型入口：`ToRefs<T>`
* 用途：批量把对象属性转换为 ref。
* 说明：适合从 `reactive` 安全解构。

### `unref()` {#unref}

* 类型入口：`T`
* 用途：统一读取 `ref.value` 或普通值。
* 说明：减少“值/Ref 双形态”判断分支。

### `toValue()` {#tovalue}

* 类型入口：`MaybeRefOrGetter<T>`
* 用途：统一展开普通值、Ref 或 getter。
* 说明：编写可复用工具函数时很常见。

### `triggerRef()` {#triggerref}

* 类型入口：`void`
* 用途：手动触发 `shallowRef` 依赖更新。
* 说明：用于“对象内部变更但引用未变”场景。

### `toRaw()` {#toraw}

* 类型入口：`T`
* 用途：拿到代理前的原始对象。
* 说明：调试或与第三方库交互时使用。

### `markRaw()` {#markraw}

* 类型入口：`T`
* 用途：标记对象跳过响应式代理。
* 说明：适用于大型类实例、SDK 对象。

## 响应式判定

### `isRef()` {#isref}

* 类型入口：type predicate
* 用途：判断某值是否为 Ref。

### `isReactive()` {#isreactive}

* 类型入口：type predicate
* 用途：判断对象是否是 `reactive` 代理。

### `isShallowRef()` {#isshallowref}

* 类型入口：type predicate
* 用途：判断是否为 `shallowRef`。

### `isShallowReactive()` {#isshallowreactive}

* 类型入口：type predicate
* 用途：判断是否为 `shallowReactive`。

### `isRaw()` {#israw}

* 类型入口：`boolean`
* 用途：判断对象是否被 `markRaw` 标记。

## 批处理与调度

### `nextTick()` {#nexttick}

* 类型入口：`Promise<void>`
* 用途：等待当前批次响应式更新完成。
* 说明：常用于更新后读取最新渲染状态。

### `batch()` {#batch}

* 类型入口：`() => void`
* 用途：在同一批处理中执行一组状态改动。
* 说明：减少中间态触发的无效计算与更新。

### `startBatch()` {#startbatch}

* 类型入口：`void`
* 用途：手动开启批处理。
* 说明：需要与 `endBatch` 成对调用。

### `endBatch()` {#endbatch}

* 类型入口：`void`
* 用途：手动结束批处理并触发提交。

## 内部能力说明

响应式内部调度与调试函数（如 reactive 树预链接、深度策略切换、内部遍历）属于框架内部能力，文档页不再展开展示。若你在业务侧需要类似能力，建议优先使用本页已列出的公开 API 组合实现。

## 示例

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { computed, nextTick, reactive, toRefs, watch, watchEffect } from 'wevu'

const state = reactive({ count: 0, unit: 2 })
const { count } = toRefs(state)
const doubled = computed(() => count.value * state.unit)

watch(count, (n) => {
  console.log('count changed:', n)
})

watchEffect(() => {
  console.log('preview:', doubled.value)
})

async function inc() {
  count.value += 1
  await nextTick()
}
</script>

<template>
  <button @tap="inc">
    count: {{ count }} / doubled: {{ doubled }}
  </button>
</template>
```

```vue [JavaScript]
<script setup>
import { computed, nextTick, reactive, toRefs, watch, watchEffect } from 'wevu'

const state = reactive({ count: 0, unit: 2 })
const { count } = toRefs(state)
const doubled = computed(() => count.value * state.unit)

watch(count, (n) => {
  console.log('count changed:', n)
})

watchEffect(() => {
  console.log('preview:', doubled.value)
})

async function inc() {
  count.value += 1
  await nextTick()
}
</script>

<template>
  <button @tap="inc">
    count: {{ count }} / doubled: {{ doubled }}
  </button>
</template>
```

:::

---

---
url: /packages/rolldown-require.md
description: >-
  rolldown-require bundles and then loads config files of any flavor (TS / MJS /
  CJS / JSX, etc.) using rolldown, so CLI …
---

# rolldown-require Guide

> Language: English | [中文](/packages/rolldown-require/index.zh)

`rolldown-require` bundles and then loads config files of any flavor (TS / MJS / CJS / JSX, etc.) using `rolldown`, so CLI tools or Node scripts can execute them safely. Its API mirrors `bundle-require` while reusing `rolldown` resolution and plugins to stay close to `rolldown-vite` runtime behaviour.

## What problems it solves

* **Cross-format loading**: infers entry module type automatically and works with ESM/CJS/TypeScript and more.
* **Consistent resolution**: follows Vite/rolldown resolution and externalization (including `module-sync`), avoiding require/import mismatches.
* **Source context preserved**: restores `__dirname`, `__filename`, and `import.meta.url` after bundling so temp output matches the source path.
* **Observable dependencies**: returns the dependency list from bundling, ready for watchers or cache validation.
* **Optional caching**: built-in persistent + in-memory cache to speed up repeated config loads.

## Install

```sh
pnpm add rolldown-require rolldown -D
# or npm / yarn / bun
```

> `rolldown` is a peer dependency and must be installed alongside.

## Quick start

```ts
import { bundleRequire } from 'rolldown-require'

const { mod, dependencies } = await bundleRequire({
  filepath: './vite.config.ts',
  cache: true, // optional: enable cache for faster reruns
})

// mod is the executed module (default export is unwrapped automatically)
// dependencies can drive a watcher to decide when to re-bundle
```

`bundleRequire` will:

1. Infer ESM/CJS from the entry path (override with `format` if needed).
2. Bundle the entry with `rolldown`, externalizing most `node_modules` to match `rolldown-vite` behaviour.
3. Execute the temp output (ESM via `import()`, CJS via `require`) and return the module plus dependency list.

## How it differs from bundle-require

* Uses `rolldown` as the bundler, matching the ecosystem and respecting conditional exports and module-sync flags.
* Injects file-scope variables so changing the temp output path does not break `__dirname`/`__filename`.
* Supports optional persistent and memory cache to reuse the same bundle across cold and warm starts.

## Next steps

* See [API & options](/packages/rolldown-require/options) for defaults and scenarios.
* Read [Loading flow & cache](/packages/rolldown-require/cache) for externalization details, temp files, and debugging tips.

---

---
url: /packages/rolldown-require/index.zh.md
description: >-
  rolldown-require 是基于 rolldown 的「打包再加载」工具，帮助 CLI 或 Node 脚本安全地执行任意格式的配置文件（ts /
  mjs / cjs / JSX 等）。API 与 bundle-require 保持…
---

# rolldown-require 使用指南

> 语言： [English](/packages/rolldown-require/) | 中文

`rolldown-require` 是基于 `rolldown` 的「打包再加载」工具，帮助 CLI 或 Node 脚本安全地执行任意格式的配置文件（`ts` / `mjs` / `cjs` / JSX 等）。API 与 `bundle-require` 保持相似，却复用了 `rolldown` 的解析与插件生态，更贴近 `rolldown-vite` 的运行时行为。

## 它解决什么问题

* **跨格式加载**：自动判定入口模块类型，支持 ESM/CJS/TypeScript 等多种后缀。
* **一致的解析策略**：沿用 Vite/rolldown 的解析与外部化逻辑（含 `module-sync` 条件），避免 `require`/`import` 行为不一致。
* **源码上下文保持**：在打包后恢复 `__dirname`、`__filename`、`import.meta.url`，让临时产物与源文件路径一致。
* **依赖可观察**：返回打包时命中的依赖列表，可直接用于文件监听或缓存校验。
* **可选缓存**：内置持久化 + 进程内缓存，重复加载配置时可显著缩短启动时间。

## 安装

```sh
pnpm add rolldown-require rolldown -D
# 或 npm / yarn / bun 等等
```

> `rolldown` 是 peer 依赖，需要一同安装。

## 快速开始

```ts
import { bundleRequire } from 'rolldown-require'

const { mod, dependencies } = await bundleRequire({
  filepath: './vite.config.ts',
  cache: true, // 可选：启用缓存，重复执行更快
})

// mod 即为被加载的模块（默认导出会被解包）
// dependencies 可用于 watcher，决定何时重新 bundle
```

`bundleRequire` 会：

1. 基于入口路径推断 ESM/CJS 格式，并支持通过 `format` 手动覆盖。
2. 使用 `rolldown` 打包入口文件，排除大多数 `node_modules` 依赖，保持解析结果与 `rolldown-vite` 一致。
3. 写入临时产物后执行（ESM 用 `import()`，CJS 用 `require`），最终返回模块与依赖列表。

## 和 bundle-require 的区别

* 换用 `rolldown` 作为打包引擎，更贴合 rolldown 生态，也能利用它的条件导出、模块同步标记等能力。
* 内置文件作用域变量注入，避免因为临时产物路径改变而让 `__dirname`/`__filename` 失真。
* 支持可选的持久化/内存缓存，冷启动和多次加载都能复用同一份 bundle。

## 下一步

* 查阅 [API 与选项说明](/packages/rolldown-require/options.zh) 理解各配置项的默认值与适用场景。
* 参考 [加载流程与缓存策略](/packages/rolldown-require/cache.zh) 了解外部化、临时文件与调试技巧。

---

---
url: /wevu/api-reference/runtime-bridge.md
description: 本页覆盖 Wevu 与小程序原生运行时之间的桥接能力，以及用于排错/调优的公共 API。
---

# Runtime Bridge API（桥接与调试）

本页覆盖 Wevu 与小程序原生运行时之间的桥接能力，以及用于排错/调优的公共 API。

## 1. 全局默认值与行为开关

| API                 | 类型入口       | 说明                                        |
| ------------------- | -------------- | ------------------------------------------- |
| `setWevuDefaults`   | `WevuDefaults` | 配置 `createApp/defineComponent` 默认行为。 |
| `resetWevuDefaults` | `void`         | 重置默认值（测试/热更新常用）。             |
| `markNoSetData`     | `T`            | 标记对象不参与 `setData` 快照。             |
| `isNoSetData`       | `boolean`      | 判断对象是否被标记为 no-setData。           |

## 2. 调试与观测

| API                      | 类型入口         | 说明                   | 场景                  |
| ------------------------ | ---------------- | ---------------------- | --------------------- |
| `addMutationRecorder`    | `MutationRecord` | 注册 mutation 记录器。 | 调试 state 变化来源。 |
| `removeMutationRecorder` | `MutationRecord` | 移除 mutation 记录器。 | 测试结束清理。        |

## 3. 编译侧常量（`wevu/compiler`）

`wevu/compiler` 主要给编译工具使用，业务代码不建议直接依赖。

| 常量/类型                    | 链接                         | 说明                            |
| ---------------------------- | ---------------------------- | ------------------------------- |
| `WE_VU_MODULE_ID`            | `WE_VU_MODULE_ID`            | 运行时模块 ID（`wevu`）。       |
| `WE_VU_RUNTIME_APIS`         | `WE_VU_RUNTIME_APIS`         | 编译器识别的运行时 API 名单。   |
| `WE_VU_PAGE_HOOK_TO_FEATURE` | `WE_VU_PAGE_HOOK_TO_FEATURE` | 页面 hook 与 feature 标记映射。 |
| `WevuRuntimeApiName`         | `WevuRuntimeApiName`         | 运行时 API 名称联合类型。       |
| `WevuPageHookName`           | `WevuPageHookName`           | 页面 hook 名称联合类型。        |
| `WevuPageFeatureFlag`        | `WevuPageFeatureFlag`        | 页面 feature 标记联合类型。     |

## 4. 示例：默认值 + mutation 记录（script setup）

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import {
  addMutationRecorder,
  onUnmounted,
  ref,
  removeMutationRecorder,
  setWevuDefaults,
} from 'wevu'

setWevuDefaults({
  component: {
    options: {
      addGlobalClass: true,
    },
  },
})

const count = ref(0)
// [TS-only] 参数类型注解仅支持 lang="ts"
function recorder(record: any) {
  console.log('mutation:', record.path, record.type)
}

addMutationRecorder(recorder)

function inc() {
  count.value += 1
}

onUnmounted(() => {
  removeMutationRecorder(recorder)
})
</script>

<template>
  <button @tap="inc">
    count: {{ count }}
  </button>
</template>
```

```vue [JavaScript]
<script setup>
import {
  addMutationRecorder,
  onUnmounted,
  ref,
  removeMutationRecorder,
  setWevuDefaults,
} from 'wevu'

setWevuDefaults({
  component: {
    options: {
      addGlobalClass: true,
    },
  },
})

const count = ref(0)
function recorder(record) {
  console.log('mutation:', record.path, record.type)
}

addMutationRecorder(recorder)

function inc() {
  count.value += 1
}

onUnmounted(() => {
  removeMutationRecorder(recorder)
})
</script>

<template>
  <button @tap="inc">
    count: {{ count }}
  </button>
</template>
```

:::

---

---
url: /wevu/api/runtime-bridge.md
description: 本页仅展示面向业务与配置层的 Wevu 运行时 API。框架内部桥接函数不会在文档中展开。
---

# Runtime Bridge API（运行时配置）

本页聚焦可在业务工程中直接使用的运行时能力。内部注册与调度函数已从文档目录中移除。

## 全局默认值

### `setWevuDefaults()` {#setwevudefaults}

* 类型入口：`WevuDefaults`
* 用途：配置 `createApp/defineComponent` 的默认行为。

### `resetWevuDefaults()` {#resetwevudefaults}

* 类型入口：`void`
* 用途：重置默认配置。
* 场景：测试隔离、开发调试。

## setData 排除标记

### `markNoSetData()` {#marknosetdata}

* 类型入口：`<T>(value: T) => T`
* 用途：标记对象不参与 `setData` 快照同步。

### `isNoSetData()` {#isnosetdata}

* 类型入口：`boolean`
* 用途：判断对象是否被标记为 no-setData。

## 调试记录

### `addMutationRecorder()` {#addmutationrecorder}

* 类型入口：`MutationRecord`
* 用途：注册状态 mutation 记录器。

### `removeMutationRecorder()` {#removemutationrecorder}

* 类型入口：`MutationRecord`
* 用途：移除状态 mutation 记录器。

## 示例

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import {
  addMutationRecorder,
  onUnmounted,
  ref,
  removeMutationRecorder,
  setWevuDefaults,
} from 'wevu'

setWevuDefaults({
  component: {
    options: {
      addGlobalClass: true,
    },
  },
})

const count = ref(0)

function recorder(record: any) {
  console.log('mutation:', record.path, record.type)
}

addMutationRecorder(recorder)

onUnmounted(() => {
  removeMutationRecorder(recorder)
})
</script>

<template>
  <button @tap="count += 1">
    count: {{ count }}
  </button>
</template>
```

```vue [JavaScript]
<script setup>
import {
  addMutationRecorder,
  onUnmounted,
  ref,
  removeMutationRecorder,
  setWevuDefaults,
} from 'wevu'

setWevuDefaults({
  component: {
    options: {
      addGlobalClass: true,
    },
  },
})

const count = ref(0)

function recorder(record) {
  console.log('mutation:', record.path, record.type)
}

addMutationRecorder(recorder)

onUnmounted(() => {
  removeMutationRecorder(recorder)
})
</script>

<template>
  <button @tap="count += 1">
    count: {{ count }}
  </button>
</template>
```

:::

---

---
url: /guide/seo-governance.md
description: 说明 Weapp-vite 文档站的 SEO/GEO 自动化治理流程，包括审计、质量检查、llms 索引生成与 CI 严格门禁。
---

# SEO/GEO 质量门禁

本文档说明文档站的 SEO（传统搜索可见性）与 GEO（Generative Engine Optimization，生成式引擎优化）治理策略，目标是保证内容在搜索引擎和大模型检索场景下都可持续演进。

## 核心命令

* `pnpm seo-audit`
  * 输出覆盖率审计（title/description/keywords/date）和站点策略完整度。
* `pnpm seo-audit:strict`
  * 按阈值执行严格检查，不达标直接失败。
* `pnpm seo-quality-check`
  * 检查模板化描述、过短描述、关键词不足、关键词未标准化等问题。
* `pnpm seo:quality:strict`
  * CI 门禁命令，要求质量问题为 `0`。
* `pnpm seo-quality-report`
  * 生成 `website/public/seo-quality-report.json`。
* `pnpm seo-generate-llms-index`
  * 生成 `website/public/llms-index.json`。

## 构建接入

`website/package.json` 的 `build` 会先执行：

```bash
pnpm -w seo:prepare
```

该命令会生成以下产物：

* `/llms-index.json`
* `/seo-quality-report.json`

随后再进行 `vitepress build`，确保构建产物与当前文档内容同步。

## CI 门禁

PR 流程中的 `CI Policy` 已接入：

```bash
pnpm seo:quality:strict
```

只要出现描述模板化、关键词不规范或覆盖缺失等问题，门禁会直接失败，从而阻止质量回归。

## frontmatter 自动治理约束

* 自动补齐默认跳过 `_*.md` / `_*.mdx`（partial 文档）。
* 兼容历史裸 YAML 头（无 `---` 包裹）文档，避免改写破坏构建。
* 关键词统一去噪、去重、限长，并转为可维护的标准词形。

---

---
url: /wevu/api-reference/setup-context.md
description: >-
  Wevu 的 setup(props, ctx) 除了 Vue 语义，还补齐了小程序运行时场景，特别是 ctx.instance（原生实例）和
  ctx.emit（事件派发）。
---

# Setup Context API（setup 上下文）

`wevu` 的 `setup(props, ctx)` 除了 Vue 语义，还补齐了小程序运行时场景，特别是 `ctx.instance`（原生实例）和 `ctx.emit`（事件派发）。

## 1. `setup` 签名与核心类型

| 类型/接口           | 链接                  | 说明                                         |
| ------------------- | --------------------- | -------------------------------------------- |
| `setup(props, ctx)` | `SetupFunction`       | 组件/页面 setup 函数签名。                   |
| `ctx`               | `SetupContext`        | setup 上下文总入口。                         |
| `ctx.runtime`       | `RuntimeInstance`     | 运行时实例（watch、snapshot、teardown 等）。 |
| `ctx.instance`      | `MiniProgramInstance` | 小程序原生实例。                             |
| `ctx.emit`          | `TriggerEventOptions` | 自定义事件派发入口。                         |

## 2. setup 上下文相关 API

| API                      | 类型入口          | 说明                     |
| ------------------------ | ----------------- | ------------------------ |
| `getCurrentInstance`     | `RuntimeInstance` | 获取当前运行时实例。     |
| `getCurrentSetupContext` | `SetupContext`    | 获取当前 setup context。 |

## 3. provide/inject

| API       | 类型入口               | 说明                   |
| --------- | ---------------------- | ---------------------- |
| `provide` | `InjectionKey<T>` 兼容 | 在当前组件树提供依赖。 |
| `inject`  | `T \| undefined`       | 从当前组件树读取依赖。 |

## 4. 推荐：通过 `ctx.instance` 操作原生实例

在 Wevu 里，和小程序实例直接耦合的方法，推荐放在 `ctx.instance` 上调用，而不是依赖 `this`：

* `ctx.instance.triggerEvent(...)`
* `ctx.instance.createSelectorQuery()`
* `ctx.instance.createIntersectionObserver(...)`
* `ctx.instance.setData(...)`
* `ctx.instance.router` / `ctx.instance.pageRouter`（基础库 `2.16.1+`）
* 以及平台原生 `wx` 组件实例 API

### 示例（script setup）

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { getCurrentSetupContext, provide, ref } from 'wevu'

// [TS-only] 此示例无专属语法，TS/JS 写法一致。
const visible = ref(false)
provide('featureFlag', 'ctx-instance-demo')

function open() {
  const ctx = getCurrentSetupContext()
  visible.value = true
  ctx?.emit('open', { ok: true })
  ctx?.instance?.triggerEvent?.('opened', { ts: Date.now() })
}

function measure() {
  const ctx = getCurrentSetupContext()
  const query = ctx?.instance?.createSelectorQuery?.()
  query?.select('#target').boundingClientRect()
  query?.exec(console.log)
}

function watchBanner() {
  const ctx = getCurrentSetupContext()
  const observer = ctx?.instance?.createIntersectionObserver?.({ thresholds: [0, 1] })
  observer?.relativeToViewport().observe('#target', console.log)
}

function patchRaw() {
  const ctx = getCurrentSetupContext()
  ctx?.instance?.setData?.({ rawFlag: true })
}
</script>

<template>
  <view id="target" @tap="open">
    open: {{ visible }}
  </view>
  <button @tap="measure">
    measure
  </button>
  <button @tap="watchBanner">
    watchBanner
  </button>
  <button @tap="patchRaw">
    patchRaw
  </button>
</template>
```

```vue [JavaScript]
<script setup>
import { getCurrentSetupContext, provide, ref } from 'wevu'

const visible = ref(false)
provide('featureFlag', 'ctx-instance-demo')

function open() {
  const ctx = getCurrentSetupContext()
  visible.value = true
  ctx?.emit('open', { ok: true })
  ctx?.instance?.triggerEvent?.('opened', { ts: Date.now() })
}

function measure() {
  const ctx = getCurrentSetupContext()
  const query = ctx?.instance?.createSelectorQuery?.()
  query?.select('#target').boundingClientRect()
  query?.exec(console.log)
}

function watchBanner() {
  const ctx = getCurrentSetupContext()
  const observer = ctx?.instance?.createIntersectionObserver?.({ thresholds: [0, 1] })
  observer?.relativeToViewport().observe('#target', console.log)
}

function patchRaw() {
  const ctx = getCurrentSetupContext()
  ctx?.instance?.setData?.({ rawFlag: true })
}
</script>

<template>
  <view id="target" @tap="open">
    open: {{ visible }}
  </view>
  <button @tap="measure">
    measure
  </button>
  <button @tap="watchBanner">
    watchBanner
  </button>
  <button @tap="patchRaw">
    patchRaw
  </button>
</template>
```

:::

## 5. 双向绑定辅助

| API            | 类型入口                               | 说明                                      |
| -------------- | -------------------------------------- | ----------------------------------------- |
| `useBindModel` | `ModelBindingOptions` / `ModelBinding` | 生成小程序可直接绑定的数据 + 事件处理器。 |

## 5.1 路由辅助

| API             | 类型入口 | 说明                                                                                                                                                                                                     |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useRouter`     | `Router` | 获取组件路径语义 Router。优先 `this.router`，再回退 `this.pageRouter`，低版本基础库降级到全局 `wx/my/tt`；可通过 `WevuTypedRouterRouteMap.entries` 收窄 `url`，并可用 `tabBarEntries` 收窄 `switchTab`。 |
| `usePageRouter` | `Router` | 获取页面路径语义 Router。优先 `this.pageRouter`，再回退 `this.router`，低版本基础库降级到全局 `wx/my/tt`；可通过 `WevuTypedRouterRouteMap.entries` 收窄 `url`，并可用 `tabBarEntries` 收窄 `switchTab`。 |

### 5.1.1 Router 语义矩阵

Router 原生对象从微信基础库 `2.16.1+` 可用。`wevu` 会按顺序做能力回退，因此建议你在设计路由 API 时明确“语义优先级”：

| 调用位置           | `useRouter()` 基准         | `usePageRouter()` 基准     |
| ------------------ | -------------------------- | -------------------------- |
| 页面 `setup()`     | 页面路径                   | 页面路径                   |
| 组件 `setup()`     | 组件路径                   | 组件所在页面路径           |
| 低版本全局回退场景 | 当前激活页（全局路由对象） | 当前激活页（全局路由对象） |

### 5.1.2 兼容建议

* 需要跨版本基路径稳定时，优先 `usePageRouter()`。
* 只在“组件目录相对路径”是业务需求时使用 `useRouter()`。
* 对低版本必须一致的路由，优先绝对路径（`/pages/**`、`/packageA/pages/**`）。

## 5.2 可见性监听辅助

| API                       | 类型入口               | 说明                                                            |
| ------------------------- | ---------------------- | --------------------------------------------------------------- |
| `useIntersectionObserver` | `IntersectionObserver` | setup 内创建观察器，自动在 `onUnload/onDetached` 阶段断开连接。 |

## 6. 相关页

* 生命周期与页面事件：[/wevu/api-reference/lifecycle](/wevu/api-reference/lifecycle)
* 运行时桥接与调试：[/wevu/api-reference/runtime-bridge](/wevu/api-reference/runtime-bridge)

---

---
url: /wevu/api/setup-context.md
description: >-
  本页严格对应 wevu 源码中的 setup
  上下文相关导出（runtime/hooks.ts、runtime/provide.ts、runtime/register.ts、runtime/vueCompat.ts）。
---

# Setup Context API（setup 上下文）

`setup(props, ctx)` 的字段语义来自 `SetupContext` 类型；本页重点列出可直接导入调用的公开 API。

`ctx` 常见字段（类型定义语义）：

* `ctx.runtime`：当前 `RuntimeInstance`
* `ctx.instance`：原生小程序实例
* `ctx.emit`：事件派发函数

## 实例与上下文访问 API

### `getCurrentInstance()` {#getcurrentinstance}

* 用途：获取当前运行时实例。
* 源码：`runtime/hooks.ts`。

### `getCurrentSetupContext()` {#getcurrentsetupcontext}

* 用途：获取当前 setup context。
* 源码：`runtime/hooks.ts`。

## 依赖注入 API

### `provide()` {#provide}

* 用途：在当前组件树提供依赖。
* 源码：`runtime/provide.ts`。

### `inject()` {#inject}

* 用途：从上层读取依赖。
* 源码：`runtime/provide.ts`。

## Setup 兼容工具 API

### `useNativeInstance()` {#usenativeinstance}

* 用途：获取当前 setup 对应的原生实例。
* 源码：`runtime/vueCompat.ts`。

### `useRouter()` {#userouter}

* 用途：获取当前组件路径语义的 Router 对象。
* 行为：优先使用 `this.router`；不可用时回退 `this.pageRouter`；低版本基础库（`< 2.16.1`）再回退全局路由方法（`wx`/`my`/`tt`）。
* 类型：可通过声明合并 `WevuTypedRouterRouteMap.entries` 收窄 `url` 字面量；可选 `tabBarEntries` 进一步收窄 `switchTab`（`weapp-vite autoRoutes` 会自动注入 `entries`）。
* 源码：`runtime/vueCompat.ts`。

### `usePageRouter()` {#usepagerouter}

* 用途：获取当前页面路径语义的 Router 对象。
* 行为：优先使用 `this.pageRouter`；不可用时回退 `this.router`；低版本基础库（`< 2.16.1`）再回退全局路由方法（`wx`/`my`/`tt`）。
* 类型：与 `useRouter()` 共享 `WevuTypedRouterRouteMap.entries / tabBarEntries` 收窄能力。
* 源码：`runtime/vueCompat.ts`。

### Router 语义与兼容建议

`Router` 能力在微信基础库 `2.16.1+` 才有原生对象。`wevu` 在低版本会自动降级到全局路由方法，所以建议你明确区分“路径语义”与“兼容语义”。

| 场景           | 推荐 API          | 相对路径基准                               |
| -------------- | ----------------- | ------------------------------------------ |
| 页面内跳转     | `usePageRouter()` | 当前页面路径（更稳定）                     |
| 组件内组件路径 | `useRouter()`     | 当前组件路径                               |
| 组件内页面路径 | `usePageRouter()` | 组件所在页面路径                           |
| 低版本降级路径 | 自动回退          | 回退为全局 `wx/my/tt` 语义（按当前激活页） |

**实践建议：**

* 需要跨版本稳定时，优先使用 `usePageRouter()`（尤其是页面方法被延迟调用、跨页调用时）。
* 当你明确要“相对组件目录”导航时，使用 `useRouter()`。
* 对低版本必须严格一致的跳转，优先使用绝对路径（如 `/pages/foo/index`），避免依赖相对路径基准。
* 若开启 `autoRoutes`，可结合路由联合类型减少拼写错误（见 `/guide/auto-routes`）。

### `useBindModel()` {#usebindmodel}

* 用途：创建绑定 payload（`value + onXxx`）辅助函数。
* 源码：`runtime/vueCompat.ts`。

### `useIntersectionObserver()` {#useintersectionobserver}

* 用途：在 `setup()` 中创建 `IntersectionObserver`，并在卸载时自动 `disconnect()`。
* 建议：优先用它替代 `onPageScroll + setData` 的可见性轮询逻辑。
* 源码：`runtime/intersectionObserver.ts`。

## 示例

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { getCurrentSetupContext, provide, ref, useBindModel, useNativeInstance } from 'wevu'

const visible = ref(false)
const model = useBindModel({
  prop: 'modelValue',
  event: 'update:modelValue',
})

provide('featureFlag', 'ctx-instance-demo')

function open() {
  const ctx = getCurrentSetupContext()
  const instance = useNativeInstance()
  visible.value = true
  model.setValue?.(true)
  ctx?.emit('open', { ok: true })
  instance.triggerEvent?.('opened', { ts: Date.now() })
}
</script>

<template>
  <view id="target" @tap="open">
    open: {{ visible }}
  </view>
</template>
```

```vue [JavaScript]
<script setup>
import { getCurrentSetupContext, provide, ref, useBindModel, useNativeInstance } from 'wevu'

const visible = ref(false)
const model = useBindModel({
  prop: 'modelValue',
  event: 'update:modelValue',
})

provide('featureFlag', 'ctx-instance-demo')

function open() {
  const ctx = getCurrentSetupContext()
  const instance = useNativeInstance()
  visible.value = true
  model.setValue?.(true)
  ctx?.emit('open', { ok: true })
  instance.triggerEvent?.('opened', { ts: Date.now() })
}
</script>

<template>
  <view id="target" @tap="open">
    open: {{ visible }}
  </view>
</template>
```

:::

### IntersectionObserver 示例

```vue
<script setup lang="ts">
import { ref, useIntersectionObserver } from 'wevu'

const visible = ref(false)
const io = useIntersectionObserver({ thresholds: [0, 0.5, 1] })

io
  .relativeToViewport({ bottom: 0 })
  .observe('#ad-banner', (res) => {
    visible.value = !!res?.intersectionRatio && res.intersectionRatio > 0
  })
</script>

<template>
  <view id="ad-banner">
    banner visible: {{ visible }}
  </view>
</template>
```

### Router 示例

```vue
<script setup lang="ts">
import type { AutoRoutes } from 'weapp-vite/auto-routes'
import { usePageRouter, useRouter } from 'wevu'

const router = useRouter()
const pageRouter = usePageRouter()
type RouteEntry = AutoRoutes['entries'][number]

function gotoFromComponent() {
  // 组件路径语义：在自定义组件中通常相对组件目录
  router.navigateTo({ url: './detail' })
}

function gotoFromPage() {
  // 页面路径语义：相对页面目录，更适合稳定基路径场景
  pageRouter.navigateTo({ url: './detail' })
}

function gotoStable(route: RouteEntry) {
  // 低版本兼容要求高时，优先绝对路径
  pageRouter.navigateTo({ url: route })
}
</script>

<template>
  <button @tap="gotoFromComponent">
    component router
  </button>
  <button @tap="gotoFromPage">
    page router
  </button>
</template>
```

---

---
url: /guide/directory-structure/shared.md
description: 跨主包与分包共享模块的推荐目录。
---

# `shared/`

`shared/` 不是框架保留目录，但它是很推荐的共享层位置。

## 适合放什么

* 共享样式
* 常量
* 类型
* 请求层封装
* 跨包复用的 composable / helper

## 为什么它常见

因为页面、组件、分包都容易不断增长，提前给共享代码一个稳定位置，长期维护成本会更低。

---

---
url: /wevu/api-reference/store.md
description: Wevu 的 store 设计接近 Pinia：defineStore 定义，createStore 创建管理器，storeToRefs 安全解构。
---

# Store API（状态管理）

`wevu` 的 store 设计接近 Pinia：`defineStore` 定义，`createStore` 创建管理器，`storeToRefs` 安全解构。

## 1. 核心函数

| API           | 类型入口             | 说明                                    |
| ------------- | -------------------- | --------------------------------------- |
| `defineStore` | `DefineStoreOptions` | 定义 store（setup/option 两种风格）。   |
| `createStore` | `StoreManager`       | 创建 store 管理器（插件、作用域隔离）。 |
| `storeToRefs` | `ToRefs`             | 将 store 状态安全转换为 ref。           |

## 2. 常用类型

| 类型                   | 链接                   | 用途                     |
| ---------------------- | ---------------------- | ------------------------ |
| `StoreManager`         | `StoreManager`         | store 根管理器。         |
| `DefineStoreOptions`   | `DefineStoreOptions`   | 选项式 store 定义类型。  |
| `ActionSubscriber`     | `ActionSubscriber`     | action 订阅回调签名。    |
| `SubscriptionCallback` | `SubscriptionCallback` | 状态变更订阅回调。       |
| `MutationRecord`       | `MutationRecord`       | mutation 记录结构。      |
| `MutationKind`         | `MutationKind`         | mutation 大类。          |
| `MutationType`         | `MutationType`         | mutation 类型枚举。      |
| `MutationOp`           | `MutationOp`           | mutation 操作类型。      |
| `WevuPlugin`           | `WevuPlugin`           | store/runtime 插件类型。 |

## 3. 端到端示例（script setup）

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { computed, createStore, defineStore, ref, storeToRefs } from 'wevu'

// [TS-only] 此示例无专属语法，TS/JS 写法一致。
const storeManager = createStore()

const useCartStore = defineStore('cart', () => {
  const count = ref(0)
  const total = computed(() => count.value * 99)
  function addOne() {
    count.value += 1
  }
  return { count, total, addOne }
})

const cart = useCartStore(storeManager)
const { count, total } = storeToRefs(cart)
</script>

<template>
  <view>count: {{ count }} / total: {{ total }}</view>
  <button @tap="cart.addOne">
    +1
  </button>
</template>
```

```vue [JavaScript]
<script setup>
import { computed, createStore, defineStore, ref, storeToRefs } from 'wevu'

const storeManager = createStore()

const useCartStore = defineStore('cart', () => {
  const count = ref(0)
  const total = computed(() => count.value * 99)
  function addOne() {
    count.value += 1
  }
  return { count, total, addOne }
})

const cart = useCartStore(storeManager)
const { count, total } = storeToRefs(cart)
</script>

<template>
  <view>count: {{ count }} / total: {{ total }}</view>
  <button @tap="cart.addOne">
    +1
  </button>
</template>
```

:::

## 4. 调试建议

* 如果要统计状态变化路径，可结合 `addMutationRecorder` / `removeMutationRecorder`。
* 如果要确认 `setData` 最终快照，可配合 `SetDataSnapshotOptions` 和运行时调试日志。

## 5. 相关页

* 响应式 API：[/wevu/api-reference/reactivity](/wevu/api-reference/reactivity)
* 运行时桥接 API：[/wevu/api-reference/runtime-bridge](/wevu/api-reference/runtime-bridge)

---

---
url: /wevu/api/store.md
description: 本页严格对应 wevu/store 的公开导出，包含 defineStore、createStore、storeToRefs 及相关类型。
---

# Store API（状态管理）

以下条目来源于 `packages/wevu/src/store/index.ts` 的公开导出。

## 核心函数

### `defineStore()` {#definestore}

* 类型入口：`DefineStoreOptions`
* 用途：定义 store（setup 风格或 option 风格）。

### `createStore()` {#createstore}

* 类型入口：`StoreManager`
* 用途：创建 store 管理器（可用于作用域隔离和测试隔离）。

### `storeToRefs()` {#storetorefs}

* 类型入口：`StoreToRefsResult`
* 用途：将 store 状态转换为 refs，避免解构丢失响应性。

## Store 类型

### `StoreManager` {#storemanager}

* 用途：store 根管理器类型。

### `DefineStoreOptions` {#definestoreoptions}

* 用途：定义 option 风格 store 的类型约束。

### `StoreToRefsResult` {#storetorefsresult}

* 用途：`storeToRefs()` 返回结果类型。

### `ActionContext` {#actioncontext}

* 用途：`$onAction` 回调上下文。

### `ActionSubscriber` {#actionsubscriber}

* 用途：action 订阅回调签名。

### `SubscriptionCallback` {#subscriptioncallback}

* 用途：状态变更订阅回调签名。

### `StoreSubscribeOptions` {#storesubscribeoptions}

* 用途：`$subscribe` 的订阅选项类型。

### `MutationType` {#mutationtype}

* 用途：store mutation 类型（`'patch object' | 'patch function' | 'direct'`）。

## 示例

::: code-group

```vue [TypeScript]
<script setup lang="ts">
import { computed, createStore, defineStore, ref, storeToRefs } from 'wevu'

const storeManager = createStore()

const useCartStore = defineStore('cart', () => {
  const count = ref(0)
  const total = computed(() => count.value * 99)

  function addOne() {
    count.value += 1
  }

  return { count, total, addOne }
})

const cart = useCartStore(storeManager)
const { count, total } = storeToRefs(cart)
</script>

<template>
  <view>count: {{ count }} / total: {{ total }}</view>
  <button @tap="cart.addOne">
    +1
  </button>
</template>
```

```vue [JavaScript]
<script setup>
import { computed, createStore, defineStore, ref, storeToRefs } from 'wevu'

const storeManager = createStore()

const useCartStore = defineStore('cart', () => {
  const count = ref(0)
  const total = computed(() => count.value * 99)

  function addOne() {
    count.value += 1
  }

  return { count, total, addOne }
})

const cart = useCartStore(storeManager)
const { count, total } = storeToRefs(cart)
</script>

<template>
  <view>count: {{ count }} / total: {{ total }}</view>
  <button @tap="cart.addOne">
    +1
  </button>
</template>
```

:::

---

---
url: /wevu/store.md
description: Store（状态管理），聚焦 Wevu / store 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# Store（状态管理）

Wevu 内置了类 Pinia 的 Store：

* 用 `defineStore()` 定义 Store
* 用 `useXxx()` 获取**单例**实例
* 用 `storeToRefs()` 解构 state/getter，避免丢失响应式

:::tip 导入约定
运行时 API 均从 `wevu` 主入口导入；`wevu/compiler` 仅供 Weapp-vite 等编译侧工具使用（非稳定用户 API）。
:::

## 导入与核心 API

* `defineStore(id, setup | options)`：定义 Store，返回 `useXxx()` 获取单例实例。
* `storeToRefs(store)`：将 state/getter 包装为 `ref`，函数保持原样，解构不丢失响应式。
* `createStore()`：可选的插件入口；只有需要插件时才调用（见下文）。

## Setup Store 示例（推荐）

```ts
// stores/counter.ts
import { computed, defineStore, ref } from 'wevu'

export const useCounter = defineStore('counter', () => {
  const count = ref(0)
  const doubled = computed(() => count.value * 2)
  const inc = () => count.value++
  return { count, doubled, inc }
})
```

特点：

* 你可以返回任意字段；函数会被当作 action（除 `$` 开头的保留字段）。
* `$patch/$subscribe/$onAction` 等基础 API 会自动合并进返回对象。

## Options Store 示例

```ts
// stores/user.ts
import { defineStore } from 'wevu'

export const useUser = defineStore('user', {
  state: () => ({ name: '', age: 0 }),
  getters: {
    label(state) {
      return `${state.name}:${state.age}`
    },
    canVote() {
      return this.age >= 18
    },
  },
  actions: {
    grow() {
      this.age += 1
    },
  },
})
```

## 在页面/组件中使用

```ts
// pages/counter/index.ts
import { defineComponent, storeToRefs } from 'wevu'
import { useCounter } from '@/stores/counter'

export default defineComponent({
  setup() {
    const counter = useCounter()
    const { count, doubled } = storeToRefs(counter)

    counter.$subscribe((mutation) => {
      console.log('[counter]', mutation.type, mutation.storeId)
    })

    return { count, doubled, inc: counter.inc }
  },
})
```

要点：

* Store 是单例，在页面/组件 `setup` 里调用 `useXxx()` 即可复用。
* 解构 state/getter 请使用 `storeToRefs`，actions 可以直接解构。

## 插件与订阅

* 默认无需插件即可使用；只有当你需要统一扩展所有 Store 时再调用 `createStore()` 并注册插件。
* 插件需在第一次 `useXxx()` 之前注册。`createStore()` 会记录为全局单例，之后创建的 Store 会自动应用插件（插件参数为 `{ store }`）。

```ts
import { createStore, defineStore } from 'wevu'

const manager = createStore()
manager.use(({ store }) => {
  store.$onAction((ctx) => {
    ctx.after(res => console.log('[after]', ctx.name, res))
    ctx.onError(err => console.error('[error]', ctx.name, err))
  })
  store.$subscribe((mutation, state) => {
    console.log(`[${store.$id}]`, mutation.type, state)
  })
})

// 之后定义的任何 store 都会自动套用上述插件
export const useCart = defineStore('cart', {
  state: () => ({ items: [] as Array<{ id: string, count: number }> }),
  actions: {
    add(id: string, count = 1) {
      const found = this.items.find(i => i.id === id)
      if (found) {
        found.count += count
      }
      else { this.items.push({ id, count }) }
    },
  },
})
```

## 持久化（storage）与初始化顺序

Store 是单例，适合承载登录态、用户偏好、缓存索引等“跨页面共享”的状态。常见诉求是把部分 state 持久化到本地存储（`wx.setStorageSync` / `wx.setStorage`）。

推荐做法：

* 只持久化必要字段（避免把大对象/列表直接塞进 storage）
* 统一在插件中处理（避免每个 store 手写重复逻辑）
* 注意初始化顺序：在第一次 `useXxx()` 之前完成“读取 → 回填”

示例（简化版，仅展示形态）：

```ts
import { createStore, defineStore } from 'wevu'

const manager = createStore()
manager.use(({ store }) => {
  const key = `wevu:${store.$id}`
  try {
    const raw = wx.getStorageSync(key)
    if (raw) {
      store.$patch(JSON.parse(raw))
    }
  }
  catch {}

  store.$subscribe((_mutation, state) => {
    try {
      wx.setStorageSync(key, JSON.stringify(state))
    }
    catch {}
  })
})

export const usePrefs = defineStore('prefs', {
  state: () => ({ theme: 'light' as 'light' | 'dark' }),
})
```

:::warning 注意
上面示例直接读取/写入 `wx` 存储，必须在小程序运行时执行；如果你在 Node/Vitest 环境跑测试，需要 stub `wx` 或把持久化逻辑封装到可替换的 adapter。
:::

## Store 实例 API

* `$id`：当前 Store 的唯一标识。
* `$state`（Options Store）：读取/替换整个 state；赋值会做浅合并并触发 `patch object`。
* `$patch(patch | fn)`：批量修改；Setup/Options Store 均可用，支持对象合并或回调方式。
* `$reset()`（Options Store）：将 state 重置为初始值。
* `$subscribe((mutation, state) => void)`：订阅变更，返回取消订阅函数；`mutation.type` 为 `patch object` 或 `patch function`。
* `$onAction(({ name, store, args, after, onError }) => void)`：订阅 action 调用，支持成功/失败回调。
* `storeToRefs(store)`：将所有非函数字段转换为可写 `ref`，函数保持原样，避免解构丢失响应式。

## TypeScript 与最佳实践

* Setup Store 会自动推导返回对象的类型；Options Store 可通过泛型精确声明 `state/getters/actions`。
* Store 文件按功能域组织（例如 `stores/user.ts`、`stores/cart.ts`），Store ID 使用小写单数。
* 避免直接解构 state：使用 `storeToRefs`；actions 可以直接解构。
* SSR/HMR/Devtools：Wevu 面向小程序运行环境，暂未提供这些 Web 专属能力。

## 常见问题

* 所有运行时 API 均从 `wevu` 主入口导入。
* 不需要为了使用 store 先调用 `createStore()`；仅在使用插件时才需要。

---

---
url: /integration/tailwindcss.md
description: 如果你是新项目，直接用官方模板创建即可，模板已集成 Tailwind CSS：
---

# Tailwindcss 集成

## 直接使用模板（推荐）

如果你是新项目，直接用官方模板创建即可，模板已集成 Tailwind CSS：

```sh
pnpm create weapp-vite
```

## 手动集成

如果你要在现有项目里手动接入 Tailwind CSS，请按下面文档操作：

* https://tw.icebreaker.top/docs/quick-start/native/install

---

---
url: /integration/tdesign.md
description: 在 Weapp-vite 项目里接入 tdesign-miniprogram 的整体思路很简单：
---

# tdesign-miniprogram 集成

在 `weapp-vite` 项目里接入 `tdesign-miniprogram` 的整体思路很简单：

* 安装依赖
* 按官方文档完成基础配置
* （可选）开启 Weapp-vite 的自动导入组件，让你不用手写 `usingComponents`

官方快速开始：<https://tdesign.tencent.com/miniprogram/getting-started>

## 安装包

```sh
pnpm add tdesign-miniprogram
```

如果你的 `tdesign-miniprogram` 版本 `>= 1.9.0`，还需要安装 `tslib`：

```sh
pnpm add -D tslib
```

## 构建成功后勾选 `将 JS 编译成 ES5`

在微信开发者工具的“详情”里勾选 `将 JS 编译成 ES5`（按官方建议配置即可）。

## 修改 app.json

将 `app.json` 中的 `"style": "v2"` 移除（按官方要求）。

## 修改 tsconfig.json (与官方文档不同)

如果你用 TypeScript 开发，建议在 `tsconfig.json` 里补上 `paths`，让编辑器能正确跳转到组件源码（避免路径报红）：

```json
{
  "paths": {
    "tdesign-miniprogram/*": ["./node_modules/tdesign-miniprogram/miniprogram_dist/*"]
  }
}
```

## 使用组件

以按钮组件为例：在页面/组件的 JSON 里引入对应组件，然后在 WXML 里使用。

```json
{
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button"
  }
}
```

WXML：

```html
<t-button theme="primary">按钮</t-button>
```

## 自动导入组件

如果你不想手写 `usingComponents`，可以开启 Weapp-vite 的自动导入组件：之后你在 WXML 里写 `<t-button />` 这类标签，构建器会自动补齐注册信息。

::: code-group

```ts [vite.config.ts]
import { TDesignResolver } from 'weapp-vite/auto-import-components/resolvers' // [!code highlight]
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    autoImportComponents: {
      resolvers: [TDesignResolver()], // [!code highlight]
    },
  },
})
```

:::

> \[!TIP]
> 旧版本 Weapp-vite 可能仍支持 `weapp.enhance.autoImportComponents`，但该写法已废弃，建议使用上面的顶层 `weapp.autoImportComponents`。

---

---
url: /wevu/api-reference/types.md
description: 本页先给出“高频类型速查”，然后提供 Wevu 当前导出的接口/类型别名全量索引。
---

# Type Reference（类型总览）

本页先给出“高频类型速查”，然后提供 `wevu` 当前导出的接口/类型别名全量索引。

## 1. 高频类型速查

| 类型                     | 链接                     | 说明                                                 |
| ------------------------ | ------------------------ | ---------------------------------------------------- |
| `SetupContext`           | `SetupContext`           | `setup(props, ctx)` 的上下文类型。                   |
| `RuntimeInstance`        | `RuntimeInstance`        | 运行时实例，含 snapshot/watch/bindModel 等能力。     |
| `ComponentDefinition`    | `ComponentDefinition`    | 小程序组件定义结构。                                 |
| `DefineComponentOptions` | `DefineComponentOptions` | `defineComponent` 参数类型。                         |
| `CreateAppOptions`       | `CreateAppOptions`       | `createApp` 参数类型。                               |
| `DefineStoreOptions`     | `DefineStoreOptions`     | `defineStore` 参数类型。                             |
| `WatchOptions`           | `WatchOptions`           | `watch/watchEffect` 配置。                           |
| `ModelBinding`           | `ModelBinding`           | `bindModel/useModel` 绑定结果。                      |
| `NativeComponent`        | `NativeComponent`        | 原生组件导入时的轻量类型包装。                       |
| `InferNativeProps`       | `InferNativeProps`       | 从原生 `properties` 自动推导 props。                 |
| `NativePropType`         | `NativePropType`         | 原生 `properties.type` 的泛型提示（类 `PropType`）。 |
| `TriggerEventOptions`    | `TriggerEventOptions`    | `emit/triggerEvent` 选项类型。                       |
| `WevuDefaults`           | `WevuDefaults`           | `setWevuDefaults` 配置结构。                         |
| `MiniProgramInstance`    | `MiniProgramInstance`    | setup 中原生实例类型。                               |
| `WevuPlugin`             | `WevuPlugin`             | 插件函数类型。                                       |

## 2. 接口（Interfaces）全量索引

| 接口                          | 领域                 |
| ----------------------------- | -------------------- |
| `ActionSubscriber`            | Store/action 订阅    |
| `AppConfig`                   | App 配置             |
| `ComponentDefinition`         | 组件定义             |
| `ComputedRef`                 | 只读 computed        |
| `CreateAppOptions`            | createApp 参数       |
| `DefineAppOptions`            | App 定义参数         |
| `DefineComponentOptions`      | defineComponent 参数 |
| `DefineStoreOptions`          | defineStore 参数     |
| `EffectScope`                 | effect 作用域        |
| `GlobalComponents`            | 全局组件扩展         |
| `GlobalDirectives`            | 全局指令扩展         |
| `InternalRuntimeStateFields`  | 运行时内部状态       |
| `MiniProgramAdapter`          | 平台适配器           |
| `MiniProgramComponentOptions` | 小程序组件配置       |
| `ModelBinding`                | 双向绑定结果         |
| `ModelBindingOptions`         | 双向绑定选项         |
| `MutationRecord`              | mutation 记录        |
| `PageFeatures`                | 页面 feature 开关    |
| `PrelinkReactiveTreeOptions`  | reactive 预链接选项  |
| `PropOptions`                 | prop 选项            |
| `RuntimeApp`                  | App 运行时实例       |
| `RuntimeInstance`             | 页面/组件运行时实例  |
| `SetDataDebugInfo`            | setData 调试信息     |
| `SetDataSnapshotOptions`      | setData 快照选项     |
| `SetupContext`                | setup 上下文         |
| `StoreManager`                | store 管理器         |
| `SubscriptionCallback`        | 订阅回调             |
| `TemplateRefs`                | 模板 ref 集合        |
| `TemplateRefValue`            | 模板 ref 值类型      |
| `WatchOptions`                | watch 配置           |
| `WevuDefaults`                | 全局默认值配置       |
| `WevuGlobalComponents`        | Wevu 全局组件        |
| `WevuGlobalDirectives`        | Wevu 全局指令        |
| `WritableComputedOptions`     | 可写 computed 配置   |
| `WritableComputedRef`         | 可写 computed 引用   |

## 3. 类型别名（Type Aliases）全量索引

### 3.1 组件、Props、宏相关

| 类型别名                  | 说明                       |
| ------------------------- | -------------------------- |
| `AllowedComponentProps`   | 允许透传的组件属性         |
| `ComponentCustomProps`    | 自定义组件属性扩展         |
| `ComponentOptionsMixin`   | 组件选项 mixin             |
| `ComponentPropsOptions`   | props 选项定义             |
| `ComponentPublicInstance` | 公共实例类型               |
| `DefineComponent`         | defineComponent 类型签名   |
| `EmitsOptions`            | emits 配置类型             |
| `ExtractDefaultPropTypes` | 默认值推断                 |
| `ExtractPropTypes`        | props 推断结果             |
| `ExtractPublicPropTypes`  | 对外 props 推断            |
| `InferPropType`           | 单个 prop 类型推断         |
| `InferProps`              | props 对象推断             |
| `InferNativePropType`     | 原生 property 单项推断     |
| `InferNativeProps`        | 原生 properties 对象推断   |
| `NativeComponent`         | 原生组件类型包装           |
| `NativePropType`          | 原生 property type 泛型    |
| `NativeTypedProperty`     | 原生 property 进阶兜底提示 |
| `PropConstructor`         | prop 构造器类型            |
| `PropType`                | prop 类型声明              |
| `PublicProps`             | 公共 props 合集            |
| `SetupFunction`           | setup 函数签名             |
| `TriggerEventOptions`     | triggerEvent 选项          |
| `VNode`                   | VNode 兼容类型             |
| `VNodeProps`              | VNode props 兼容类型       |

### 3.2 响应式与工具类型

| 类型别名              | 说明                 |
| --------------------- | -------------------- |
| `ComputedDefinitions` | computed 定义集合    |
| `ComputedGetter`      | computed getter      |
| `ComputedSetter`      | computed setter      |
| `ExtractComputed`     | 提取 computed 返回值 |
| `ExtractMethods`      | 提取 methods 返回值  |
| `MaybeRef`            | 值或 Ref             |
| `MaybeRefOrGetter`    | 值或 Ref 或 getter   |
| `MethodDefinitions`   | methods 定义集合     |
| `Ref`                 | Ref 类型             |
| `ShallowRef`          | ShallowRef 类型      |
| `ShallowUnwrapRef`    | shallow 解包类型     |
| `ToRefs`              | toRefs 返回类型      |
| `WatchStopHandle`     | watch 停止句柄       |

### 3.3 小程序桥接与运行时内部

| 类型别名                              | 说明               |
| ------------------------------------- | ------------------ |
| `InternalRuntimeState`                | 运行时内部状态     |
| `MiniProgramAppOptions`               | App 原生配置       |
| `MiniProgramBehaviorIdentifier`       | Behavior 标识符    |
| `MiniProgramComponentBehaviorOptions` | 组件 behavior 配置 |
| `MiniProgramComponentRawOptions`      | 组件原始配置       |
| `MiniProgramInstance`                 | 原生组件/页面实例  |
| `MiniProgramPageLifetimes`            | 页面生命周期类型   |
| `ObjectDirective`                     | 指令对象类型       |
| `TemplateRef`                         | 模板 ref 类型      |

### 3.4 store / model / mutation

| 类型别名              | 说明               |
| --------------------- | ------------------ |
| `ModelBindingPayload` | model 绑定 payload |
| `MutationKind`        | mutation 种类      |
| `MutationOp`          | mutation 操作      |
| `MutationType`        | mutation 类型      |
| `WevuPlugin`          | 插件类型           |

## 4. 编译侧类型（`wevu/compiler`）

| 类型别名              | 链接                  | 说明                              |
| --------------------- | --------------------- | --------------------------------- |
| `WevuRuntimeApiName`  | `WevuRuntimeApiName`  | 编译器识别的运行时 API 名字联合。 |
| `WevuPageHookName`    | `WevuPageHookName`    | 页面 hook 名字联合。              |
| `WevuPageFeatureFlag` | `WevuPageFeatureFlag` | 页面 feature 开关联合。           |

## 5. 相关页

* Core API：[/wevu/api-reference/core](/wevu/api-reference/core)
* Reactivity API：[/wevu/api-reference/reactivity](/wevu/api-reference/reactivity)
* Runtime Bridge API：[/wevu/api-reference/runtime-bridge](/wevu/api-reference/runtime-bridge)

---

---
url: /wevu/api/types.md
description: 本页仅保留业务开发最常用的公开类型。内部运行时类型不会在文档中展开。
---

# Type Reference（类型总览）

本页提供最常用的公开类型速查，避免把内部实现类型暴露为常规 API。

## 组件与应用

### `CreateAppOptions` {#createappoptions}

`createApp()` 的参数类型。

### `DefineComponentOptions` {#definecomponentoptions}

`defineComponent()` 的参数类型。

### `ComponentDefinition` {#componentdefinition}

`defineComponent()` 返回定义结构类型。

### `SetupContext` {#setupcontext}

`setup(props, ctx)` 中 `ctx` 的类型。

### `RuntimeInstance` {#runtimeinstance}

页面/组件运行时实例类型。

## 响应式与监听

### `Ref` {#ref-type}

基础响应式引用类型。

### `ShallowRef` {#shallowref-type}

浅层响应式引用类型。

### `WatchOptions` {#watchoptions}

`watch/watchEffect` 配置类型。

### `WatchStopHandle` {#watchstophandle}

watch 停止句柄类型。

### `MaybeRefOrGetter` {#maybereforgetter}

可接收值、Ref 或 getter 的联合类型。

## Store

### `StoreManager` {#storemanager}

store 根管理器类型。

### `DefineStoreOptions` {#definestoreoptions}

defineStore 选项类型。

### `StoreToRefsResult` {#storetorefsresult}

`storeToRefs()` 返回类型。

### `MutationType` {#mutationtype}

store mutation 类型。

## 运行时配置

### `WevuDefaults` {#wevudefaults}

`setWevuDefaults()` 配置类型。

### `ModelBinding` {#modelbinding}

`defineModel/useModel/useBindModel` 相关绑定类型。

### `TriggerEventOptions` {#triggereventoptions}

事件触发选项类型。

## 说明

更多底层与内部类型仍可在类型声明文件中找到，但不属于推荐直接依赖的公共 API 文档范围。

---

---
url: /guide/directory-structure/utils.md
description: 通用工具函数的推荐目录。
---

# `utils/`

`utils/` 是通用工具函数目录。

它没有框架保留语义，但非常适合作为纯函数和轻量工具层的落点。

## 常见内容

* 格式化函数
* URL/路径辅助函数
* 时间、数字、字符串处理
* 与业务无关的通用 helper

如果这里的模块同时被主包和多个分包引用，最终代码落盘位置还会受到 chunk 策略影响。

---

---
url: /integration/vant.md
description: Vant Weapp 集成，聚焦 integration / vant 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# Vant Weapp 集成

官方文档：<https://vant-ui.github.io/vant-weapp/#/home>

## 安装

```sh
pnpm i @vant/weapp
```

## 修改 app.json

将 `app.json` 中的 `"style": "v2"` 移除（按官方要求）。

## 修改 tsconfig.json (与官方文档不同)

如果你用 TypeScript 开发，建议在 `tsconfig.json` 里补上 `paths`，让编辑器能正确跳转到 Vant 组件源码（避免路径报红）：

```json
{
  "paths": {
    "@vant/weapp/*": ["./node_modules/@vant/weapp/dist/*"]
  }
}
```

## 使用组件

以按钮组件为例：在页面/组件的 JSON 里引入对应组件，然后在 WXML 里使用。

```json
{
  "usingComponents": {
    "van-button": "@vant/weapp/button/index"
  }
}
```

WXML：

```html
<van-button type="primary">按钮</van-button>
```

## 自动导入组件

如果你不想手写 `usingComponents`，可以开启 Weapp-vite 的自动导入组件：之后你在 WXML 里写 `<van-button />`，构建器会自动补齐注册信息。

::: code-group

```ts [vite.config.ts]
import { VantResolver } from 'weapp-vite/auto-import-components/resolvers' // [!code highlight]
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    autoImportComponents: {
      resolvers: [VantResolver()], // [!code highlight]
    },
  },
})
```

:::

> \[!TIP]
> 旧版本 Weapp-vite 可能仍支持 `weapp.enhance.autoImportComponents`，但该写法已废弃，建议使用顶层 `weapp.autoImportComponents`。

---

---
url: /guide/vite-plugin-host.md
description: 在自定义 Vite 插件中判断当前运行环境是否由 weapp-vite 创建，并区分 miniprogram 与 web 两种运行面。
---

# Vite 插件识别 weapp-vite 宿主

当你把一个自定义 Vite 插件同时用于 `weapp-vite` 和普通 `vite` 项目时，常见需求是：

* 只在 `weapp-vite` 场景下注入额外逻辑；
* 在 `weapp-vite` 里继续区分 `miniprogram` 与 `web` 两种运行面；
* 避免使用 `process.env` 这类进程级变量，防止同进程里的其他 Vite 实例被误判。

从当前版本开始，`weapp-vite` 会给自己创建的 Vite 实例注入 `config.weappVite` 宿主元信息。你可以在插件的 `config`、`configResolved` 等阶段读取这份信息来做判断。

## 宿主元信息结构

`weapp-vite` 会向 Vite 配置对象注入下面这个字段：

```ts
interface WeappViteHostMeta {
  name: 'weapp-vite'
  runtime: 'miniprogram' | 'web'
}
```

* `name` 固定为 `'weapp-vite'`，用于判断当前实例是否由 `weapp-vite` 创建。
* `runtime` 用于区分当前运行面：
  * `miniprogram`：小程序构建链路，包括主包、分包、pluginRoot、workers。
  * `web`：`weapp.web` 启用后的 Web 运行时与对应的 Vite 实例。

普通 `vite` 项目不会自动带上这个字段。

## 推荐写法

最直接的写法是在 `configResolved` 中读取 `config.weappVite`：

```ts
import type { Plugin } from 'vite'

export function myPlugin(): Plugin {
  return {
    name: 'my-plugin',
    configResolved(config) {
      if (config.weappVite?.name !== 'weapp-vite') {
        return
      }

      if (config.weappVite.runtime === 'miniprogram') {
        // 只在 weapp-vite 小程序运行面生效
      }

      if (config.weappVite.runtime === 'web') {
        // 只在 weapp-vite web 运行面生效
      }
    },
  }
}
```

如果你希望把判断逻辑收敛到一个 helper，也可以直接使用 `weapp-vite` 导出的工具函数：

```ts
import type { Plugin } from 'vite'
import { isWeappViteHost, resolveWeappViteHostMeta } from 'weapp-vite'

export function myPlugin(): Plugin {
  return {
    name: 'my-plugin',
    configResolved(config) {
      if (!isWeappViteHost(config)) {
        return
      }

      const host = resolveWeappViteHostMeta(config)
      if (!host) {
        return
      }

      if (host.runtime === 'miniprogram') {
        // 小程序逻辑
      }
    },
  }
}
```

## 对应处理方式

拿到宿主信息后，推荐按下面的粒度处理，而不是只做一个粗糙的布尔判断。

### 1. 普通 Vite

```ts
if (!config.weappVite) {
  // 保持普通 Vite 行为
}
```

适合的处理方式：

* 走插件默认逻辑；
* 跳过 weapp-vite 专属 transform、文件发射或小程序路径重写；
* 不要假设存在 `weapp` 配置、WXML/WXSS 产物或小程序输出目录。

### 2. weapp-vite + miniprogram

```ts
if (config.weappVite?.runtime === 'miniprogram') {
  // 小程序运行面
}
```

适合的处理方式：

* 启用只服务于小程序构建的逻辑；
* 处理小程序专属文件类型、路径规则、产物后缀或构建阶段行为；
* 针对 pluginRoot、workers、分包等链路复用同一套判断，因为它们都属于 `miniprogram`。

### 3. weapp-vite + web

```ts
if (config.weappVite?.runtime === 'web') {
  // Web 运行面
}
```

适合的处理方式：

* 使用浏览器可运行的分支；
* 跳过只能在小程序产物里成立的 emit/rename 逻辑；
* 如果你的插件既处理小程序源码，又支持 H5 调试，可以把浏览器兼容逻辑集中到这里。

## 为什么不推荐 `process.env`

不推荐用下面这种方式判断：

```ts
if (process.env.WEAPP_VITE) {
  // 不推荐
}
```

原因很直接：

* `process.env` 是进程级共享状态，不是当前 Vite 实例私有状态；
* 同一个 Node 进程里可能同时存在多个 Vite 实例；
* 这类标记很难可靠地区分 `miniprogram` 和 `web` 两种运行面。

`config.weappVite` 则是当前实例级别的元信息，作用域更清晰，也更适合插件判断。

## 类型与导入位置

你可以从下面两个入口获得类型与 helper：

```ts
import type { WeappViteHostMeta, WeappViteRuntime } from 'weapp-vite'
import {
  isWeappViteHost,
  resolveWeappViteHostMeta

} from 'weapp-vite'
```

或：

```ts
import type { WeappViteHostMeta, WeappViteRuntime } from 'weapp-vite/config'
import {
  isWeappViteHost,
  resolveWeappViteHostMeta

} from 'weapp-vite/config'
```

如果你只是在插件内部读取 `config.weappVite`，不引入 helper 也完全可以。

## 适用范围说明

当前宿主元信息由 `weapp-vite` 在内部合并配置时注入，因此以下链路都可以读取到：

* 常规小程序 `dev/build`
* 启用 `pluginRoot` 的插件构建
* workers 构建
* `weapp.web` 对应的 Web 运行面

如果你自己直接调用原生 `vite.createServer()` 或 `vite.build()`，且没有经过 `weapp-vite` 的配置合并链路，那么不会自动得到该字段，这属于预期行为。

---

---
url: /packages/vite-plugin-performance.md
description: vite-plugin-performance 用于包装一个或多个 Vite 插件，并统计每个生命周期 Hook 的执行耗时。
---

# vite-plugin-performance

`vite-plugin-performance` 用于包装一个或多个 Vite 插件，并统计每个生命周期 Hook 的执行耗时。

## 何时使用

* 你要定位构建慢点来自哪个插件/Hook
* 你要为插件性能监控打点
* 你要在不改插件实现的前提下测量耗时

## 安装

```bash
pnpm add -D vite-plugin-performance
```

## 最小示例

```ts
import { defineConfig } from 'vite'
import Inspect from 'vite-plugin-inspect'
import { wrapPlugin } from 'vite-plugin-performance'

export default defineConfig({
  plugins: [
    wrapPlugin(Inspect(), {
      threshold: 50,
    }),
  ],
})
```

## 常用选项

* `hooks`: 指定要统计的 Hook，或传 `'all'`
* `threshold`: 仅输出大于等于阈值的耗时
* `silent`: 关闭默认日志
* `logger`: 自定义日志输出
* `formatter`: 自定义日志格式
* `onHookExecution`: 每次统计完成后的回调

## 相关导出

* `wrapPlugin`
* `DEFAULT_PLUGIN_HOOKS`
* `DEFAULT_THRESHOLD`

---

---
url: /guide/directory-structure/vite-config.md
description: Weapp-vite 目录结构能力的总开关，负责定义 srcRoot、自动路由、分包、自动导入组件等行为。
---

# `vite.config.ts`

`vite.config.ts` 是这组目录约定的真正入口。很多“目录为什么会生效”的答案，最终都在这里。

## 它决定什么

* `weapp.srcRoot`：源码根目录在哪里
* `weapp.autoRoutes`：哪些页面目录会被扫描
* `weapp.subPackages`：哪些目录被当成分包 root
* `weapp.autoImportComponents`：哪些组件目录参与自动导入

## 最小示例

```ts
import { defineConfig } from 'weapp-vite'

export default defineConfig({
  weapp: {
    srcRoot: 'src',
    autoRoutes: true,
    autoImportComponents: true,
    subPackages: {
      packageA: {},
    },
  },
})
```

## 什么时候先看它

* 页面没被扫描到
* 分包页面被识别错了
* 类型文件生成到了意料之外的位置
* 你把源码目录从 `src/` 改到了 `miniprogram/`

相关文档：[srcRoot](/guide/directory-structure/src-root) / [subPackages](/guide/directory-structure/subpackages)

---

---
url: /wevu/vue-sfc/vue3-vs-weapp-sfc.md
description: >-
  本文聚焦“写法层面”的相同与不同：当你用 Weapp-vite + Wevu 写 .vue 时，哪些与 Vue 3 SFC
  一致，哪些会因为小程序编译/运行时而发生变化。
---

# Vue 3 SFC vs Weapp-vite SFC：写法对比

本文聚焦“写法层面”的相同与不同：当你用 Weapp-vite + Wevu 写 `.vue` 时，哪些与 Vue 3 SFC 一致，哪些会因为小程序编译/运行时而发生变化。

## 相同点（写法层面）

* **SFC 结构一致**：`<template>` / `<script setup>` / `<script>` / `<style>` 这些块仍然是主入口。
* **Composition API 语法一致**：`ref` / `reactive` / `computed` / `watch` / `onMounted` 等写法保持 Vue 3 心智。
* **`setup(props, ctx)` 签名一致**：`props` 与 `ctx` 仍是第一、第二参数，SFC 可以同时写 Options API 与 Composition API。
* **Script Setup 宏一致**：`defineProps` / `defineEmits` / `defineExpose` / `defineSlots` / `defineModel` 等宏仍可用（主要用于类型与编译期消解）。

## 不同点（由小程序编译/运行时造成）

### 1. 模板目标不是 DOM，而是 WXML

* 模板会被编译成 WXML，标签与属性遵循小程序规范（如 `view` / `text` / `image`）。
* 事件名会被映射到小程序事件（例如 `@click` 会映射为 `bindtap`）。
* `v-model` 会被编译成小程序事件 + 数据集路径（`bindinput="__weapp_vite_model"` + `data-wv-model="..."`），并只对部分表单元素有专门映射。
* `v-bind="object"` 不会展开为属性，需要显式写 `:prop="..."`。

细节参考：`/wevu/vue-sfc/template`。

### 2. 组件注册方式不同：usingComponents 仍是最终产物

Vue 3 中常见写法是“import + 注册/自动注册”。小程序最终仍要求 **JSON 声明式** 的 `usingComponents`，但 Weapp-vite 支持在**编译期**把“import + 模板使用”转为 `usingComponents`，因此可以保留类似的写法心智。

在 Weapp-vite 中：

* `usingComponents` 可以写在 `<json>` 或 `definePageJson/defineComponentJson` 宏里。
* 编译器会从 **模板标签** 与 **`<script setup>` 导入** 自动补齐 `usingComponents`（编译期生成，不是运行时注册）。
* 对应的组件导入会被移除，仅作为编译期元信息使用。

细节参考：`/wevu/vue-sfc/config`。

### 3. 新增 `<json>` 与 JSON 宏（Vue 3 没有）

Weapp-vite 允许在 `.vue` 中直接写小程序配置：

* `<json>` 自定义块（支持 json/jsonc/json5）。
* `<script setup>` 中的 `defineAppJson / definePageJson / defineComponentJson`（构建期执行并合并到最终 JSON）。

这些配置最终生成 `app.json / page.json / component.json`，属于小程序必需产物。

### 4. 运行时来源是 Wevu（而非 vue）

SFC 运行时基于 **Wevu**，不是浏览器 DOM：

* `defineComponent`、`ref` 等 API 应从 `wevu` 导入。
* Weapp-vite 会把部分 `vue` 运行时 API 重写为 `wevu` 版本（如 `useAttrs` / `useSlots` / `useModel`）。
* `ctx.emit` 实际调用的是小程序 `triggerEvent`，只携带 `detail` 单一载荷。

### 5. 样式输出是 WXSS，scoped 规则不同

* `<style>` 会编译为 WXSS，支持 `lang` 与 `scoped` / CSS Modules，但输出受 WXSS 规则限制。
* `scoped` 通过注入属性选择器实现（`data-v-xxx`），不是 DOM 级别的作用域计算。
* class/style 绑定会注入运行时代码（JS/WXS）以适配小程序模板能力。

## 快速对照示例

Vue 3（Web）：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import MyCard from './MyCard.vue'

const count = ref(0)
</script>

<template>
  <MyCard :count="count" @click="count++" />
</template>
```

Weapp-vite + Wevu（小程序）：

```vue
<script setup lang="ts">
import { ref } from 'wevu'
import MyCard from './MyCard.vue'

// 编译期会根据 import + 模板使用自动生成 usingComponents
const count = ref(0)
</script>

<template>
  <MyCard :count="count" @click="count++" />
</template>
```

## 实用总结

* **“写法像 Vue 3，产物是小程序”**：语法趋同，但目标平台完全不同。
* **优先认清两层**：模板/配置在编译期解决，响应式与生命周期在 Wevu 运行期解决。
* **遇到问题先分层**：模板/指令 → 看 Weapp-vite 编译；状态/生命周期 → 看 Wevu 运行时。

---

---
url: /guide/vue-sfc.md
description: >-
  这里是 Vue SFC 开发的入口说明。完整内容已迁移到 Wevu 文档目录：Weapp-vite 负责编译期（.vue → 小程序产物），Wevu
  负责运行期（响应式与生命周期）。
---

# Vue SFC 开发

这里是 Vue SFC 开发的入口说明。完整内容已迁移到 `wevu` 文档目录：Weapp-vite 负责编译期（`.vue` → 小程序产物），Wevu 负责运行期（响应式与生命周期）。

## 目录

* [总览](/wevu/vue-sfc/)
* [基础与组成](/wevu/vue-sfc/basics)
* [配置与宏](/wevu/vue-sfc/config)
* [模板与指令](/wevu/vue-sfc/template)
* [示例](/wevu/vue-sfc/examples)
* [调试与排错](/wevu/vue-sfc/troubleshoot)

---

---
url: /wevu/vue-sfc.md
description: >-
  Weapp-vite 内置了 Vue SFC 编译链路，配合 Wevu 运行时即可用 Vue
  风格开发小程序页面/组件，同时保持小程序能力（页面特性、分享、性能优化）。
---

# 在 Weapp-vite 中使用 Vue SFC

Weapp-vite 内置了 Vue SFC 编译链路，配合 `wevu` 运行时即可用 Vue 风格开发小程序页面/组件，同时保持小程序能力（页面特性、分享、性能优化）。

> 适用版本：Vue SFC 仅在 `weapp-vite@6.x` 及以上可用，请先升级到 6 大版本。
>
> 若项目同时使用 `weapp-vite` 与 `wevu`，请保持两者版本号一致（例如 `weapp-vite@x.y.z` 与 `wevu@x.y.z`）。

## 快速开始

* 需要安装 `wevu`：

::: code-group

```sh [pnpm]
pnpm add -D wevu
```

```sh [yarn]
yarn add -D wevu
```

```sh [npm]
npm i -D wevu
```

```sh [bun]
bun add -D wevu
```

:::

* 官方模板已默认带上，手动集成时请先装依赖再继续。

## 心智模型

Vue SFC 在小程序里建议拆成两段：

* **编译期（Weapp-vite）**：负责把 `.vue` 拆解/编译为小程序产物（WXML/WXSS/JS/JSON），并做模板语法（如 `v-if/v-for/v-model`）到 WXML 的转换。
* **运行期（Wevu）**：负责响应式、生命周期 hooks、快照 diff 与最小化 `setData`，让你用 Vue 3 风格的 Composition API 写业务逻辑。

```mermaid
flowchart LR
  A[Vue SFC<br/>.vue] --> B[编译期<br/>weapp-vite]
  B --> C[小程序产物<br/>WXML / WXSS / JS / JSON]
  C --> D[运行期<br/>wevu]
  D --> E[小程序逻辑层<br/>响应式 / hooks / diff + setData]
  E --> F[渲染层更新<br/>UI]
```

## 章节导航

* [基础与组成](/wevu/vue-sfc/basics)：SFC 各块作用、宏/指令的编译时与运行时、页面与组件区分等
* [配置与宏](/wevu/vue-sfc/config)：`usingComponents` 规则、`<json>` 与 Script Setup JSON 宏
* [模板与指令](/wevu/vue-sfc/template)：页面事件触发机制、`v-model` 支持范围与限制
* [class/style 绑定](/wevu/vue-sfc/class-style)：对齐 Vue 3 的 class/style 语法与运行时模式
* [示例](/wevu/vue-sfc/examples)：页面示例与组件 `v-model` 示例
* [调试与排错](/wevu/vue-sfc/troubleshoot)：常见问题定位与建议
* [Vue 3 写法对比](/wevu/vue-sfc/vue3-vs-weapp-sfc)：与 Vue 3 SFC 写法的相同点/不同点

迁移相关内容已独立成章节，请阅读：[从原生小程序迁移到 Vue SFC（详细指南）](/wevu/migration/from-native-to-vue-sfc)。

---

---
url: /config/vue.md
description: Weapp-vite 内置 Vue SFC（.vue → WXML/WXSS/JS/JSON）编译链路。这里聚焦编译期可配置项。
---

# Vue SFC 配置 {#vue-config}

`weapp-vite` 内置 Vue SFC（`.vue` → WXML/WXSS/JS/JSON）编译链路。这里聚焦编译期可配置项。

\[\[toc]]

## `weapp.vue.enable` {#weapp-vue-enable}

* **类型**：`boolean`
* **默认值**：`true`
* **说明**：保留字段。当前版本会在检测到 `.vue` 时自动启用 SFC 支持，该字段不影响行为。

## `weapp.vue.template` {#weapp-vue-template}

* **类型**：
  ```ts
  {
    removeComments?: boolean
    simplifyWhitespace?: boolean
    scopedSlotsCompiler?: 'auto' | 'augmented' | 'off'
    scopedSlotsRequireProps?: boolean
    slotMultipleInstance?: boolean
    classStyleRuntime?: 'auto' | 'wxs' | 'js'
    objectLiteralBindMode?: 'runtime' | 'inline'
    mustacheInterpolation?: 'compact' | 'spaced'
    classStyleWxsShared?: boolean
  }
  ```

示例：

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        scopedSlotsCompiler: 'auto',
        scopedSlotsRequireProps: true,
        slotMultipleInstance: true,
        classStyleRuntime: 'js',
        objectLiteralBindMode: 'runtime',
        mustacheInterpolation: 'compact',
        classStyleWxsShared: true,
      },
    },
  },
})
```

字段说明：

* `scopedSlotsCompiler`：作用域插槽编译策略。
  * `auto`：自动选择最小可用方案（默认）。
  * `augmented`：强制使用增强方案。
  * `off`：关闭 scoped slot（仅保留原生 slot，不支持 slot props）。
* `scopedSlotsRequireProps`：仅在 slot 传递作用域参数时才生成 scoped slot 组件。默认值随 `scopedSlotsCompiler` 自动推导。
* `slotMultipleInstance`：`v-for` 下 scoped slot 多实例模式（默认 `true`）。
* `classStyleRuntime`：class/style 绑定运行时。
  * `js`：强制 JS（默认）。
  * `auto`：平台支持 WXS 时优先 WXS，否则回退 JS。
  * `wxs`：强制 WXS，不支持时回退 JS 并告警。
* `objectLiteralBindMode`：对象字面量 `v-bind` 的输出方式。
  * `runtime`：默认，借助运行时中间变量输出。
  * `inline`：直接内联对象字面量到模板插值。
* `mustacheInterpolation`：Mustache 输出风格。
  * `compact`：默认，输出 `{{expr}}`。
  * `spaced`：输出 `{{ expr }}`，更便于调试阅读。
* `classStyleWxsShared`：是否复用 class/style 的 WXS helper（主包与非独立分包共享，独立分包各自生成）。

> \[!NOTE]
> `removeComments` / `simplifyWhitespace` 当前仍是兼容性预留位，尚未接入实际编译流程；其余字段已经参与模板编译输出。

## `weapp.vue.autoImport` {#weapp-vue-autoimport}

* **类型**：`boolean`
* **默认值**：`undefined`
* **说明**：保留字段，当前不影响构建行为。

> 组件自动导入请使用 [`weapp.autoImportComponents`](/config/auto-import-components.md)。
> 如果你在使用 Wevu 的 `<script setup>` / JSON 宏，请继续阅读 [/wevu/vue-sfc/config](/wevu/vue-sfc/config)。

---

---
url: /guide/vue-sfc/basics.md
description: Vue SFC：基础与组成，聚焦 guide / vue-sfc 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/basics](/wevu/vue-sfc/basics)。

---

---
url: /wevu/vue-sfc/basics.md
description: Vue SFC：基础与组成，聚焦 Wevu / vue-sfc 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# Vue SFC：基础与组成

## Vue SFC = 编译期（Weapp-vite）+ 运行期（Wevu）

在小程序里写 Vue SFC，建议把心智模型拆成两段：

* **编译期（Weapp-vite）**：负责把 `.vue` 拆解/编译为小程序产物（WXML/WXSS/JS/JSON），并做模板语法（如 `v-if/v-for/v-model`）到 WXML 的转换。
* **运行期（Wevu）**：负责响应式、生命周期 hooks、快照 diff 与最小化 `setData`，让你用 Vue 3 风格的 Composition API 写业务逻辑。

```mermaid
flowchart TB
  subgraph 编译期[编译期（weapp-vite）]
    SFC[.vue]
    SFC --> T[template 编译<br/>v-if/v-for/v-model → WXML]
    SFC --> S[script 编译<br/>SFC compiler + 转换 → JS]
    SFC --> C[style 编译<br/>lang/scoped/modules → WXSS]
    SFC --> J[json 合并<br/><json> + 宏 + auto usingComponents → JSON]
  end

  subgraph 运行期[运行期（wevu）]
    R[响应式 / hooks / diff]
    R --> SD[最小化 setData]
  end

  T --> OUT[产物：WXML/WXSS/JS/JSON]
  S --> OUT
  C --> OUT
  J --> OUT
  OUT --> R
```

因此：

* “模板能不能写”看编译器规则（本章主要讲这个）。
* “状态为什么不更新 / hooks 为什么不触发”通常是运行时使用方式问题（请对照 `/wevu/runtime` 与 `/wevu/compatibility`）。

## SFC 组成速查

在 Weapp-vite 里，一个 `.vue` 最终会被拆成小程序的 `wxml/wxss/js/json` 四件套。各个块大致对应如下：

| SFC 块                        | 你写什么                                                                         | 主要发生阶段                                     | 对应小程序产物                                            |
| ----------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------- |
| `<template>`                  | 视图结构、数据绑定、事件、指令（如 `v-if/v-for/v-model`）                        | 编译期（模板编译）                               | `*.wxml`                                                  |
| `<script setup>` / `<script>` | 业务逻辑、响应式状态、事件处理、生命周期 hooks                                   | 编译期（SFC 编译 + Weapp-vite 转换）→ 运行期执行 | `*.js`                                                    |
| `<style>`                     | 样式（支持 `lang`，支持 `scoped`/CSS Modules）                                   | 编译期（样式编译）                               | `*.wxss`                                                  |
| `<json>`（自定义块）          | 页面/组件配置：`usingComponents`、`navigationBarTitleText`、`component: true` 等 | 编译期（配置块编译/合并）                        | `page.json` / `component.json` / `app.json`（按文件类型） |

> 说明：Weapp-vite 只识别 SFC 中的 `<json>` 自定义块用于生成配置；其他自定义块不会参与小程序产物生成（除非你的项目额外加了插件链路处理它们）。

## 宏与指令：哪些是编译时，哪些是运行时

很多“看起来像函数/语法糖”的东西，其实属于不同层级；把它们分清，排查问题会快很多：

| 类别                               | 例子                                                                                                            | 阶段                   | 你需要知道的点                                                                                                              |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 模板指令（Vue 语法）               | `v-if/v-else/v-for`、`v-show`、`v-model`、`v-bind`（`:`）、`v-on`（`@`）                                        | 编译期                 | 由 Weapp-vite 把模板转换为 WXML；并非浏览器 DOM 事件模型（例如 `@click` 会被映射为小程序的 `tap`）。                        |
| `<script setup>` 编译宏（Vue SFC） | `defineProps/defineEmits/withDefaults/defineExpose/defineOptions/defineSlots/defineModel` 等（随 Vue 版本而定） | 编译期                 | 它们在编译时被消解，不是运行时函数：不用 `import`，也不能在非 `<script setup>` 里调用。                                     |
| Script Setup JSON 宏（Weapp-vite） | `defineAppJson/definePageJson/defineComponentJson`                                                              | 构建期（Node.js）      | 在打包时执行并生成/合并小程序 JSON 配置；不能访问 `wx`、不能依赖运行时状态；同一 SFC 内只能用一种宏（详见“配置与宏”章节）。 |
| 运行时 API（Wevu）                 | `ref/reactive/computed/watch`、`onMounted/onShow/onPageScroll/...`                                              | 运行期（小程序逻辑层） | 真正跑在小程序环境里，负责响应式与生命周期；相关 API 必须从 `wevu` 导入而不是 `vue`。                                       |

```mermaid
flowchart LR
  A[你写的代码] --> B{属于哪一类？}
  B -->|模板指令| C[weapp-vite 编译<br/>→ WXML]
  B -->|<script setup> 编译宏| D[Vue SFC 编译器消解<br/>→ JS 产物]
  B -->|JSON 宏| E[构建期执行（Node.js）<br/>→ 合并 JSON]
  B -->|wevu 运行时 API| F[小程序逻辑层执行<br/>→ 响应式/生命周期]
```

## 基础范式

* `wevu` 提供运行时：`defineComponent`（页面/组件统一使用）、`ref/reactive/computed/watch`、生命周期等。
* 推荐使用 Script Setup JSON 宏（build-time）注入小程序 App/Page/Component 配置。App/Page/Component 场景都应优先使用对应宏，不再新增 `<json>` 块。配合 `weapp-vite/volar` 获得智能提示。
* 模板语法与 Vue 3 基本一致（事件、v-if/v-for/class/style 绑定），构建时转为小程序原生 WXML。
* 样式使用 `<style lang="scss|less|css">`，构建后输出 `wxss`。
* 组件引入沿用小程序约定：在 `definePageJson/defineComponentJson` 中声明 `usingComponents`，脚本里不要用 ESModule `import` 注册小程序组件。
* props 推荐：Wevu 会把 Vue 风格的 `props` 规范化为小程序 `properties`，原生 `properties` 亦兼容。

## 页面与组件：如何区分

在微信小程序里，页面与组件都是“用 `Component()` 注册”的，但它们的 JSON 字段与生命周期事件并不一样。

* **页面**：通常位于 `src/pages/**/index.vue`，最终会出现在 `app.json` 的 `pages` 列表中（来源依赖你的路由/扫描策略）。
  * 页面配置优先用 `definePageJson()`（最终生成 `page.json`），`<json>` 仅用于兼容历史代码。
  * 页面 hooks（滚动/分享/触底/下拉刷新等）只对页面生效。
* **组件**：通常位于 `src/components/**/index.vue`，通过页面/组件 JSON 的 `usingComponents` 使用。
  * 组件配置优先用 `defineComponentJson()`（最终生成 `component.json`），并确保 `component: true`；新增组件不建议再写 `<json>`。

组件最小示例（只展示关键字段）：

```vue
<!-- components/MyCard/index.vue -->
<script setup lang="ts">
defineComponentJson(() => ({
  component: true,
  options: { virtualHost: true },
}))
</script>

<template>
  <view class="card">
    <slot />
  </view>
</template>
```

## .vue 编写注意事项（示例前必看）

* `<script lang="ts">`：页面/组件均使用 `export default defineComponent({ setup() {...} })` 注册；组件推荐写 `props`（Wevu 会转为小程序 `properties`），并在 `setup()` 里返回/暴露模板需要的数据与方法。
* `<script setup lang="ts">`：组合式语法糖，顶层定义的 ref/computed/函数会自动暴露到模板；如需声明 props/emits 使用 `defineProps/defineEmits`。
* 运行时 API 请从 `wevu` 导入（`ref/reactive/computed/watch`、生命周期钩子等），确保挂载到小程序生命周期与 `setData` diff。
* `usingComponents` 推荐通过 Script Setup JSON 宏注入；`<json>` 仅用于兼容旧代码。脚本侧不要通过 `import` 注册小程序组件（见“配置与宏”章节）。
* 避免直接使用 `window/document` 等浏览器专属能力，需改用微信小程序 API；模板事件使用小程序事件名（`@tap` 等）。

---

---
url: /guide/vue-sfc/template.md
description: 本页已迁移至 /wevu/vue-sfc/template。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/template](/wevu/vue-sfc/template)。

---

---
url: /wevu/vue-sfc/template.md
description: Vue SFC：模板与指令，聚焦 Wevu / vue-sfc 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# Vue SFC：模板与指令

## 页面事件与生命周期：怎么触发

在小程序里，很多页面事件属于“按需派发”：

* 只有你定义了 `onPageScroll/onReachBottom/onPullDownRefresh/...` 这些页面方法，事件才会从渲染层派发到逻辑层。
* `wevu` 的 `onPageScroll/onShareAppMessage/...` hooks，本质也是在注册对应页面方法。

```mermaid
flowchart LR
  R[渲染层] -->|scroll/share/...| P[Page 方法 onXxx]
  P --> W[wevu hooks 桥接]
  W --> L[setup 同步注册的回调]

  Note[说明：按需派发<br/>没定义 onXxx 就不会派发] -.-> P
```

你通常不需要手写 `features.enableOnXxx`：

* **使用 Weapp-vite 构建**：当编译器检测到你调用了对应 hooks，会在编译阶段自动补齐 `features.enableOnXxx = true`。
* **不使用 Weapp-vite（或极端场景）**：才需要在 `defineComponent({ features: ... })` 里手动开启。

## v-model 支持范围与限制

`weapp-vite` 的 Vue 模板编译会把 `v-model="x"` 直接编译成**小程序的“赋值表达式事件”**（例如 `bind:input="x = $event.detail.value"`），因此它有一些明确限制：

* **表达式必须可赋值**：只建议写 `x` / `x.y` / `x[i]` 这类“左值”。不要写 `a + b`、函数调用、可选链（`a?.b`）等。
* **不支持 v-model 参数/修饰符**：`v-model:title`、`v-model.trim/.number/.lazy` 目前不会按 Vue 语义生效（会当作普通 v-model 处理，可能导致行为不符合预期）。
* **仅对部分表单元素做了专门映射**（见下表）。其他标签会退化为 `value + bind:input` 并给出编译警告。

当前内置映射（实现位于 `packages/weapp-vite/src/plugins/vue/compiler/template.ts`）：

| 标签                    | 绑定属性  | 事件          | 赋值来源                                    |
| ----------------------- | --------- | ------------- | ------------------------------------------- |
| `input`（默认/text）    | `value`   | `bind:input`  | `$event.detail.value`                       |
| `input type="checkbox"` | `checked` | `bind:change` | `$event.detail.value`（实现为 best-effort） |
| `input type="radio"`    | `checked` | `bind:change` | `$event.detail.value`                       |
| `textarea`              | `value`   | `bind:input`  | `$event.detail.value`                       |
| `select`                | `value`   | `bind:change` | `$event.detail.value`                       |
| `switch` / `checkbox`   | `checked` | `bind:change` | `$event.detail.value`                       |
| `slider` / `picker`     | `value`   | `bind:change` | `$event.detail.value`                       |

> 建议：复杂/非标准表单（如 `radio-group` / `checkbox-group`）或自定义组件，优先使用显式 `:value` + `@input/@change`，或者用 `wevu` 的 `ctx.bindModel()` 自己定义 `event/valueProp/parser`。

```mermaid
flowchart TB
  A[v-model=\"x\"] --> B{标签类型}
  B -->|input/textarea| C[value + bind:input<br/>x = $event.detail.value]
  B -->|switch/checkbox| D[checked + bind:change<br/>x = $event.detail.value]
  B -->|slider/picker| E[value + bind:change<br/>x = $event.detail.value]
  B -->|其它/自定义| F[退化为 value + bind:input<br/>并给出编译警告]
```

## v-bind 限制

`v-bind="object"`（对象展开）目前不会生成任何属性，等同于未绑定。
建议改为显式写法：`:<prop>="..."` + `@<event>="..."`。

## 延伸阅读

* [class/style 绑定能力](/wevu/vue-sfc/class-style)

---

---
url: /guide/vue-sfc/examples.md
description: 本页已迁移至 /wevu/vue-sfc/examples。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/examples](/wevu/vue-sfc/examples)。

---

---
url: /wevu/vue-sfc/examples.md
description: >-
  这个示例展示一个自定义组件如何配合 v-model 工作。对于自定义组件，Weapp-vite 会把 v-model="x" 按默认策略编译为
  value="{{x}}" + bind:input="x = $event.detail.v…
---

# Vue SFC：示例

## 页面示例：计数 + 分享 + 页面滚动

```vue
<!-- pages/counter/index.vue -->
<script setup lang="ts">
import { computed, onPageScroll, onShareAppMessage, ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '计数器',
}))

const count = ref(0)
const doubled = computed(() => count.value * 2)
const reachedTop = ref(true)

onPageScroll(({ scrollTop }) => {
  reachedTop.value = scrollTop < 40
})

onShareAppMessage(() => ({
  title: `当前计数 ${count.value}`,
  path: '/pages/counter/index',
}))

function inc() {
  count.value += 1
}
</script>

<template>
  <view class="page">
    <text>count: {{ count }} / doubled: {{ doubled }}</text>
    <text v-if="!reachedTop">
      正在滚动...
    </text>
    <button @tap="inc">
      +1
    </button>
  </view>
</template>
```

> 说明：小程序部分页面事件是“按需派发”（分享/滚动等），Weapp-vite 会在编译阶段根据你是否调用 `onPageScroll/onShareAppMessage/...` 自动补齐 `features.enableOnXxx = true`；如需手动控制，仍可在 `defineComponent({ features: ... })` 中显式覆盖。

## 组件示例：Props + Emits + v-model（Script Setup + 宏）

这个示例展示一个自定义组件如何配合 `v-model` 工作。对于自定义组件，`weapp-vite` 会把 `v-model="x"` 按默认策略编译为 `value="{{x}}"` + `bind:input="x = $event.detail.value"`，因此组件侧需要：

* 接收 `value`（props）
* 触发 `input` 事件，并在 `detail.value` 中带回新值

```mermaid
flowchart LR
  Page[页面 state.amount] --> WXML[WXML: v-model 编译产物<br/>value={{state.amount}}]
  WXML --> Comp[自定义组件 props.value]
  Comp -->|triggerEvent('input', { value: next })| WXML
  WXML -->|bind:input 赋值表达式| Page
```

```vue
<!-- components/stepper/index.vue -->
<script setup lang="ts">
import { computed } from 'wevu'

const props = withDefaults(defineProps<{
  value?: number
  min?: number
  max?: number
}>(), {
  value: 0,
  min: 0,
  max: 10,
})

const emit = defineEmits<{
  (e: 'input', detail: { value: number }): void
}>()

defineComponentJson(() => ({
  component: true,
}))

const value = computed(() => props.value ?? 0)

function setValue(next: number) {
  emit('input', { value: next })
}

function inc() {
  if (value.value >= props.max) {
    return
  }
  setValue(value.value + 1)
}

function dec() {
  if (value.value <= props.min) {
    return
  }
  setValue(value.value - 1)
}
</script>

<template>
  <view class="stepper">
    <button @tap="dec">
      -
    </button>
    <text>{{ value }}</text>
    <button @tap="inc">
      +
    </button>
  </view>
</template>
```

使用（页面侧同样推荐用宏注入 `usingComponents`）：

```vue
<!-- pages/demo/index.vue -->
<script setup lang="ts">
import { reactive } from 'wevu'

definePageJson(() => ({
  usingComponents: {
    stepper: '/components/stepper/index',
  },
}))

const state = reactive({ amount: 1 })
</script>

<template>
  <stepper v-model="state.amount" :min="1" :max="5" />
</template>
```

更多实践可搭配仓库中的示例应用 `apps/wevu-*`（如 [wevu-comprehensive-demo](https://github.com/weapp-labs/weapp-vite/tree/main/apps/wevu-comprehensive-demo)、[wevu-runtime-demo](https://github.com/weapp-labs/weapp-vite/tree/main/apps/wevu-runtime-demo)、[wevu-vue-demo](https://github.com/weapp-labs/weapp-vite/tree/main/apps/wevu-vue-demo)）。

---

---
url: /guide/vue-sfc/troubleshoot.md
description: 本页已迁移至 /wevu/vue-sfc/troubleshoot。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/troubleshoot](/wevu/vue-sfc/troubleshoot)。

---

---
url: /wevu/vue-sfc/troubleshoot.md
description: Vue SFC：调试与排错，聚焦 Wevu / vue-sfc 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# Vue SFC：调试与排错

## 最佳实践与限制

* 使用小程序组件/事件名：模板中的 `<view>`、`<button>`、`@tap` 等会在构建时转为原生写法。
* 避免 DOM 专属 API（`window/document`）；需用小程序 API（如 `wx.request`）。
* 样式选择器遵循小程序规范；`scoped` 样式会编译为符合小程序前缀的选择器。
* 若使用 `<slot>`，保持与小程序组件 slot 语义一致。
* 需要分享/朋友圈/收藏能力时，请按微信官方实现页面回调（`onShareAppMessage/onShareTimeline/onAddToFavorites`），并在需要时调用 `wx.showShareMenu()` 配置菜单项。

## 常见问题

### 1) 组件不渲染

优先按这个顺序检查：

* `usingComponents` 是否声明、路径是否正确（注意分包路径与大小写）。
* `component.json` 是否包含 `component: true`（组件必须是组件）。
* 开发者工具控制台是否提示 “usingComponents not found / component path not found / wxml parse error”。

```mermaid
flowchart TB
  A[组件不渲染] --> B{usingComponents 是否正确？}
  B -->|否| B1[修正路径/分包路径/大小写]
  B -->|是| C{component: true 是否存在？}
  C -->|否| C1[用 <json> 或 defineComponentJson 写入 component: true]
  C -->|是| D{控制台是否报错？}
  D -->|是| D1[按错误信息定位：wxml parse / path not found]
  D -->|否| E[进一步排查：模板/条件渲染/样式隐藏]
```

### 2) 状态不更新

* 确认响应式 API 来自 `wevu`（不是 `vue`）。
* 确认你更新的是响应式值（例如 `ref.value`）。
* 确认模板确实依赖了该状态（否则更新不会反映到 UI）。

### 3) hooks 不触发（滚动/分享/触底等）

* hooks 必须在 `setup()` **同步阶段**注册（`await` 后注册会报错或失效）。
* 分享/朋友圈/收藏等能力是否满足微信官方触发条件（菜单项、`open-type="share"`、`wx.showShareMenu()` 等）。

### 4) v-model 行为不符合 Vue 预期

回到“模板与指令”章节的 `v-model` 限制：它是小程序“赋值表达式事件”，不是 Vue 的完整 v-model 语义（参数/修饰符等）。

更强的双向绑定方案请参考：`/wevu/runtime` 的 `bindModel` 部分。

---

---
url: /guide/vue-sfc/config.md
description: Vue SFC：配置与宏，聚焦 guide / vue-sfc 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/config](/wevu/vue-sfc/config)。

---

---
url: /wevu/vue-sfc/config.md
description: 小程序组件的注册是 **JSON 声明式** 的：只认 usingComponents。因此在 SFC 里推荐：
---

# Vue SFC：配置与宏

## usingComponents：为什么脚本里不要 import

小程序组件的注册是 **JSON 声明式** 的：只认 `usingComponents`。因此在 SFC 里推荐：

* 优先在 `defineAppJson/definePageJson/defineComponentJson` 里声明 `usingComponents`
* App/Page/Component SFC 能用对应 JSON 宏就不要再写 `<json>`
* 模板里直接写组件标签（例如 `<my-card />`）

页面示例：

```vue
<script setup lang="ts">
definePageJson(() => ({
  usingComponents: {
    'my-card': '/components/MyCard/index',
  },
}))
</script>

<template>
  <my-card />
  <!-- 也可以传 slot -->
  <my-card>
    <text>hello</text>
  </my-card>
</template>
```

:::warning 常见误区
不要把小程序组件当成 Web Vue 组件来做“ESM import + components 注册”。即使你在脚本里写了 import，最终是否能工作也取决于产物如何生成 `usingComponents`。
:::

> 提示：`tsconfig.app.json` 已预置 `"vueCompilerOptions.plugins": ["weapp-vite/volar"]`，配合 Volar 扩展即可获得 JSON 宏与模板提示。

:::warning 必须设置 vueCompilerOptions.lib
若使用 Wevu 的 `<script setup>` 宏（`defineProps/withDefaults/defineEmits` 等），请务必在同一处设置 `"vueCompilerOptions.lib": "wevu"`，否则宏的类型提示会退化为 `any`。
:::

## 配置块模式对比

| 写法                  | 作用                | 适合场景                         |
| --------------------- | ------------------- | -------------------------------- |
| Script Setup 宏       | build-time 注入配置 | 默认方案（页面/组件/App 均推荐） |
| `<json>`              | JSONC + Schema 提示 | 兼容旧代码的静态配置             |
| `<json lang="jsonc">` | JSONC + Schema 提示 | 兼容旧代码的静态配置（显式标注） |
| `<json lang="ts/js">` | TS/JS + 类型检查    | 历史项目迁移期的动态/异步配置    |

```mermaid
flowchart TB
  A[最终 JSON（page.json / component.json / app.json）] <-- 合并/覆盖 --- B[配置来源]
  B --> C[<json> 自定义块]
  B --> D[auto usingComponents<br/>（基于 <template> 引用分析）]
  B --> E[Script Setup JSON 宏<br/>definePageJson / defineComponentJson / defineAppJson]
  E -->|优先级最高| A
  C --> A
  D --> A
```

示例（动态配置）：

```vue
<script setup lang="ts">
definePageJson(async () => ({
  navigationBarTitleText: process.env.APP_TITLE ?? '默认标题',
}))
</script>
```

## Script Setup JSON 宏（build-time） {#script-setup-json-macros}

`weapp-vite` 支持在 Vue SFC 的 `<script setup>` 中使用以下 **JSON 宏**，并在构建时把返回结果合并进最终的 `page.json` / `component.json`：

* `defineAppJson`
* `definePageJson`
* `defineComponentJson`

建议：

* App/Page/Component SFC 默认使用对应宏：
  * App 用 `defineAppJson`
  * Page 用 `definePageJson`
  * Component 用 `defineComponentJson`
* `<json>` 作为兼容模式保留，不建议在新增 SFC 里使用。

特点与限制：

* 必须是 `<script setup>` 的**顶层语句**，且**只能传 1 个参数**。
* 同一个 SFC 内只能使用一种宏（例如只能用 `definePageJson`），但可以调用多次；多次返回会 **deep merge**（后者覆盖前者）。
* 支持 `object` / `() => object` / `async () => object`（也支持返回 `Promise`）。
* 宏只在 **构建期（Node.js）** 执行：请保持幂等，避免依赖小程序运行时 API；推荐只做本地 import、常量拼装与轻量计算。
* 合并优先级最高：会覆盖 `<json>` 块以及自动 `usingComponents` 的结果。

> TypeScript 提示：确保项目的 `vite-env.d.ts` 包含 `/// <reference types="weapp-vite/client" />`（脚手架默认已配置），这样 IDE 才能识别这些全局宏。

组件示例：

```vue
<script setup lang="ts">
defineComponentJson(() => ({
  styleIsolation: 'isolated',
  options: { virtualHost: true },
  externalClasses: ['macro-card-class'],
}))
</script>
```

页面示例：

```vue
<script setup lang="ts">
import { macroDemoNavBg, macroDemoNavTitle } from './macro.config'

definePageJson(() => ({
  navigationBarTitleText: macroDemoNavTitle,
  navigationBarBackgroundColor: macroDemoNavBg,
  enablePullDownRefresh: true,
}))
</script>
```

---

---
url: /integration/vue-mini.md
description: Vue Mini 是一个基于 Vue 3 的小程序框架，你可以用 Vue 3 的响应式和组合式 API 来开发小程序。
---

# Vue-mini 集成

## vue-mini 介绍

Vue Mini 是一个基于 Vue 3 的小程序框架，你可以用 Vue 3 的响应式和组合式 API 来开发小程序。

文档：<https://vuemini.org/>

## 集成

在 `weapp-vite` 中接入 `vue-mini` 的步骤很简单：安装依赖后按官方文档使用即可。

```sh
pnpm i @vue-mini/core
```

然后你就可以跟随文档，使用 `vue-mini` 的所有特性了！

## 模板地址

这是一个 `vue-mini` + `weapp-vite` + `weapp-tailwindcss` 已配置好的模板：

<https://github.com/icebreaker-template/vue-mini-tailwindcss-template>

---

---
url: /packages/weapp-ide-cli.md
description: weapp-ide-cli 是微信开发者工具 CLI 的增强封装，提供命令透传、automator 子命令、配置管理与中英文切换。
---

# weapp-ide-cli

`weapp-ide-cli` 是对微信开发者工具官方命令行的增强封装：

* 保留官方命令语义（透传）
* 增强路径/参数兼容
* 提供 automator 子命令
* 提供可持久化配置（`~/.weapp-ide-cli/config.json`）
* 默认中文提示，支持切换英文

> 使用前请在微信开发者工具开启：`设置 -> 安全设置 -> 服务端口`。

## 安装

```bash
pnpm add -g weapp-ide-cli
# 或 npm install -g weapp-ide-cli
```

`weapp` 与 `weapp-ide-cli` 为等价入口。

## 命令大全

### 1) 微信官方 CLI 透传命令

| 命令                    | 说明            |
| ----------------------- | --------------- |
| `weapp open`            | 打开 IDE / 项目 |
| `weapp login`           | 重新登录 IDE    |
| `weapp islogin`         | 检查登录状态    |
| `weapp preview`         | 预览二维码      |
| `weapp auto-preview`    | 自动预览        |
| `weapp upload`          | 上传小程序      |
| `weapp build-npm`       | 构建 npm        |
| `weapp auto`            | 开启自动化      |
| `weapp auto-replay`     | 自动化回放      |
| `weapp reset-fileutils` | 重置文件工具    |
| `weapp close`           | 关闭项目        |
| `weapp quit`            | 退出 IDE        |
| `weapp cache`           | 清理缓存        |
| `weapp engine`          | 引擎相关命令    |
| `weapp open-other`      | 打开其它项目    |
| `weapp build-ipa`       | 生成 iOS 包     |
| `weapp build-apk`       | 生成 Android 包 |
| `weapp cloud`           | 云开发命令      |

官方文档：

* <https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html>

### 2) automator 增强命令

| 命令                             | 说明                      |
| -------------------------------- | ------------------------- |
| `weapp screenshot`               | 截图（base64 / 文件输出） |
| `weapp navigate <url>`           | 保留栈跳转页面            |
| `weapp redirect <url>`           | 重定向页面                |
| `weapp back`                     | 页面返回                  |
| `weapp relaunch <url>`           | 重启到指定页面            |
| `weapp switch-tab <url>`         | 切换到 tabBar 页          |
| `weapp page-stack`               | 查看页面栈                |
| `weapp current-page`             | 查看当前页面              |
| `weapp system-info`              | 查看系统信息              |
| `weapp page-data [path]`         | 查看页面数据              |
| `weapp tap <selector>`           | 点击元素                  |
| `weapp input <selector> <value>` | 元素输入                  |
| `weapp scroll <scrollTop>`       | 页面滚动                  |
| `weapp audit`                    | 体验评分审计              |
| `weapp remote [--disable]`       | 开关远程调试              |

帮助：

```bash
weapp help navigate
weapp navigate --help
```

### 3) config 子命令

| 命令                                         | 说明                              |
| -------------------------------------------- | --------------------------------- |
| `weapp config`                               | 交互式配置 CLI 路径               |
| `weapp config lang <zh\|en>`                 | 切换并保存语言                    |
| `weapp config set-lang <zh\|en>`             | `lang` 别名                       |
| `weapp config show`                          | 显示完整配置 JSON                 |
| `weapp config get <cliPath\|locale>`         | 读取单个配置项                    |
| `weapp config set <cliPath\|locale> <value>` | 写入配置项                        |
| `weapp config unset <cliPath\|locale>`       | 删除配置项                        |
| `weapp config doctor`                        | 配置健康诊断                      |
| `weapp config export [path]`                 | 导出配置（不传 path 输出 stdout） |
| `weapp config import <path>`                 | 从 JSON 文件导入配置              |

配置文件位置：

* macOS / Linux: `~/.weapp-ide-cli/config.json`
* Windows: `C:\Users\<用户名>\.weapp-ide-cli\config.json`

配置示例：

```json
{
  "cliPath": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
  "locale": "zh"
}
```

### 4) 支付宝 minidev 转发

| 命令                               | 说明                         |
| ---------------------------------- | ---------------------------- |
| `weapp alipay <args...>`           | 透传到 `minidev`             |
| `weapp ali <args...>`              | `alipay` 别名                |
| `weapp open --platform alipay ...` | 自动转发为 `minidev ide ...` |

### 5) 程序化命令目录导出

可直接复用 `weapp-ide-cli` 提供的命令判断能力：

```ts
import {
  isWeappIdeTopLevelCommand,
  WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES,
} from 'weapp-ide-cli'

if (isWeappIdeTopLevelCommand('preview')) {
  // 这里可以执行透传
}

console.log(WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES)
```

## 语言切换

默认中文。可通过以下方式切换英文：

```bash
# 单次命令
weapp help navigate --lang en

# 持久化配置
weapp config lang en

# 环境变量
WEAPP_IDE_CLI_LANG=en weapp open -p
```

## 参数前置校验（增强）

在调用官方 CLI 前，会进行本地校验：

* `upload` 必须提供 `--version/-v` 与 `--desc/-d`（且非空）
* `preview` 的 `--qr-format/-f` 仅支持 `terminal` / `image` / `base64`
* `preview` / `upload` / `auto` / `auto-preview` 需要提供 `--project` 或 `--appid`
* `--ext-appid` 在未提供 `--project` 时必须与 `--appid` 一起使用
* `--port` 必须为正整数
* `--login-retry` 仅支持 `never` / `once` / `always`
* `--login-retry-timeout` 必须为正整数

## 参考

* 微信 CLI 文档：<https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html>
* 微信自动化文档：<https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/miniprogram.html>

---

---
url: /blog/release4.md
description: >-
  Weapp-vite 是由 笔者 icebreaker 开发的一个基于 vite 的现代化微信小程序开发工具链。我给它设定的目标初心是:
  为小程序开发者带来笑容。
---

# Weapp-vite - 微信小程序工具链的另一种选择

## 前言

[`weapp-vite`](https://github.com/weapp-vite/weapp-vite) 是由 [笔者 icebreaker](https://github.com/sonofmagic) 开发的一个基于 `vite` 的现代化微信小程序开发工具链。我给它设定的目标初心是: `为小程序开发者带来笑容`。

自从在 `2024` 年的 `8` 月正式发布之后，到现在也过了将近 `9` 个月的时间。`weapp-vite` 在用户不断的反馈，以及我对代码方面不断的重构和优化下，也从 `1.x` 版本逐渐迭代到了 `4.0` 版本。

最近随着我对打包工具，以及编译的理解不断的加深，`4.0` 版本中，我也完全重构了 `weapp-vite` 的编译核心。这个版本是我相对来说，比较 **满意** 的一个版本。

所以我也心血来潮，写了这篇文章。同时这也是我之前，虽然发布了 `2.x`，`3.x` 版本，但是却没有发表任何文章的一个主要原因。

## 之前版本遇到的一些困难

在 `3.x` 之前的版本，存在一些非常大的问题:

### 热更新与耦合问题

每次构建，`weapp-vite` 都会去扫描整个小程序目录，然后分析哪些是打包入口，哪些是 `wxml` 的依赖项。这套机制是纯 `fs` 实现的，并没有用到 `vite`(`rollup`) 的 `chunk`/`asset` 加载的机制。

这导致在插件的 `options` 阶段做的事情过多，热更新效率非常差，多个 `Service` 还有 `Vite` 插件存在严重耦合。

虽然普通的使用 `weapp-vite` 的开发者不会遇到这个情况，但是这却严重阻碍了 `weapp-vite` 的进一步发展。这让我如鲠在喉，夜不能寐。

于是，我详细阅读并调试了 `uni-app` 和 `Taro` 的源代码，并最终走出了一条最适合 `weapp-vite` 路。

值得一提的是，`uni-app` 编译的中间产物比较有趣:

```js
import './manifest-json-js'

if (!Math) {
  import('uniPage://cGFnZXMvaW5kZXgvaW5kZXgudnVl')
  import('uniPage://cGFnZXMvaXNzdWUvdGFpbHdpbmQtY2hpbGRyZW4udnVl')
  import('uniPage://cGFnZXMvaXNzdWUvY2FzZS1keW5hbWljLWNsYXNzLnZ1ZQ')
}
```

这种加载机制，有点类似于那种 `rollup` 虚拟模块的实现。而且这么写可以走 `resolveDynamicImport` 的 `rollup build hook`，然后其余的小程序页面就走:

```js
// uniPage
import MiniProgramPage from 'xxxx'

wx.createPage(MiniProgramPage)
```

虽然 `uni-app` / `Taro` 都改了运行时了。但我对我的 `weapp-vite` 的编译的目标是默认不会注入任何运行时的东西，这样才能保证打出来的包足够的小, 后续用户想要注入什么都通过 `vite` 插件的方式进行注入。

> `Taro` 为了做运行时兼容，注入的运行时代码实在是太大了，需要在一开始的时候就做好分包的规划。`uni-app` 也有注入但是体积还能接受，没有 `Taro` 这么夸张。

### 自定义加载模块方式

然后另外在更改 `weapp-vite` 内核的时候，我曾经一度想要放弃使用 `vite` 改用 `rspack` 完全重写，因为我有高度自定义加载模块方式的需求。(假如真的这样做，那项目就改名叫 `weapp-rspack`)

因为默认情况下 `rollup` 就只支持 `import` ,`import()` 等等这种方式去做模块的分析和引入。`cjs` 那种都是需要依赖 `@rollup/plugin-commonjs` 这种去做转化 `esm`, 然后分析依赖。

但是小程序的模块加载方式是非标的，什么 `require.async(id)`, `require(id,callback)` 这种都不是默认的标准，这时候就需要自定义加载模块方式。

当然扯到这就太技术了，读者没有遇到过这样的场景的话，也是很难理解的了的。毕竟技术都是，越往一个方向深入，同行的人就越少，想找个人做技术探讨和交流都困难。

## 主要特点

接下来我来总结一下 `weapp-vite` 的主要特点：

1. **轻量级原生开发**
   * 保持原生小程序的开发方式，无需学习新框架
   * 直接使用微信官方文档的写法
   * 对原生小程序开发提供更好的支持，包括 `Skyline` 等新特性

2. **现代化开发体验**
   * 开箱即用支持 `TypeScript`、`SCSS`、`Less` 等
   * 基于 `Vite` 构建，享受极速的开发体验
   * 支持 `Vite` 生态的插件系统

3. **增强功能**
   * 自动构建 `npm`：支持两种 `npm` 构建策略
   * 自动引入组件：无需手动在 `json` 中注册
   * 完整的别名支持：可在任意 `js/ts` 或 `json` 文件中使用
   * 独立分包适配：自动处理分包场景

### 适用场景

`weapp-vite` 特别适合以下场景：

1. **专注微信小程序开发**
   * 如果你只需要开发微信小程序，不需要跨端
   * 想要使用微信小程序最新特性（如 `Skyline`）

2. **原生小程序迁移**
   * 现有原生小程序项目想要现代化改造
   * 使用 `gulp` 或 `mina` 方案的项目想要升级

3. **轻量级需求**
   * 不需要完整的跨端框架
   * 希望保持原生开发方式，但需要现代化工具支持

### 不适用的场景

同样，目前 `weapp-vite` 并不适合以下场景：

* 需要完整跨端能力的框架
* 需要使用 `Vue`/`React` 等前端框架的写法，来取代小程序原生写法

毕竟深入小程序原生开发的人，其实要比懂 `Vue`/`React` 的人数少很多。

而且小程序的编写范式和体验，实际上也要比 `Vue`/`React` 差，我自从做小程序方向的开源项目以来，听到了无数次群友这方面吐槽，早已听出老茧了。

对于这种场景，推荐使用 `uni-app` 或 `Taro` 这种成熟的跨端框架。

## 快速开始

1. **创建项目**

```sh
# 使用 pnpm
pnpm create weapp-vite@latest

# 或使用 npm
npm create weapp-vite@latest
```

2. **安装依赖**

```sh
pnpm i  # 或 npm install
```

3. **开发命令**

```sh
pnpm dev  # 启动开发服务器
pnpm dev -o  # 启动开发并打开微信开发者工具
```

当然对应的使用文档都在 [`官方文档`](https://vite.icebreaker.top/) | [`备用官方文档`](https://vite.icebreaker.top/) 中。

## 结尾

最后一定要感谢我的用户们，他们为这个项目提供了许多非常有价值的反馈。

助力这个项目从一个个人实验性质的想法，升级到了一个正式的项目。

当然，也非常欢迎大家提出任何的改进意见，除了在群里交流之外，我其实更加希望大家使用提 [Issue](https://github.com/weapp-vite/weapp-vite/issues) 或 [Pull Request](https://github.com/weapp-vite/weapp-vite/pulls) 的方式。

另外，也希望看到这里的同学们，给 [`weapp-vite`](https://github.com/weapp-vite/weapp-vite) 点个 `Star` 吧! 大家的鼓励就是我继续前进的动力，Thanks!

---

---
url: /deep/init.md
description: >-
  Weapp-vite init 是在现有原生项目上接入 Weapp-vite
  的最快方式。它会检查当前目录结构、补齐必需的配置文件，然后提示你后续可以手动调整的地方。本节逐步拆解各项改动，方便团队在需要时自行定制或纯手动迁移。
---

# `weapp-vite init` 做了什么？

`weapp-vite init` 是在现有原生项目上接入 Weapp-vite 的最快方式。它会检查当前目录结构、补齐必需的配置文件，然后提示你后续可以手动调整的地方。本节逐步拆解各项改动，方便团队在需要时自行定制或纯手动迁移。

> \[!TIP]
> 如果你更倾向于完全手工搭建，也可以把下面每一小节视为 Checklist，按需执行对应步骤。

## 1. 修改 `project.config.json`

* 设置 `miniprogramRoot` 指向 Weapp-vite 产物目录（默认 `dist`），确保微信开发者工具预览/上传的始终是编译后的文件。
* 统一 `npm` 构建相关字段，避免与 Weapp-vite 的自动 npm 策略冲突。

> 手工迁移时，记得在开发者工具中重新选择项目根目录或刷新配置，使其指向新的 `dist` 路径。

## 2. 更新 `package.json`

* 添加 `pnpm dev`、`pnpm build`、`pnpm open` 等脚本，与 Weapp-vite CLI 对齐。
* 安装基础依赖（`weapp-vite`、`typescript`、`@types` 系列）以及推荐的工具链。

脚本示例：

```json
{
  "scripts": {
    "dev": "weapp-vite dev",
    "build": "weapp-vite build",
    "open": "weapp-vite open",
    "lint": "eslint . --ext .ts,.js --fix"
  }
}
```

## 3. 新增 `tsconfig.json` 与 `vite-env.d.ts`

* `tsconfig.json` 提供 TypeScript 编译基础配置，并启用小程序类型提示。
* `vite-env.d.ts` 声明 Weapp-vite 自动注入的全局类型，避免在编辑器中出现缺失提示。

如果项目暂不使用 TypeScript，也建议保留这些文件，以便后续随时开启类型支持。

## 4. 生成 `vite.config.[m]ts`

* 创建标准的 `vite.config.ts`（或 `vite.config.mts`）并写入 Weapp-vite 默认配置。
* 默认配置中包含 `weapp: { srcRoot: '.', subPackages: [] }` 等常用字段，你可以在此基础上继续补充别名、插件等设置。

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

export default defineConfig({
  weapp: {
    srcRoot: '.',
  },
})
```

> \[!IMPORTANT]
> 若项目目录结构特殊（例如 `app.json` 位于 `miniprogram/`），请记得修改 `srcRoot`，并结合 [基础目录与资源收集配置](/config/paths.md) 进行调优。

## 5. 更新 `.gitignore`

* 添加 `dist/`、`node_modules/`、临时缓存等条目，避免编译产物误入版本库。
* 如果项目已有 `.gitignore`，脚手架会合并新条目而非覆盖原内容。

## 6. 其他辅助文件

* 视情况添加 `README` 提示、`pnpm-workspace.yaml`（在 Monorepo 场景下）等文件。
* 对于 SCSS/Tailwind 等需要额外配置的工具，脚手架会保留注释提示下一步应该如何开启。

***

完成 `weapp-vite init` 后，建议依次执行：

1. `pnpm install` 安装依赖；
2. `pnpm dev --open` 验证项目能在微信开发者工具中正常运行；
3. 参考 [快速开始](/guide/) 继续进行页面开发或自定义配置。

如需还原或自定义初始化流程，可直接查看源码：[`@weapp-core/init`](https://github.com/weapp-vite/weapp-vite/tree/main/@weapp-core/init)。

---

---
url: /blog/announce.md
description: >-
  Weapp-vite 发布：重塑小程序开发体验！，聚焦 blog / announce 相关场景，覆盖 Weapp-vite 与 Wevu
  的能力、配置和实践要点。
---

![bg](./assets/release4.png)

# `weapp-vite` 发布：重塑小程序开发体验！

大家好，我是[`ice breaker`](https://github.com/sonofmagic)，也是[`weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss)项目的作者。

今天，我非常高兴地宣布`weapp-vite`项目的正式发布，这标志着我在`vite`框架应用与探索上的一个阶段性成果。

`weapp-vite`不仅是我对`vite`技术深入理解和实践的产物，更是我在小程序开发领域的一次创新尝试。该项目旨在结合`vite`的极速构建与热重载能力，为小程序开发者带来更加高效、流畅的开发体验。

通过`weapp-vite`，我们希望能够为小程序开发者提供一种全新的解决方案，让开发过程更加便捷、灵活。同时，我们也期待与广大开发者共同探索`vite`在小程序领域的更多可能性，共同推动小程序开发技术的进步与发展。

## 什么是 `weapp-vite`?

`weapp-vite` 是对 `vite` 的封装，专为小程序开发设计。

它保留了 `vite` 的强大配置和插件系统，同时针对小程序的开发流程进行了优化，支持 `ts`、`postcss`、`sass`、`less` 等现代前端技术栈，让小程序开发更加高效、便捷。

## 诞生背景

### 原生小程序开发的痛点

在深入探索小程序开发的过程中，我深刻体会到了原生小程序开发方式所带来的不便与局限。繁琐的构建流程、有限的工具支持，使得开发体验难以令人满意。同时，跨端框架如`uni-app`、`tarojs`等，虽然提供了多平台兼容的能力，但其基于`vue`、`react`等Web框架的写法，对于追求原生体验的开发者来说，显得过于沉重与冗余。此外，尽管这些框架开源，但源代码的复杂性往往让人望而却步，难以深入理解和定制。

### 差异化加剧的挑战

随着小程序生态的不断发展，各平台之间的差异日益显著。微信小程序凭借其持续的技术投入和创新，如`skyline`、`Donut`等项目的推进，展现出了强大的生命力和未来潜力。然而，这也对开发者提出了更高的要求，需要更加紧密地跟随官方技术动态，以充分利用平台优势。与此同时，其他平台也在不断探索和进步，但市场的竞争与变化使得开发者在选择和适配上面临更多挑战。

### 轻量化与灵活性的追求

鉴于上述痛点与挑战，我萌生了打造一款既轻量化又灵活的小程序开发解决方案的想法。`weapp-vite`应运而生，它保留了`vite`的极速构建与灵活配置优势，同时针对小程序开发流程进行了深度优化。通过引入编译插件系统，`weapp-vite`允许开发者以原生小程序语法为基础，轻松扩展至其他平台，实现所见即所得的跨端开发体验。

### `weapp-vite`的优势

* **轻量级构建**：专注于小程序开发的核心需求，提供极简的构建流程与配置选项。
* **灵活扩展**：利用`vite`的插件生态与编译插件系统，轻松实现功能的定制与增强。
* **高度自定义**：支持对小程序语法的深度自定义与转换，满足不同平台的开发需求。
* **紧跟官方步伐**：以原生小程序语法为基础，确保与官方技术动态保持同步。

综上所述，`weapp-vite`的诞生旨在解决原生小程序开发的痛点，提升开发效率与灵活性，同时保持对技术前沿的敏锐洞察与响应。我们期待与广大开发者携手共进，共同探索小程序开发的无限可能。

## 快速开始

### 创建与初始化

1. 在微信开发者工具中创建一个新的 `js`/`ts` 项目。

![微信开发者工具创建项目界面](../images/create-project.png)

2. 确保项目根目录下有 `package.json`，若无则运行 `npm init -y`

> 假如你创建的是一个 `ts` 项目，你需要在 `vite.config.ts` 里的 `weapp.srcRoot` 配置项，指明使用的是 `'./miniprogram'` 目录，详见本页下方

3. 安装 Weapp-vite 并执行初始化命令

```sh
npm i -D weapp-vite
# 执行初始化命令
npx weapp-vite init
```

于是就初始化成功了！然后再执行一下安装包的命令，去安装智能提示的类型定义

```sh
npm i
```

这样微信开发小程序的智能提示(`types`)，就也被安装进来

## 语言默认支持

你可以直接使用 `typescript`，把 `js` 改成 `ts` 后缀即可，也可以通过安装 `sass` / `less`，并把 `index.wxss` 的后缀名改成相应的后缀来支持样式预处理器，比如 `scss` / `less` 。

## 开发与构建

* 开发模式：使用 `npm run dev` 启动开发服务器，实时监听文件变化并自动编译。
* 构建模式：通过 `npm run build` 进行生产环境的构建，包括代码压缩等优化。
* 构建 npm：`npm run build-npm` 用于微信开发者工具中的 npm 构建，输出至 `dist/miniprogram_npm`。
* 打开微信开发者工具：`npm run open` 直接启动微信开发者工具，便捷调试。

## 配置项

配置项可以与 `vite` 通用，同时加入了 `weapp-vite` 的扩展:

`vite.config.ts`:

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

export default defineConfig({
  // 其他的配置同
  weapp: {
    // 用来配置监听 app.json 所在的目录
    // 比如默认情况下 ts 创建的项目，app.json 所在为 './miniprogram'
    srcRoot: './miniprogram',
    // weapp-vite options
  },
})
```

![Image](https://pic4.zhimg.com/80/v2-ebc9231004dc0d7582a21d3af7acd302.png)
你可以在 `defineConfig` 使用其他的 `vite` 插件，比如 `weapp-tailwindcss`

## 关于 `weapp-vite` 的承诺与展望

在过去的三年里，`weapp-tailwindcss` 不仅见证了小程序开发社区的蓬勃发展，也陪伴了无数开发者从初识到精通的旅程。这份历程教会了我耐心、细致与不懈追求。现在，我将这份恒心带入 `weapp-vite`，致力于打造一个更加高效、灵活且易于使用的小程序开发解决方案。

## 期待大家的加入

`weapp-vite` 刚刚起步，虽已初具雏形，但仍有许多待完善之处。我诚挚邀请各位开发者加入我们的行列，共同推动项目的成长：

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

## 未来展望

展望未来，`weapp-vite` 将不断进化以适应小程序开发的最新趋势。我们将持续关注各平台小程序的更新迭代，确保 `weapp-vite` 能够无缝兼容并充分利用这些新特性。同时，我们也期待与广大开发者建立更加紧密的联系，听取大家的意见与建议，共同推动 `weapp-vite` 的发展与完善。

## 尾言

感谢每一位对 `weapp-tailwindcss` 及 `weapp-vite` 给予关注与支持的朋友。让我们携手并进，在小程序开发的道路上不断前行，共创辉煌！

[GitHub 项目地址](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/packages/weapp-vite)

---

---
url: /blog/drafts/weapp-vite-rethinking-slidev.md
description: 用于 20-30 分钟技术分享的 Slidev 稿件，聚焦 AI 协作、原子化样式、分包治理、HMR 与语法重写的工程化实践。
---

# Weapp-vite: 对小程序工程化的重新思考

副标题：从“功能堆叠”到“工程系统”

***

## layout: default

# 这场分享你能带走什么

* 一个可复用的工程化判断框架（5 个维度）
* Weapp-vite 的关键取舍，而不是参数清单
* 一份可落地的 30 天迁移/升级路线

- 适合对象：技术负责人、架构师、核心开发
- 假设前提：你已经做过中大型小程序项目

***

# 目录

1. 为什么要“重新思考”
2. AI：从提示词到工程接口
3. 样式：原子化背后的组织收益
4. 分包：从“能分”到“分得对”
5. HMR：快只是起点，稳定快才是目标
6. 语法重写：编译链路 + 运行时双重设计
7. 30 天落地计划

***

# 问题不在“有没有功能”

很多团队已经有：

* Vue 写法
* 分包配置
* 热更新工具
* Tailwind 或其他原子化方案
* AI 编码助手

但依然会遇到：

* 协作不稳定
* 迭代速度波动
* 包体与首开相互拉扯
* 语法升级后运行时问题变多

***

## layout: center

# 核心观点

## 小程序工程化的关键，不是多支持一种写法

## 而是把开发、构建、调试、协作接成一条链路

***

## layout: section

# 1) AI 协作

从“会写代码”到“可控地参与工程”

***

# AI 协作的三层结构

```mermaid
flowchart LR
  A[Skills<br/>流程约束] --> B[MCP<br/>仓库能力暴露]
  B --> C[llms.txt<br/>上下文入口]
  C --> D[可执行协作链路]
```

* Skills：减少“看起来对，执行跑偏”
* MCP：让 AI 真正读代码、跑命令、调用工具
* llms：降低上下文遗漏和误判

***

# 这不是文档口号，有源码落地

关键证据：

* `packages/weapp-vite/src/defaults.ts`
  * `mcp.enabled: true`
  * `mcp.autoStart: false`
* `packages/weapp-vite/src/mcp.ts`
  * 提供 `stdio` / `streamable-http`
* `packages/weapp-vite/src/cli/commands/mcp.ts`
  * 直接支持 `weapp-vite mcp`

结论：AI 不是外挂窗口，而是工程内角色。

***

# 团队落地建议（AI）

* 先统一 Skills 触发词和任务模板
* MCP 只开放必要能力，避免过宽权限
* 在 PR 模板里增加一条：
  * 本次变更是否可被 AI 工作流复现

一句话：把 AI 变成“可审计的协作者”。

***

## layout: section

# 2) 原子化样式

不是审美选择，是治理选择

***

# 为什么是“治理问题”

样式体系一旦规模化，痛点通常是：

* 重复样式不断增长
* 组件样式语义不统一
* 改一个设计 token 需要大量回归

原子化样式的价值：

* 让样式复用从“复制”变“组合”
* 让设计约束从“约定”变“语法”

***

# Weapp-vite 的处理方式：集成，而不重造

* 文档入口：`website/integration/tailwindcss.md`
* 脚手架：`create-weapp-vite` 自动补齐 `weapp-tailwindcss`
  * `packages/create-weapp-vite/src/createProject.ts`
* HMR 细节：检测到 `weapp-tailwindcss` 时自动 touch `app.wxss`
  * `packages/weapp-vite/src/runtime/buildPlugin/touchAppWxss.ts`

这让“原子化写法”与“开发体验”绑定在同一条链路上。

***

# 样式体系的三个常见误区

1. 把原子化当作“少写 CSS”的工具
2. 没有组件级样式边界规范
3. 缺少设计 token 与业务语义的映射层

建议：

* 先定 token，再定 class 约定
* 每个业务域维护最小组件样式规范
* 将“样式变更成本”纳入迭代评估

***

## layout: section

# 3) 分包策略

从“会分”到“分得对”

***

# 分包真正的决策点

你每次都在做权衡：

* 首开速度优先？
* 总体积优先？
* 共享模块复制还是提炼？

`weapp-vite` 把这件事显式化为策略：

* `sharedStrategy: 'duplicate'`（默认）
* `sharedStrategy: 'hoist'`

***

# `duplicate` vs `hoist`（工程视角）

| 策略        | 更适合       | 代价                         |
| ----------- | ------------ | ---------------------------- |
| `duplicate` | 分包首开体验 | 可能增加冗余体积             |
| `hoist`     | 控制总体积   | 分包首开可能依赖主包共享模块 |

源码锚点：

* `packages/weapp-vite/src/runtime/chunkStrategy/apply.ts`
* `packages/weapp-vite/src/runtime/chunkStrategy/bundle.ts`
* `packages/weapp-vite/src/plugins/core/lifecycle/emit.ts`

***

# 分包治理建议

* 开发初期优先 `duplicate`（先保证体验）
* 稳定期结合数据评估是否切 `hoist`
* 使用 `weapp-vite analyze` 定期审查跨包共享与冗余
* 设定冗余体积告警阈值（`duplicateWarningBytes`）

结论：分包不是“配置一次就结束”，而是持续运营。

***

## layout: section

# 4) HMR

快很重要，稳定地快更重要

***

# 为什么很多团队 HMR 体验会波动

常见现象：

* 某些改动很快，某些改动突然变慢
* 共享模块改动后偶发不一致
* “为了稳”被迫全量重建

`weapp-vite` 的思路：

* 默认 `sharedChunks: 'auto'`
* 能局部更新就局部更新
* 风险场景自动回退全量发射

***

# HMR 证据与逻辑

性能参考（`website/migration/v5.md`）：

* 整体平均构建：约 `1.86x` 提升
* 热更新平均构建：约 `2.50x` 提升

关键逻辑文件：

* `packages/weapp-vite/src/plugins/hooks/useLoadEntry/index.ts`
* `packages/weapp-vite/src/plugins/core/lifecycle/watch.ts`

一句话：在正确性边界内，尽量缩小重建范围。

***

## layout: section

# 5) 语法重写

不是“套个 Vue 壳”，而是编译 + 运行时协同

***

# 编译侧：完整阶段管线

`wevu-compiler` 中，`compileVueFile` 走的是完整链路：

1. `parse`
2. `template`
3. `script`
4. `style`
5. `config`
6. `finalize`

核心文件：

* `packages/wevu-compiler/src/plugins/vue/transform/compileVueFile/index.ts`
* `packages/wevu-compiler/src/plugins/vue/transform/compileVueFile/parse.ts`

***

# 模板与宏：结构化转换

* `v-if / v-else-if / v-else`
  * `.../template/elements/tag-structural.ts`
* `v-for` alias/作用域解析
  * `.../template/elements/tag-structural.ts`
* `v-model` 宿主控件差异绑定
  * `.../template/directives/model.ts`
* `definePageJson / defineComponentJson / defineAppJson`
  * `.../transform/jsonMacros/*`

这不是字符串替换，而是语义级编译。

***

# 运行时：为什么坚持 `diff + setData`

运行时关键文件：

* `packages/wevu/src/runtime/diff.ts`

关注点：

* 快照 plain 化（可序列化）
* 差量路径计算
* 最小化 `setData` payload

这与小程序运行模型是对齐的。

***

# 为什么不是 `createRenderer` 主路线

结论不是“不能做”，而是“主线不划算”。

原因：

* `createRenderer` 假设 host 节点操作模型
* 小程序核心更新模型是 `setData(payload)`
* 抽象错位会引入额外维护与性能成本

延伸阅读：

* `website/wevu/why-not-runtime-core-create-renderer.md`

***

## layout: section

# 6) 30 天落地计划

把“理念”变成“节奏”

***

# 第 1 周：基线盘点

* 跑一次 `weapp-vite analyze`，输出包体与共享模块图
* 盘点当前 HMR 耗时波动区间
* 梳理样式体系现状：token、组件、重复率
* 明确 AI 协作入口（Skills/MCP/llms）

交付物：当前状态基线报告。

***

# 第 2-3 周：小步试点

* 选 1 个业务分包试点 `duplicate/hoist` 策略
* 选 1 条页面链路试点 Vue SFC + wevu
* 选 1 个模块试点 AI 流程化协作

评估维度：

* 首开性能
* 迭代效率
* 缺陷率
* 回归成本

***

# 第 4 周：固化规则

* 形成团队配置基线（hmr/chunks/style）
* 把 AI 工作流写入工程文档与 PR 模板
* 制定版本节奏：每次迭代固定做一次 analyze
* 建立告警阈值：包体冗余、构建耗时、回归失败率

一句话：让工程化从“人治”变“机制”。

***

## layout: center

# 总结

## Weapp-vite 的价值不在“功能数量”

## 而在“系统一致性”

* AI：可控协作
* 样式：可持续治理
* 分包：可解释策略
* HMR：可预期速度
* 语法：可对齐运行模型

***

## layout: center

# Q\&A

感谢聆听

---

---
url: /blog/drafts/weapp-vite-rethinking-release.md
description: 这不是功能清单，而是一篇面向真实项目的工程复盘：AI 协作、原子化样式、分包策略、热更新速度和语法重写，应该如何放进同一条链路。
---

# Weapp-vite: 对小程序工程化的重新思考

这几年大家聊小程序工程化，常见写法是“能力罗列”：支持 Vue、支持分包、支持热更新、支持某某插件。

但做过中大型项目的人都知道，真正让团队每天付出成本的，往往不是“有没有这个功能”，而是“这些能力能不能被组织成一套稳定流程”。

`weapp-vite` 想解决的，正是后者。

## 第一件事：AI 协作必须进入工程上下文

AI 写代码已经不稀奇。稀缺的是让 AI 在你项目里“可控地工作”。

`weapp-vite` 在文档里把这件事拆成了三层：`Skills` 提供稳定流程，`MCP` 暴露仓库能力，`llms.txt` 统一上下文入口。它不是让 AI 猜项目，而是给 AI 接口。

从源码看，这套能力也不是“贴在文档里的建议”：`mcp` 默认可用，`weapp-vite mcp` 可以直接启动服务，支持 `stdio` 和 `streamable-http`。这意味着 AI 可以真正进入你的日常研发链路，不再只当外部聊天工具。

## 第二件事：原子化样式不是审美问题，是维护问题

当页面规模起来以后，样式维护会迅速变成团队负担。原子化样式真正的价值不是“class 很酷”，而是把样式治理从“文件复制粘贴”变成“规则复用”。

`weapp-vite` 在这块很克制：不重新造样式 DSL，而是把 `weapp-tailwindcss` 纳入默认工作流。

* 脚手架创建项目时会自动补齐 `weapp-tailwindcss` 依赖版本。
* 开发态下可自动 touch `app.wxss` 触发开发者工具热重载。
* 配置层面提供 `weapp.hmr.touchAppWxss`，并支持 `auto` 模式。

这类细节很小，但它决定了原子化样式在日常开发里到底是顺手还是反复“手动刷新”。

## 第三件事：分包不是开关，而是策略

很多工具都“支持分包”，但工程上要回答的是另一个问题：共享代码到底落主包还是落分包。

`weapp-vite` 的默认策略是 `duplicate`，把跨分包共享 chunk 复制到各分包，优先分包首开体验；你也可以切到 `hoist`，把共享代码提炼进主包，优先控制总体体积。

它的价值不在“多两个配置项”，而在于把取舍变成显式策略：你可以按业务阶段选择“更快首开”或“更小总包”，而不是接受一个黑箱结果。

## 第四件事：热更新速度，核心是稳定快

`rolldown-vite` 带来了一次明显提速，这点在升级文档里已有量化数据。

但更重要的是后续实现：`weapp-vite` 的 HMR 在 `auto` 策略下会判断共享 chunk 导入关系，能局部更新就局部更新，只有在可能造成共享导出不一致时才回退全量发射。

这让“快”从偶发幸运变成可预期体验。对团队来说，这比一次跑分更有意义。

## 第五件事：语法重写必须和运行时一起做

`weapp-vite + wevu` 的重点从来不是“可以写 `.vue`”，而是“写法升级后，运行模型依然贴合小程序”。

编译侧会把 `v-if`、`v-for`、`v-model`、`<script setup>` JSON 宏等能力做结构化转换；运行时则坚持 `diff + setData` 的路径，把优化重点放在 payload 体积和更新频率上。

这也是它没有把 `createRenderer` 当主路线的原因。小程序的核心语义不是 DOM 节点操作，而是数据快照下发。抽象不对齐，就会平白增加一层成本。

## 最后

如果要用一句话概括这篇文章，我更愿意这样说：

`weapp-vite` 做的不是“多支持几种语法”，而是把小程序工程化里最痛的几件事，重新接成一条可验证、可协作、可持续演进的链路。

这条链路里，AI、样式、分包、热更新和语法重写，不再是五个孤立功能，而是一套能一起工作的系统。

---

---
url: /blog/drafts/weapp-vite-rethinking-deep-dive.md
description: 从源码与文档出发，拆解 Weapp-vite 在 AI 协作、原子化样式、分包策略、HMR 和 Vue SFC 语法重写上的工程取舍。
---

# Weapp-vite: 对小程序工程化的重新思考

这篇文章不是“新特性导览”，也不是“和别家对比”。
我想回答一个更具体的问题：

一个中大型小程序项目，怎样才算工程化做对了？

我自己的判断标准有 5 条：

1. AI 能不能真正进入研发链路，而不是只在群聊里写 demo。
2. 样式体系能不能稳定扩张，而不是规模一大就失控。
3. 分包有没有明确策略，能不能按业务目标调参。
4. 热更新是否稳定地快，能否支持高频试错。
5. 语法升级是不是编译和运行时一起重构，而不只是“壳子像 Vue”。

`weapp-vite` 的价值，在于它把这 5 条放进了同一套系统。

## 1. AI 协作：从“提示词”走向“工程接口”

不少团队接入 AI 后，最大问题不是模型能力，而是输出不稳定：今天能用，明天跑偏。

`weapp-vite` 文档把协作链路拆成了三个稳定层：

* `Skills`：约束 AI 工作流程。
* `MCP`：把仓库能力暴露给 AI（读代码、跑命令、调用工具）。
* `llms.txt`：给模型可控上下文入口。

这个设计在源码层是有落地的：

* `packages/weapp-vite/src/defaults.ts`：`mcp` 默认启用（`enabled: true`，`autoStart: false`）。
* `packages/weapp-vite/src/mcp.ts`：实现服务启动与配置解析，支持 `stdio` 和 `streamable-http`。
* `packages/weapp-vite/src/cli/commands/mcp.ts`：提供 `weapp-vite mcp` 命令入口。

工程含义很直接：
你不是在“让 AI 猜你的项目结构”，而是在“把项目能力显式暴露给 AI”。

## 2. 原子化样式：核心收益是治理成本下降

原子化样式在小程序里讨论很多，但常见误区是只盯着“写法是否简洁”。
实际收益在于治理：

* 统一设计 token 和工具类，减少跨页面样式漂移。
* 把修改成本集中到规则层，而不是大量样式文件搜索替换。

`weapp-vite` 在这件事上采用“集成而不重造”的路径：

* 文档侧提供 Tailwind 集成入口（`website/integration/tailwindcss.md`）。
* 脚手架 `create-weapp-vite` 创建项目时会自动处理 `weapp-tailwindcss` 依赖（`packages/create-weapp-vite/src/createProject.ts`）。
* HMR 层提供 `touchAppWxss` 自动行为（`packages/weapp-vite/src/runtime/buildPlugin/touchAppWxss.ts` 与 `service.ts`），在检测到 `weapp-tailwindcss` 时自动触发样式热重载。

这类看似“工具细节”的设计，决定了原子化样式在团队里是“长期资产”还是“初期好用，后期负担”。

## 3. 分包策略：从“可用”走向“可调”

小程序的分包不是新概念，难点在策略：

* 你更在意分包首开速度，还是总体包体积？
* 共享模块该复制还是上提？
* 主包与分包共同引用时，怎么避免错误分发？

`weapp-vite` 在文档与实现上给了完整答案。

文档侧：

* 分包实践：`website/guide/subpackage.md`
* 配置说明：`website/config/shared.md#weapp-chunks`

实现侧：

* `packages/weapp-vite/src/runtime/chunkStrategy/apply.ts`
* `packages/weapp-vite/src/runtime/chunkStrategy/bundle.ts`
* `packages/weapp-vite/src/plugins/core/lifecycle/emit.ts`

关键策略点：

1. `sharedStrategy: 'duplicate'`（默认）
   目标是优先分包首开，跨分包共享代码复制到分包共享目录。
2. `sharedStrategy: 'hoist'`
   目标是优先控制总体体积，共享代码提炼进主包。
3. 主包共同引用回退逻辑
   当共享模块同时被主包使用时，系统可自动回退，避免拆分错误。

这让“分包优化”从经验拍脑袋，变成可解释、可调参、可验证的工程动作。

## 4. HMR：速度提升之外，重点是稳定性

从 v5 开始，`weapp-vite` 转向 `rolldown-vite`。
文档给过一组参考数据（`website/migration/v5.md`）：

* 整体平均构建时间：约 `1.86` 倍提升。
* 热更新平均构建时间：约 `2.50` 倍提升。

但 HMR 真正的含金量在实现策略，不只在基准数据。

源码链路中有两个关键点：

1. `packages/weapp-vite/src/plugins/hooks/useLoadEntry/index.ts`
   在 `sharedChunks: 'auto'` 下，系统会根据“脏 entry + 共享 chunk 导入图”判断是否需要全量发射。
2. `packages/weapp-vite/src/plugins/core/lifecycle/watch.ts`
   文件变化会回溯影响入口并标记 dirty，尽可能缩小重建范围。

结果是：
开发体验不是“偶尔很快”，而是“多数场景下稳定快，且在高风险场景下自动回退保正确性”。

## 5. 语法重写：编译链路与运行时一起重构

很多人看到 Vue SFC 支持，第一反应是“可以写 `.vue` 了”。
真正的工程难点其实在：如何让这套写法在小程序运行模型下依然成立。

### 5.1 编译侧：结构化转换，不是字符串替换

在 `wevu-compiler` 里，`compileVueFile` 走完整阶段管线：

* `parse`
* `template`
* `script`
* `style`
* `config`
* `finalize`

对应文件：

* `packages/wevu-compiler/src/plugins/vue/transform/compileVueFile/index.ts`
* `packages/wevu-compiler/src/plugins/vue/transform/compileVueFile/parse.ts`

模板转换关键点：

* `v-if / v-else-if / v-else`：`tag-structural.ts`
* `v-for` 作用域与别名解析：`tag-structural.ts`
* `v-model` 宿主控件差异绑定：`directives/model.ts`

### 5.2 JSON 宏：把配置前移到编译期

`<script setup>` 里的 `definePageJson / defineComponentJson / defineAppJson` 会在编译时提取并剥离运行时代码：

* `packages/wevu-compiler/src/plugins/vue/transform/jsonMacros/index.ts`
* `packages/wevu-compiler/src/plugins/vue/transform/jsonMacros/parse.ts`
* `packages/wevu-compiler/src/plugins/vue/transform/jsonMacros/rewrite.ts`

这让页面/组件配置可以写在同一份 SFC 上下文里，同时保持运行时零成本。

### 5.3 运行时：坚持 `diff + setData` 路线

运行时核心在 `packages/wevu/src/runtime/diff.ts`。
它处理的是“小程序真实约束”：

* 快照 plain 化（可序列化）。
* 路径级差量比对。
* 最小化 `setData` payload。

这也是 Wevu 不把 `createRenderer` 作为主路线的根本原因。
小程序更新语义是数据下发，不是 host 节点操作。抽象层错位，往往只会引入额外成本。

延伸阅读：`website/wevu/why-not-runtime-core-create-renderer.md`

## 结论：真正的工程化，是把孤立能力接成系统

回到文章开头的 5 个问题，`weapp-vite` 给出的并不是“单点功能集合”，而是一套互相咬合的工程体系：

* AI 有稳定入口。
* 样式有长期治理路径。
* 分包有可解释策略。
* HMR 有速度和正确性的平衡机制。
* 语法升级有编译与运行时双落地。

这也是我理解的“重新思考”：
不是改一层 API 皮肤，而是把开发、构建、调试和协作的底层关系重新组织一遍。

---

---
url: /blog/drafts/weapp-vite-rethinking-slidev-detailed.md
description: 面向分享场景的 Slidev 完整案例稿，覆盖 AI 协作、原子化样式、分包策略、HMR 与语法重写的可执行演示流程。
---

# Weapp-vite: 对小程序工程化的重新思考

## 案例演示完整版（20-30 分钟）

***

# 这版分享解决什么问题

* 把“工程理念”变成“可执行演示”
* 每个案例都有配置和产物，不靠口头描述
* 你讲完后，团队可以按 slide 直接复现

- 案例 1：AI 协作验收（MCP + screenshot）
- 案例 2：原子化样式（Tailwind 动态类）
- 案例 3：超强分包（duplicate vs hoist）
- 案例 4：快速热更新（auto-routes HMR）
- 案例 5：语法重写（defineAppJson + autoRoutes）

***

# 演示约定

* 所有案例都来自仓库真实路径
* 命令优先使用仓库已有 e2e / fixture
* 结果产出分三类：
  * 文件产出
  * 内容产出
  * 日志/状态产出

***

## layout: section

# 案例 1

AI 协作验收：MCP 驱动截图

***

# 案例 1 - 演示目标

目标：让 AI 从“聊天建议”变成“可验收执行者”

场景：

* 构建一个 e2e app
* 调用 `weapp-vite screenshot`
* 产出截图文件并给出机器可读结果

来源文档：`website/guide/ai.md`

***

# 案例 1 - 演示步骤

```bash
# 1) 启动 MCP（本地）
weapp-vite mcp --transport streamable-http --host 127.0.0.1 --port 3088 --endpoint /mcp
```

把下面提示词交给接入 MCP 的 AI 客户端：

```text
你现在连接的是 weapp-vite MCP。
1. 构建 e2e-apps/auto-routes-define-app-json（platform=weapp）。
2. 执行 weapp-vite screenshot：
   - project: e2e-apps/auto-routes-define-app-json/dist/build/mp-weixin
   - page: pages/home/index
   - output: .tmp/mcp-screenshot.png
3. 存在输出 screenshot-ok，不存在输出 screenshot-missing。
```

***

# 案例 1 - 配置点

默认配置（源码）：`packages/weapp-vite/src/defaults.ts`

```ts
const weappConfig = {
  mcp: {
    enabled: true,
    autoStart: false,
    host: '127.0.0.1',
    port: 3088,
    endpoint: '/mcp',
  },
}
```

命令入口（源码）：

* `packages/weapp-vite/src/mcp.ts`
* `packages/weapp-vite/src/cli/commands/mcp.ts`

***

# 案例 1 - 结果产出

预期结果：

1. AI 返回 `screenshot-ok`
2. 工作区出现 `.tmp/mcp-screenshot.png`

验收价值：

* 有“状态值”（ok/missing）
* 有“制品文件”（png）
* 可直接接 CI 或自动化验收

***

## layout: section

# 案例 2

原子化样式：Tailwind 动态类编译

***

# 案例 2 - 演示目标

目标：证明动态 class 在小程序产物中可控落地

示例项目：`e2e-apps/issue-814-tailwind4`

源码页面：

* `e2e-apps/issue-814-tailwind4/src/pages/index/index.vue`

核心源码片段：

```vue
<view :class="[`flex${bbb} gap-[17px]`, aaa]">
```

***

# 案例 2 - 演示步骤

```bash
node packages/weapp-vite/bin/weapp-vite.js \
  build e2e-apps/issue-814-tailwind4 \
  --platform weapp \
  --skipNpm
```

然后查看产物：

* `dist/pages/index/index.wxml`
* `dist/pages/index/index.js`

***

# 案例 2 - 配置

`e2e-apps/issue-814-tailwind4/weapp-vite.config.ts`

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

export default defineConfig({
  weapp: {
    srcRoot: 'src',
  },
})
```

补充：开发态样式热重载可用

* `weapp.hmr.touchAppWxss: 'auto'`
* 检测到 `weapp-tailwindcss` 时自动启用（源码：`touchAppWxss.ts`）

***

# 案例 2 - 结果产出

`index.wxml`（真实产物）

```html
<view class="flex gap-_b24px_B">...</view>
<view class="{{__wv_cls_0}}">...</view>
```

`index.js`（真实产物片段）

```js
const classExpr = `flex${this.bbb} gap-_b17px_B`
```

结果说明：

* 动态类被编译到运行时表达式
* 任意值 `gap-[17px]` 转义为 `gap-_b17px_B`

***

## layout: section

# 案例 3

超强分包：`duplicate` vs `hoist`

***

# 案例 3 - 演示目标

目标：让“分包策略”可视化，而不是口头解释

示例 fixture：

* `packages/weapp-vite/test/fixtures/subpackage-dayjs`

验证用例：

* `packages/weapp-vite/test/subpackage-dayjs.test.ts`

***

# 案例 3 - 演示步骤

你可以直接跑这个测试：

```bash
pnpm vitest run packages/weapp-vite/test/subpackage-dayjs.test.ts
```

这个测试会分别构建两种模式：

* `sharedStrategy: 'duplicate'` -> 输出到 `dist-duplicate`
* `sharedStrategy: 'hoist'` -> 输出到 `dist-hoist`

***

# 案例 3 - 配置

测试里用的是内联配置（简化后）：

```ts
weapp: {
  chunks: {
    sharedStrategy: 'duplicate' // 或 'hoist'
  }
}
```

策略含义：

* `duplicate`：共享模块复制到分包
* `hoist`：共享模块提炼到主包 `common.js`

***

# 案例 3 - 结果产出（产物差异）

`duplicate` 模式下：

* `packageA/weapp-shared/common.js`
* `packageB/weapp-shared/common.js`

`hoist` 模式下：

* 主包 `common.js`
* 分包不再有 `weapp-shared/common.js`

***

# 案例 3 - 结果产出（代码差异）

`duplicate` 的页面引用（真实产物）：

```js
require('../weapp-shared/common.js')
```

`hoist` 的页面引用（真实产物）：

```js
require('../../common.js')
```

这就是“超强分包”的可验证证据。

***

## layout: section

# 案例 4

快速热更新：auto-routes HMR

***

# 案例 4 - 演示目标

目标：展示 HMR 不只是快，还要“结构同步正确”

示例用例：

* `e2e/ci/auto-routes-hmr.test.ts`
* 项目：`e2e-apps/auto-routes-define-app-json`

验证内容：

* 新增/删除页面后，`typed-router.d.ts` 同步
* `app.json` 与 `app.js` 路由快照同步

***

# 案例 4 - 演示步骤

```bash
node --import tsx packages/weapp-vite/bin/weapp-vite.js \
  dev e2e-apps/auto-routes-define-app-json \
  --platform weapp \
  --skipNpm
```

然后在运行中：

1. 新建 `src/pages/logs/hmr-added.vue`
2. 观察 `typed-router.d.ts`
3. 删除该文件，观察回滚

***

# 案例 4 - 配置

`e2e-apps/auto-routes-define-app-json/weapp-vite.config.ts`

```ts
export default defineConfig({
  weapp: {
    srcRoot: 'src',
    autoRoutes: true,
  },
})
```

HMR 默认策略（源码默认值）：

```ts
const hmr = {
  sharedChunks: 'auto',
  touchAppWxss: 'auto',
}
```

***

# 案例 4 - 结果产出

来自 e2e 断言的结果：

* `typed-router.d.ts` 包含新增路由后再移除
* `dist/app.json` 的 `pages` 与 `subPackages` 保持正确
* `dist/app.js` 的 `__autoRoutesPages/__entries/__subPackages` 同步

关键点：

* 快，不是唯一目标
* 快 + 同步正确，才是可用 HMR

***

## layout: section

# 案例 5

语法重写：`defineAppJson` + `autoRoutes`

***

# 案例 5 - 演示目标

目标：证明“语法重写”是编译链路行为，不是魔法

示例源码：

* `e2e-apps/auto-routes-define-app-json/src/app.vue`

关键写法：

```ts
defineAppJson({
  pages: routes.pages,
  subPackages: routes.subPackages,
})
```

***

# 案例 5 - 演示步骤

```bash
node packages/weapp-vite/bin/weapp-vite.js \
  build e2e-apps/auto-routes-define-app-json \
  --platform weapp \
  --skipNpm
```

重点查看三个产物：

* `dist/app.json`
* `dist/app.js`
* `typed-router.d.ts`

***

# 案例 5 - 配置

`weapp-vite.config.ts`

```ts
export default defineConfig({
  weapp: {
    autoRoutes: true,
  },
})
```

编译侧关键事实：

* `defineAppJson` 在编译期提取
* 路由列表来自 `weapp-vite/auto-routes`
* 类型文件 `typed-router.d.ts` 自动生成

***

# 案例 5 - 结果产出（真实文件）

`dist/app.json`：

```json
{
  "pages": [
    "pages/dashboard/index",
    "pages/detail/index",
    "pages/home/index",
    "pages/logs/index"
  ],
  "subPackages": [
    { "root": "subpackages/lab", "pages": ["pages/state-playground/index"] },
    { "root": "subpackages/marketing", "pages": ["pages/campaign/index"] }
  ]
}
```

***

# 案例 5 - 结果产出（运行时快照）

`dist/app.js`（真实片段）包含：

```js
const globalData = {
  __autoRoutesPages: ['pages/home/index'],
  __autoRoutesEntries: ['pages/home/index', 'subpackages/marketing/pages/campaign/index'],
  __autoRoutesSubPackages: [{ root: 'subpackages/marketing', pages: ['pages/campaign/index'] }],
}
```

`typed-router.d.ts`（真实片段）包含：

```ts
export type AutoRoutesPages = [
  'pages/dashboard/index',
  'pages/detail/index',
  'pages/home/index',
  'pages/logs/index'
]
```

***

## layout: section

# 把 5 个案例串成一条链路

***

# 一张图看完整工程化链路

```mermaid
flowchart LR
  A[AI 协作入口<br/>MCP/Skills] --> B[源码编写<br/>SFC + Tailwind]
  B --> C[构建策略<br/>chunks/HMR]
  C --> D[产物验证<br/>dist + typed-router]
  D --> E[回归与验收<br/>screenshot/e2e]
```

结论：

* 单点能力不会自动形成工程系统
* 把能力串成闭环，团队效率才会稳定增长

***

# 附：5 个案例可直接复用的最小命令

```bash
# 案例1：AI + MCP
weapp-vite mcp --transport streamable-http --host 127.0.0.1 --port 3088 --endpoint /mcp

# 案例2：Tailwind 动态类
node packages/weapp-vite/bin/weapp-vite.js build e2e-apps/issue-814-tailwind4 --platform weapp --skipNpm

# 案例3：分包策略验证
pnpm vitest run packages/weapp-vite/test/subpackage-dayjs.test.ts

# 案例4：HMR 路由同步
node --import tsx packages/weapp-vite/bin/weapp-vite.js dev e2e-apps/auto-routes-define-app-json --platform weapp --skipNpm

# 案例5：语法重写产物
node packages/weapp-vite/bin/weapp-vite.js build e2e-apps/auto-routes-define-app-json --platform weapp --skipNpm
```

***

## layout: center

# 总结

## 工程化不是“工具堆叠”

## 是“可演示 + 可配置 + 可验证”的系统能力

* 每个案例都有配置
* 每个案例都有结果产出
* 每个案例都能在仓库复现

***

## layout: center

# Q\&A

---

---
url: /blog/drafts/weapp-vite-rethinking.md
description: 这不是一篇功能罗列，而是从源码与文档出发，重新讨论小程序工程化里最关键的 5 件事：AI 协作、原子化样式、分包策略、热更新速度和语法改写。
---

# Weapp-vite: 对小程序工程化的重新思考

很多人聊小程序工程化，最后都会落成一份工具清单：支持了什么、兼容了什么、能跑到多少端。

但如果你真的在业务里维护过一个中大型小程序项目，你会发现真正折磨人的从来不是“有没有这个功能”，而是另外几件事：

* 团队能不能稳定协作，尤其是和 AI 协作时，输出是否可控。
* 样式体系能不能长期维护，而不是三个月后全靠搜索替换。
* 分包到底是“能配上”还是“能吃透”，包体、首开、复用有没有工程策略。
* 热更新是不是快到可以让人愿意频繁改、频繁试。
* 语法升级是不是只停留在表面，还是从编译和运行时一起重写过。

`weapp-vite` 有意思的地方在于，它不是把这些问题拆开做，而是把它们连成了一条完整链路。

## 1. AI 不是“外挂”，而是工程链路的一部分

很多项目谈 AI，停留在“可以让 AI 生成代码”。`weapp-vite` 的做法更务实：先把 AI 放进可验证的工程上下文里。

文档里已经把协作路径写得很清楚了：`Skills` 负责给 AI 固定流程，`MCP` 负责把仓库能力暴露给 AI，`llms.txt` 负责给模型稳定喂上下文（见 `/guide/ai`）。

这件事在源码里不是口号。`packages/weapp-vite/src/defaults.ts` 里，`mcp` 默认就是启用状态（`enabled: true`，`autoStart: false`）；`packages/weapp-vite/src/mcp.ts` 和 `src/cli/commands/mcp.ts` 直接提供了 `weapp-vite mcp` 的启动入口，支持 `stdio` 和 `streamable-http` 两种传输。

这意味着，AI 在这个体系里不是“另一个聊天窗口”，而是一个能真实读仓库、跑命令、走工程规则的参与者。

说白了：你不是在“让 AI 猜你的项目”，你是在“给 AI 一套可执行的项目接口”。

## 2. 原子化样式的价值，不在于 class 多酷

小程序项目一旦变大，样式问题很快会演变成组织问题。你用不用原子化样式，最后比拼的不是审美，而是迭代成本。

`weapp-vite` 本身没有重复造一个样式 DSL，而是把 `weapp-tailwindcss` 放进工程默认路径。

* 文档层面：`/integration/tailwindcss` 直接把 Tailwind 集成当作一等路径。
* 脚手架层面：`packages/create-weapp-vite/src/createProject.ts` 在创建项目时会自动补齐 `weapp-tailwindcss` 依赖版本。
* 开发体验层面：`weapp.hmr.touchAppWxss` 默认是 `auto`，当检测到安装了 `weapp-tailwindcss` 时，会在开发构建结束后 touch `app.wxss` 来触发开发者工具热重载（见 `runtime/buildPlugin/touchAppWxss.ts` 和 `runtime/buildPlugin/service.ts`）。

这组设计背后的思路很实在：

第一，样式原子化不是“可选潮流”，而是把样式治理从“文件级维护”改成“规则级维护”。
第二，工具链要主动适配这套工作流，而不是把热更新问题甩给开发者手动刷新。

## 3. 分包能力的关键，不是会分，而是怎么分

小程序都支持分包，但“支持分包”和“分包可控”是两回事。

`weapp-vite` 在这块做得比较深。文档 `/guide/subpackage` 和 `/config/shared#weapp-chunks` 讲了策略，源码 `runtime/chunkStrategy/apply.ts` 负责真正执行：

* 默认 `sharedStrategy: 'duplicate'`，把跨分包共享 chunk 复制到各分包，优先保证分包首开体验。
* 可切到 `hoist`，把共享代码提炼回主包，优先压总体体积。
* 如果共享模块同时被主包引用，策略会自动回退并保留主包版本，避免错误拆分。
* 独立分包走独立构建上下文，和主包彻底隔离。

这不是“多了几个配置项”这么简单。

它真正解决的是工程里的老问题：同一份共享代码，到底应该为“更快首开”付费，还是为“更小总包”付费。`weapp-vite` 给了明确可切换的策略，而不是只给一个黑箱结果。

## 4. 热更新快，不只是换了打包器

`v5` 切到 `rolldown-vite` 的时候，文档给了很直接的数据：示例工程里热更新平均构建时间从 `2216.58 ms` 降到 `887.56 ms`，约 `2.50` 倍提升（见 `/migration/v5`）。

但更关键的是后面的实现。

在 `plugins/hooks/useLoadEntry/index.ts` 里，HMR 不是简单“有改动就全量重编译”。默认 `sharedChunks: 'auto'` 下，会根据共享 chunk 的导入关系判断：

* 能局部更新就局部更新。
* 只有在“部分 entry 更新会导致共享 chunk 不一致”的情况下，才回退到全量 entry 发射。

再叠加 `plugins/core/lifecycle/watch.ts` 对变更入口和受影响依赖的追踪，开发态的体验就不是“快一次慢一次”，而是稳定地快。

工程上，这比“偶发峰值很低”更重要。

## 5. 语法重写：不是把 Vue 套壳到小程序上

很多人第一次看 `weapp-vite + wevu`，会以为只是“能写 `.vue` 了”。

实际情况是，编译侧和运行时都做了重新设计。

编译侧（`wevu-compiler`）里，`compileVueFile` 会经历 `parse -> template -> script -> style -> config -> finalize` 的完整阶段。模板转换不是字符串替换：

* `v-if / v-else-if / v-else` 在 `tag-structural.ts` 里做结构化转换。
* `v-for` 会解析 alias、作用域和表达式，再映射到小程序循环语义。
* `v-model` 在 `directives/model.ts` 里按不同宿主控件生成不同绑定策略。
* `<script setup>` 里的 `definePageJson / defineComponentJson / defineAppJson` 会在编译期提取、计算和合并，然后把宏语句从运行时代码里剥离（`transform/jsonMacros/*`）。

运行时（`wevu`）则把更新路径明确落在 `diff + setData`：`runtime/diff.ts` 负责快照转 plain object、差量比较和 patch 生成，目标非常明确，就是尽量降低 `setData` 体积和频率。

这也解释了为什么 Wevu 没把 `@vue/runtime-core` 的 `createRenderer` 当主线路。因为小程序的核心更新语义不是“节点操作”，而是“数据快照下发”。这部分可以看单独文章：[/wevu/why-not-runtime-core-create-renderer](/wevu/why-not-runtime-core-create-renderer)。

## 结语

如果把这套东西放在一句话里，我会这样总结：

`weapp-vite` 在做的不是“让小程序看起来像 Vue”，而是“把小程序工程化里最痛的几件事，放到同一条可验证的链路里”。

AI 协作有入口，样式体系有抓手，分包策略有取舍，热更新有稳定收益，语法升级有编译与运行时双支撑。

这才是“重新思考”的价值。不是换了写法，而是把开发、构建、调试、协作几件事重新接成了一个系统。

---

---
url: /blog/release6.md
description: 还记得在 Weapp-vite 4.0 的发布文章里，我写过这样的话：
---

![Weapp-vite 6 顶部海报](/6/bg.jpg)

# Weapp-vite：原生模式之外，多一种 Vue SFC 选择

大家好呀，我是你们的老朋友，开源爱好者 [icebreaker](https://github.com/sonofmagic)！又到了新的一年了，祝大家财源滚滚，早日不用上班实现财务自由！

今天主要来分享一下我开源项目 [Weapp-vite](https://github.com/weapp-vite/weapp-vite) 的开发里程碑，核心就是来给大家秀一把。

## 前言

我还记得在过去 Weapp-vite@4.0 的发布文章里，写过这样的话：

> Weapp-vite **不适用场景**：需要使用 `Vue`/`React` 等前端框架的写法，来取代小程序原生写法。

但社区的声音让我重新想了想这个定位。说实话，原生小程序的语法写多了确实烦，尤其是你要是平时写 Vue 3 写习惯了，回头再 `this.setData`、手动绑事件、管生命周期，就会觉得特别笨重。Vue 的 SFC 设计确实好用，这个没什么好争的。

而且即使到了这个 AI 时代，小程序的验收工具也比较笨重，因为小程序缺少 playwright-cli, agent-browser, chrome-devtools-mcp 这类的验收工具, 还原度远远不及 Web。

另外还有一点就是当时我正好在团队里面做[《Vue 编译本质论》](https://deep-in-vue.icebreaker.top/)的技术分享

所以我就在想**能不能把 Weapp-vite 改造成一个既保留原生模式优势，又提供 Vue 开发体验的工具？**

于是，Weapp-vite@6 来了——**在原生模式之外，多一种 Vue 选择**。

## 背景故事：从零运行时到 Vue SFC 支持

### 最初的定位

Weapp-vite 一开始就是奔着**零运行时**去的——一个纯粹的原生小程序构建工具。你用原生写法写代码，它给你提供现代化的开发体验，打出来的包尽量小、跑起来尽量快。

这个定位确实满足了不少用户，特别是只做微信小程序、对性能有洁癖的那批人，还有用 Skyline 的。

但我后来一直在琢磨：能不能在不动原生模式的前提下，再给一个 Vue 的选项？

### 市面上的选择

让我们看看现有的方案吧：

#### Taro

跨端能力确实强，但运行时代码量不小。分包没规划好的话，主包很容易超。语法上虽然说支持 React/Vue，但写起来总有种"变种"的感觉，踩坑成本不低。

而且说实话 Taro 现在维护节奏慢了不少，issue 堆得挺多的。

我也曾经在 2 年前，在他们的公众号上，看到了招聘启事，于是投了简历，结果人家完全没有鸟我(笑～)。

#### uni-app

上手是挺快的，但 `uni.xxx` 那套 API 和专属 DSL 毕竟是另一套东西。uni-app x 搞的 uts，跟标准 Vue 生态和社区总感觉有点貌合神离。

我很喜欢 uni-app, 当时也很早就让我另外一个项目 weapp-tailwindcss 中兼容了 uni-app x，但是我不喜欢 HBuilderX

#### mpx

滴滴出品，基于 Vue 2.7 + webpack。我不喜欢，技术栈老了，响应式系统跟标准 Vue 也不完全一样。

我的 `Weapp-vite` 方案，你可以理解成 mpx 的下一代：**Vue 3 风格 + Rolldown Vite，只做小程序，但跟原生 API 完全兼容**。

### Weapp-vite 的思路

Weapp-vite@6 想做的事情很简单：**同一个工具，两种模式**。

* **原生模式**：零运行时，包体积和性能都拉满，适合对这些有要求的项目
* **Vue 模式**：完整的 Vue 3 写法，适合 Vue 技术栈的团队

两者可以在同一个项目里混着用。`.vue` 组件能引原生组件，原生组件也能引 `.vue` 组件，按页面按组件自己选就行。

### 运行时 Wevu 的诞生

转折点是 `wevu` 的出现——一个专门给小程序写的 Vue 运行时。

当时本来是叫 `wevue` 的，但是这个名字 `npm` 包已经被注册掉了，所以 `trimEnd` 了一个 `e`

`wevu` 保留了 Vue 3 那些核心 API——`ref`、`computed`、`watch`、`onMounted` 之类的，但底层更新走的是小程序的 `setData`。

更重要的是，**Wevu 从一开始就是配合 Weapp-vite 的 SFC 编译来设计的**，所以编译时能加的糖都尽量加上了，写起来会比较顺手。

### 编译时 + 运行时

`wevu` 运行时搞定之后，Vue SFC 编译支持就是顺水推舟的事了。

## 认识 Wevu：给小程序写的 Vue 3 风格运行时

**Wevu** 专门给小程序设计，核心思路就是：**响应式那套跟 Vue 3 同源，渲染层按小程序的规矩来**。

### 它能干什么

* `ref`、`reactive`、`computed`、`watch`、`watchEffect` 这些响应式 API 都有，用法跟 Vue 3 一样
* `onMounted`、`onUpdated`、`onUnmounted` 等生命周期钩子，自动映射到小程序对应的生命周期
* 快照 diff 优化，`setData` 只传变了的数据路径，不会整坨丢过去
* 内置了 `defineStore`/`storeToRefs`，用法跟 Pinia 差不多
* 跟 Weapp-vite 的 SFC 编译配合使用，响应式和生命周期都是打通的

### Vue 3 和 Wevu 到底哪不一样

响应式 API 和写法基本一致，区别在渲染那层：Wevu 不操作 DOM，而是操作小程序实例，更新走的是"快照 diff + `setData`"。

### 为什么没用 `createRenderer`

`@vue/runtime-core` 的 `createRenderer` 技术上能做，但拿来对小程序有个根本问题：它假设宿主能提供一套比较完整的节点操作接口，而小程序这边核心就一个 `setData(payload)`，两边的抽象对不上。

Wevu 走的是"编译到 WXML + 快照 diff + 最小 setData"，把优化做在更贴近小程序实际情况的地方。

### Weapp-vite + Wevu 怎么配合

* **Weapp-vite** 管编译：把 Vue SFC 拆开、转换、生成小程序四件套
* **Wevu** 管运行时：提供响应式系统和生命周期

两个加一起，你得到的就是：

1. Vue 3 的开发体验（SFC + Composition API）
2. 接近小程序原生的运行性能

Vue SFC 支持是**直接内置在 `weapp-vite` 里的**，不是外挂插件。

## 一处编写，四处生成

你写一个 `.vue` 文件，Weapp-vite 编译完会变成小程序四件套：

```text
MyComponent.vue
    ├─> MyComponent.js    // 脚本逻辑
    ├─> MyComponent.wxml  // 模板结构
    ├─> MyComponent.wxss  // 样式文件
    └─> MyComponent.json  // 组件配置
```

Vue 的 `<script>`、`<template>`、`<style>`、`<json>`(可被 `defineXXXJson` 宏指令取代) 会被拆开，各自转换成小程序能认的格式。整个过程就像是把 Vue 组件"翻译"成了小程序的方言。

## Vue 语法怎么转的

这不是简单地把 Vue 代码塞进小程序，而是做了一层语法映射：

| Vue 写法 | 转换为 |
|:---|:---|
| `v-if` / `v-else-if` / `v-else` | `wx:if` / `wx:elif` / `wx:else` |
| `v-for="item in list"` | wx:for="{{list}}" + wx:key |
| `@click` / `@tap` | `bindtap` / `catchtap` |
| `:class` / `:style` | class="{{...}}" / style="{{...}}" |
| `v-model` | 双向绑定的完整实现（input/checkbox/radio/textarea 等） |
| `<script setup>` | 自动处理响应式和生命周期 |

你按 Vue 的方式写，Weapp-vite 按小程序的方式跑。

## 工具链友好：智能提示 + AI 协作

### 智能提示：直接复用 Vue 官方插件

VS Code 里装了 Vue 官方插件（Vue - Official / Volar）的话，Weapp-vite 的 `.vue` 文件直接就能用上模板智能提示和类型检查，不用再折腾一套新的编辑器插件。

* `v-for` 场景下的 `:key` 等属性补全

![Vue 模板智能提示（v-for + :key）](/6/ic.png)

* `:class` / `:style` 等常用绑定提示
* 组件属性与事件相关补全

![Vue 模板智能提示（原生标签属性补全）](/6/in.png)
![Vue 模板智能提示（组件属性补全）](/6/inc.png)

### AI 协作

如果你准备用 AI 来协作开发，我自己的顺序一直很固定：先把 `skills` 装好，再起 `MCP`，最后按需喂 `llms` 语料。

先装 skills：

```bash
npx skills add sonofmagic/skills
```

常用的几个：`weapp-vite-best-practices`、`docs-and-website-sync`、`weapp-vite-vue-sfc-best-practices`、`wevu-best-practices`。

然后启动 MCP：

```bash
weapp-vite mcp
```

如果你不在仓库目录下执行，再补 `--workspace-root /path/to/weapp-vite`。

最后是 llms 语料入口：

* 页面：[/llms](/llms)
* 文件：`/llms.txt`、`/llms-full.txt`、`/llms-index.json`
* 顺序：`llms.txt -> llms-full.txt -> llms-index.json`

更多细节放在这里：[/guide/ai](/guide/ai)、[/packages/mcp](/packages/mcp)、[/config/shared#weapp-mcp](/config/shared#weapp-mcp)。

## 几个常见用法

### 响应式状态 + 计算属性

```html
<script setup lang="ts">
import { computed, ref } from 'wevu'

const count = ref(0)
const doubled = computed(() => count.value * 2)
</script>

<template>
  <view>
    <text>{{ count }} / {{ doubled }}</text>
    <button @tap="count++">+1</button>
  </view>
</template>
```

### `definePageJson` 宏定义页面配置

```html
<script setup lang="ts">
definePageJson({
  navigationBarTitleText: '首页',
  navigationBarTextStyle: 'white',
})
</script>
```

### 在 `.vue` 里直接用原生组件

```html
<script setup lang="ts">
import NativeMeter from '../../native/native-meter/index'
</script>

<template>
  <NativeMeter label="构建链能力" :value="80" />
</template>
```

### `v-model` 表单双向绑定

```html
<script setup lang="ts">
import { ref } from 'wevu'

const message = ref('')
</script>

<template>
  <input v-model="message" placeholder="输入点什么..." />
  <text>{{ message }}</text>
</template>
```

更多像 `slots`、`props/emits`、`app.vue` 配置以及编译行为说明，已放到原理文档统一说明：[`Weapp-vite@6 原理拆解`](/blog/release6-principles)。

## 适用场景

### 双模式并存才是 Weapp-vite 的杀手锏

Weapp-vite@6 最实用的一点就是"同仓双模式"。性能敏感的页面继续走原生，迭代快、业务重的页面丢到 Vue 模式里。迁移可以一个页面一个页面来，不用一口气重写整个项目。

### 什么时候用 Vue 模式：

* 你平时写 Vue 3，想用同样的写法搞小程序
* 团队本来就是 Vue 技术栈，想复用过来
* 想要热重载、TypeScript 这些现代开发体验
* 希望 Vue 代码后面还能往 Web 项目上搬

### 什么时候用原生模式：

* 对性能有洁癖，一点运行时开销都不想要
* 已经有一大堆原生代码，不想大动
* 团队对小程序原生 API 很熟
* 包体积卡得很死

### 什么时候该选别的框架？

* **Taro**：如果你真的要同时出微信、支付宝、百度、字节好几个平台的小程序，甚至还要编 H5 和 RN，那 Taro 确实是绕不开的。不过说真的，大部分项目真需要跨这么多端吗？

* **uni-app**：如果你想要一个开箱即用的全家桶，而且已经习惯了 DCloud 那套生态（HBuilderX、uniCloud 之类的），uni-app 挺合适。就是它的 DSL 跟标准 Vue 还是有些差异。

* **mpx**：Vue 2.7 + webpack，技术栈偏老了。

## 快速体验

1. **创建项目**：

```sh
pnpm create weapp-vite@latest
# 选择 Wevu 模板或者 Wevu + TDesign 模板
```

2. **开发**：

```sh
pnpm dev
```

3. **享受 Vue 带来的快乐**：

```html
<script setup>
import { ref } from 'wevu'

const message = ref('Hello, weapp-vite@6!')
</script>

<template>
  <view>{{ message }}</view>
</template>
```

## 技术细节

原理和实现细节，如果大家有兴趣的话，我会另外写一篇专门的技术拆解文档。

## 后面打算做什么

接下来主要推两条线：支持更多小程序平台，以及支持 Web 目标。

### Android / iOS 原生方向

现在原生 Android / iOS 这边，很多场景还是得靠微信开发者工具的多端框架来转。这块后面会继续投入，目标是把链路做得更稳、接入成本更低。

## 最后

Weapp-vite@6 这次就是想把选择权留给你：要性能就走原生，要开发体验就走 Vue 模式，混着来也行。背后靠的是 `vue/compiler-sfc` 的解析能力、`wevu` 的运行时设计，以及社区一路给的真实反馈。

感谢每一位提建议、报 bug、提 PR 的同学。

***

如果 Weapp-vite 帮到了你，欢迎给项目点个 [Star](https://github.com/weapp-vite/weapp-vite)！

Happy Coding! 🚀

---

---
url: /guide/web-compat-matrix.md
description: 本文用于说明 Weapp-vite 在 Web 运行时（@weapp-vite/web）下的能力边界。 状态含义如下：
---

# Web 兼容矩阵 experimental {#web-compat-matrix}

本文用于说明 `weapp-vite` 在 Web 运行时（`@weapp-vite/web`）下的能力边界。
状态含义如下：

* `✅`：已实现且有基础测试覆盖。
* `🟡`：可用但有明显限制或降级行为。
* `⛔`：当前未实现，不应依赖。

> \[!WARNING]
> Web 运行时仍处于实验阶段（experimental），用于预览/调试，不替代开发者工具与真机行为。

## 模板语法矩阵

| 能力                                | 状态 | 说明                                                              |
| ----------------------------------- | ---- | ----------------------------------------------------------------- |
| `{{}}` 插值表达式                   | `✅` | 支持文本与属性表达式。                                            |
| `wx:if / wx:elif / wx:else`         | `✅` | 支持条件分支链路。                                                |
| `wx:for / wx:key`                   | `✅` | 支持列表渲染与 key 生成。                                         |
| `<template name>` + `<template is>` | `✅` | 支持模板注册与调用。                                              |
| `<import>` / `<wx-import>`          | `✅` | 支持模板导入，缺失时告警。                                        |
| `<include>` / `<wx-include>`        | `✅` | 支持模板包含，缺失时告警。                                        |
| `<wxs>`（内联与 src）               | `🟡` | 支持基础执行与 `require`，仅允许相对/绝对路径。                   |
| `<slot>`                            | `🟡` | 保留为原生 `slot` 标签；高级插槽语义不保证与小程序完全一致。      |
| 事件前缀 `bind/catch/capture`       | `🟡` | 采用表驱动映射并支持 `catch/capture` 标记；事件别名仍是高频子集。 |
| 复杂模板能力（如 `wx:model` 等）    | `⛔` | 当前未进入 Web 编译主路径。                                       |

## 组件选项矩阵

| 能力                                             | 状态 | 说明                                                             |
| ------------------------------------------------ | ---- | ---------------------------------------------------------------- |
| `properties`（含 `type/value/observer`）         | `✅` | 支持属性反射、类型收敛与 observer。                              |
| `data` / `setData`                               | `✅` | 支持基础状态更新与重渲染。                                       |
| `methods` / `triggerEvent`                       | `✅` | 支持事件触发与组件方法调用。                                     |
| `lifetimes`（`created/attached/ready/detached`） | `✅` | 支持基础生命周期。                                               |
| `pageLifetimes`（`show/hide`）                   | `🟡` | 在页面显示/隐藏时分发到组件；`resize` 依赖浏览器环境。           |
| `behaviors`（递归合并）                          | `✅` | 支持递归合并 `data/properties/methods/lifetimes/pageLifetimes`。 |
| `observerInit`                                   | `✅` | 可配置初始化阶段 observer 触发策略。                             |
| `relations` / `externalClasses` 等               | `⛔` | 当前未在 runtime `ComponentOptions` 中实现。                     |

## `wx` API 矩阵（Web bridge）

| API                                                                                                      | 状态 | 说明                                                                                                    |
| -------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
| `wx.navigateTo`                                                                                          | `✅` | 支持基础页面栈推进。                                                                                    |
| `wx.redirectTo`                                                                                          | `✅` | 支持替换当前页面。                                                                                      |
| `wx.reLaunch`                                                                                            | `✅` | 支持重建路由栈。                                                                                        |
| `wx.switchTab`                                                                                           | `🟡` | 当前行为等价于 `redirectTo`。                                                                           |
| `wx.showTabBar` / `wx.hideTabBar`                                                                        | `🟡` | 当前为 no-op 成功桥接，用于兼容调用链，不改变实际 Web 布局。                                            |
| `wx.loadSubPackage` / `wx.preloadSubpackage`                                                             | `🟡` | 当前提供 no-op 成功桥接，主要用于兼容分包加载调用链，不执行真实下载与预加载流程。                       |
| `wx.navigateBack`                                                                                        | `✅` | 支持 `delta` 回退。                                                                                     |
| `wx.setNavigationBarTitle`                                                                               | `🟡` | 依赖默认导航栏组件存在。                                                                                |
| `wx.setNavigationBarColor`                                                                               | `🟡` | 依赖默认导航栏组件存在。                                                                                |
| `wx.setBackgroundColor` / `wx.setBackgroundTextStyle`                                                    | `🟡` | 提供页面背景与文本样式的近似桥接，基于 DOM 样式设置，不等价小程序原生渲染语义。                         |
| `wx.showNavigationBarLoading` / `hideNavigationBarLoading`                                               | `🟡` | 依赖默认导航栏组件存在。                                                                                |
| `wx.showLoading` / `wx.hideLoading`                                                                      | `🟡` | 提供轻量 DOM loading 层，视觉行为为近似实现。                                                           |
| `wx.nextTick`                                                                                            | `🟡` | 基于微任务队列调度回调，时序近似小程序行为。                                                            |
| `wx.showModal`                                                                                           | `🟡` | 基于浏览器 `confirm/alert`，`confirmText/cancelText` 不生效。                                           |
| `wx.showActionSheet`                                                                                     | `🟡` | 通过浏览器 `prompt` 或预设索引桥接选择结果，交互样式与真机 ActionSheet 不一致。                         |
| `wx.showToast`                                                                                           | `🟡` | 提供轻量 DOM toast，样式与真机不完全一致。                                                              |
| `wx.startPullDownRefresh` / `wx.stopPullDownRefresh`                                                     | `🟡` | Web 侧均作为 no-op 成功桥接，便于兼容下拉刷新调用链。                                                   |
| `wx.hideKeyboard`                                                                                        | `🟡` | 通过 `blur` 当前聚焦输入元素近似桥接收起键盘能力，行为受浏览器焦点模型限制。                            |
| `wx.pageScrollTo`                                                                                        | `🟡` | 支持 `scrollTop/duration` 的基础滚动，`selector` 等高级能力未覆盖。                                     |
| `wx.createCanvasContext`                                                                                 | `🟡` | 基于浏览器 2D Canvas 上下文桥接高频绘制命令，绘图状态与高级 API 未全量覆盖。                            |
| `wx.createVideoContext`                                                                                  | `🟡` | 基于页面 video 元素提供播放控制桥接（`play/pause/seek` 等），不包含原生播放器完整语义。                 |
| `wx.createWorker`                                                                                        | `🟡` | 基于浏览器 Worker 桥接消息收发与错误监听（`postMessage/onMessage/onError`），线程模型与真机不完全一致。 |
| `wx.createSelectorQuery`                                                                                 | `🟡` | 支持 `in/select/selectAll/selectViewport` 与 `boundingClientRect/scrollOffset/fields/node` 高频子集。   |
| `wx.setClipboardData` / `wx.getClipboardData`                                                            | `🟡` | 依赖浏览器剪贴板权限；失败时会回调 `fail`。                                                             |
| `wx.request`                                                                                             | `🟡` | 基于 `fetch` 桥接，支持常见 JSON/text 场景；上传下载与高级拦截能力未覆盖。                              |
| `wx.uploadFile`                                                                                          | `🟡` | 基于 `fetch + FormData` 桥接文件上传，支持基础表单字段；上传任务进度与中断控制语义未覆盖。              |
| `wx.downloadFile`                                                                                        | `🟡` | 基于 `fetch` + `Blob URL` 桥接，返回临时 URL；文件系统语义与真机不一致。                                |
| `wx.openDocument`                                                                                        | `🟡` | 支持 URL 或内存文件桥接到浏览器新窗口预览，文档菜单与内置查看器行为不等价。                             |
| `wx.chooseImage`                                                                                         | `🟡` | 优先使用 `showOpenFilePicker`，降级到文件输入框选择；结果为浏览器临时 URL。                             |
| `wx.chooseMedia`                                                                                         | `🟡` | 基于文件选择器桥接图片/视频选择，结果为浏览器临时 URL，媒体元信息（时长/尺寸）当前为近似占位值。        |
| `wx.chooseVideo`                                                                                         | `🟡` | 基于媒体文件选择桥接视频选择，返回浏览器临时 URL；时长/尺寸字段当前为近似占位值。                       |
| `wx.compressImage`                                                                                       | `🟡` | 优先基于 Canvas 执行近似压缩，失败或能力缺失时回退原图路径；压缩质量与真机语义不完全一致。              |
| `wx.compressVideo`                                                                                       | `🟡` | 当前提供 no-op 兼容桥接（默认返回原视频路径），可通过预设结果注入压缩后的临时路径用于调试流程。         |
| `wx.getImageInfo`                                                                                        | `🟡` | 基于浏览器 `Image` 对象读取图片宽高与类型；EXIF 与方向能力为近似值。                                    |
| `wx.getVideoInfo`                                                                                        | `🟡` | 优先读取运行时预设，降级尝试浏览器 video 元信息；文件大小、帧率、码率等字段当前为近似值。               |
| `wx.chooseMessageFile`                                                                                   | `🟡` | 基于文件选择器桥接消息文件选择，返回浏览器临时文件信息；会话/聊天上下文语义与真机不同。                 |
| `wx.chooseFile`                                                                                          | `🟡` | 基于文件选择器桥接通用文件选择，支持 `extension` 过滤；返回浏览器临时文件信息。                         |
| `wx.previewImage`                                                                                        | `🟡` | 使用浏览器 `window.open` 预览图片，依赖浏览器弹窗策略。                                                 |
| `wx.previewMedia`                                                                                        | `🟡` | 基于浏览器新窗口预览媒体 URL，不提供小程序原生媒体预览器的手势、切换与播放控制能力。                    |
| `wx.openVideoEditor`                                                                                     | `🟡` | 当前提供 API 级兼容桥接（默认返回原视频路径），可通过预设结果注入编辑后路径用于调试流程。               |
| `wx.saveImageToPhotosAlbum`                                                                              | `🟡` | 通过浏览器下载行为近似桥接保存流程，不具备系统相册写入与权限弹窗等真机语义。                            |
| `wx.saveVideoToPhotosAlbum`                                                                              | `🟡` | 通过浏览器下载行为近似桥接保存流程，不具备系统相册写入与权限弹窗等真机语义。                            |
| `wx.saveFile`                                                                                            | `🟡` | 将临时文件路径近似持久化到 Web 内存文件系统并返回 `savedFilePath`，不等价真机文件沙箱语义。             |
| `wx.saveFileToDisk`                                                                                      | `🟡` | 通过浏览器下载行为近似桥接保存文件流程，不具备小程序容器内的系统文件管理语义。                          |
| `wx.login` / `wx.checkSession` / `wx.getAccountInfoSync`                                                 | `🟡` | 提供 Web 环境下的登录态占位桥接与会话校验，不等价真实小程序登录会话。                                   |
| `wx.getUserInfo` / `wx.getUserProfile`                                                                   | `🟡` | 提供用户信息读取与授权确认占位桥接，可通过预设结果注入用户资料，不触发系统级授权弹窗。                  |
| `wx.showShareMenu` / `wx.updateShareMenu`                                                                | `🟡` | 提供 API 级成功回调桥接，不覆盖平台级分享能力差异。                                                     |
| `wx.getExtConfigSync` / `wx.getExtConfig`                                                                | `🟡` | 返回 Web runtime 注入的扩展配置快照（默认空对象）。                                                     |
| `wx.getUpdateManager` / `wx.getLogManager`                                                               | `🟡` | 返回 Web 侧更新/日志桥接对象：更新流程可通过预设状态驱动，日志输出映射到浏览器 console。                |
| `wx.cloud.init` / `wx.cloud.callFunction`                                                                | `🟡` | 提供云能力初始化与云函数调用占位桥接，返回 mock 结果用于流程调试，不连接真实云环境。                    |
| `wx.reportAnalytics`                                                                                     | `🟡` | 在运行时内存中记录事件用于调试，不会真实上报到微信数据分析后台。                                        |
| `wx.navigateToMiniProgram` / `wx.exitMiniProgram`                                                        | `🟡` | 提供 API 级桥接用于流程调试，不执行真实小程序容器跳转/退出。                                            |
| `wx.openCustomerServiceChat`                                                                             | `🟡` | 可选地通过浏览器打开客服链接，企业微信会话能力不等价。                                                  |
| `wx.makePhoneCall`                                                                                       | `🟡` | 通过浏览器 `tel:` 链接桥接拨号流程，受设备与浏览器支持限制。                                            |
| `wx.chooseAddress`                                                                                       | `🟡` | 支持通过运行时预设或 `prompt` 输入桥接收货地址选择，不包含小程序原生地址簿与用户授权弹窗能力。          |
| `wx.chooseLocation`                                                                                      | `🟡` | 支持通过预设值或 `prompt` 输入经纬度完成桥接，不包含地图选点 UI 与 POI 选择能力。                       |
| `wx.openLocation`                                                                                        | `🟡` | 通过地图 URL 跳转近似桥接定位查看能力，不等价微信内置地图页面行为。                                     |
| `wx.requestPayment`                                                                                      | `🟡` | 仅提供成功回调级占位桥接，不涉及真实支付签名与交易流程。                                                |
| `wx.requestSubscribeMessage`                                                                             | `🟡` | 提供订阅消息授权结果占位桥接，可通过预设值控制模板消息确认结果，不触发平台级订阅弹窗。                  |
| `wx.createRewardedVideoAd` / `wx.createInterstitialAd`                                                   | `🟡` | 提供广告对象生命周期桥接（`load/show/onError/onClose`），不触发真实广告网络与平台策略。                 |
| `wx.createVKSession`                                                                                     | `🟡` | 提供 VKSession 生命周期占位桥接（`start/stop/destroy/on/off`），不包含真实 VisionKit 推理能力。         |
| `wx.getNetworkType` / `wx.onNetworkStatusChange` / `wx.offNetworkStatusChange`                           | `🟡` | 基于 `navigator.onLine` 与浏览器网络事件，网络类型为近似值。                                            |
| `wx.scanCode`                                                                                            | `🟡` | 提供基于输入/预设结果的占位扫码桥接，用于流程调试，不等价真实摄像头扫码能力。                           |
| `wx.getLocation`                                                                                         | `🟡` | 基于浏览器 Geolocation API 桥接，坐标与精度字段受浏览器权限策略影响。                                   |
| `wx.getFuzzyLocation`                                                                                    | `🟡` | 优先读取运行时预设并降级到定位结果模糊化桥接（经纬度保留两位小数），精度字段为近似值。                  |
| `wx.vibrateShort`                                                                                        | `🟡` | 通过浏览器 `navigator.vibrate` 触发短振动，实际效果受设备与权限限制。                                   |
| `wx.getBatteryInfo` / `wx.getBatteryInfoSync`                                                            | `🟡` | 优先读取浏览器 Battery API，缺失时回退到缓存近似值。                                                    |
| `wx.getFileSystemManager`                                                                                | `🟡` | 提供基于内存的文件读写桥接（`writeFile/readFile` 及 sync 版本），用于开发调试，不等价真机沙箱文件系统。 |
| `wx.setStorage` / `getStorage` / `removeStorage` / `clearStorage` / `getStorageInfo`                     | `🟡` | 基于内存 + `localStorage` 前缀桥接；与真机容量和隔离策略不完全一致。                                    |
| `wx.setStorageSync` / `getStorageSync` / `removeStorageSync` / `clearStorageSync` / `getStorageInfoSync` | `🟡` | 提供同步桥接，缺失 key 时 `getStorageSync` 返回空字符串。                                               |
| `wx.getSystemInfo` / `wx.getSystemInfoSync` / `wx.getWindowInfo`                                         | `🟡` | 基于浏览器环境推断，字段为近似值。                                                                      |
| `wx.onWindowResize` / `wx.offWindowResize`                                                               | `🟡` | 基于浏览器 `resize` 事件桥接窗口尺寸变化回调，触发时序与真机可能有差异。                                |
| `wx.getDeviceInfo` / `wx.getSystemSetting` / `wx.getAppAuthorizeSetting`                                 | `🟡` | 返回浏览器可推断字段与默认授权状态（多数字段为近似/占位值）。                                           |
| `wx.getSetting` / `wx.authorize` / `wx.openSetting`                                                      | `🟡` | 提供基于运行时内存状态的权限桥接，支持常见 scope 调试，不会触发系统级授权弹窗。                         |
| `wx.openAppAuthorizeSetting`                                                                             | `🟡` | 提供应用级授权设置结果桥接，可通过预设状态注入授权结果，不触发系统级授权设置页。                        |
| `wx.getAppBaseInfo`                                                                                      | `🟡` | 提供浏览器环境下的基础信息近似值（语言、主题、平台等）。                                                |
| `wx.getMenuButtonBoundingClientRect`                                                                     | `🟡` | 返回基于窗口尺寸的启发式胶囊按钮区域，不保证与真机一致。                                                |
| `wx.getLaunchOptionsSync` / `wx.getEnterOptionsSync`                                                     | `🟡` | 返回基于当前 Web runtime 路由推断的启动参数快照。                                                       |
| `wx.canIUse`                                                                                             | `🟡` | 支持 API 级能力探测（`wx.xxx`）；复杂组件/样式规则探测未覆盖。                                          |
| `getCurrentPages` / `getApp`                                                                             | `✅` | 提供基础桥接能力。                                                                                      |
| 其他常见 API（多媒体高级能力等）                                                                         | `⛔` | 尚未内置桥接，需业务层自行兼容。                                                                        |

## 已知限制

1. Web 侧表达式与 WXS 执行依赖动态求值机制，行为与小程序引擎存在差异。
   如需更保守或更严格的行为，可通过 `weapp.web.pluginOptions.runtime.executionMode` 调整为 `safe` 或 `strict`。
2. 事件映射与组件标签映射优先覆盖高频场景，未承诺全量等价。
3. `analyze --platform h5` 目前仅支持 Web 静态配置分析（`weapp.web` 与 `executionMode`），不包含分包体积、源码映射和仪表盘能力。
4. 运行时告警已支持 `runtime.warnings.level` 与 `runtime.warnings.dedupe`，但当前可观测信息仍以控制台输出为主。

## 建议用法

1. 将 Web 运行时作为“开发期预览与调试层”，不要直接等价真机验收。
2. 新增 Web 能力时，同步更新本矩阵，并补齐单测/E2E 用例。
3. 需要查看 Web 侧静态分析时，可执行 `weapp-vite analyze --platform h5 --json`。
4. 若业务依赖 `⛔` 能力，建议在业务侧提供平台分支与降级策略。

---

---
url: /config/web.md
description: Weapp-vite 可选集成浏览器端运行时（@weapp-vite/web），用于 Web 预览/调试。
---

# Web 运行时配置 experimental {#web-config}

`weapp-vite` 可选集成浏览器端运行时（`@weapp-vite/web`），用于 Web 预览/调试。

\[\[toc]]

> \[!TIP]
> Web 端能力边界请配合阅读：[Web 兼容矩阵](/guide/web-compat-matrix)。

> \[!WARNING]
> `weapp.web` 仍处于实验阶段（experimental）。当前建议用于开发期预览与调试，不建议作为生产验收的唯一依据。
> 若需查看 Web 侧配置解析结果，可执行 `weapp-vite analyze --platform h5 --json`（当前仅静态分析，非包体分析）。

## `weapp.web` {#weapp-web}

* **类型**：
  ```ts
  {
    enable?: boolean
    root?: string
    srcDir?: string
    outDir?: string
    pluginOptions?: Partial<Omit<WeappWebPluginOptions, 'srcDir'>>
    vite?: InlineConfig
  }
  ```
* **默认值**：不开启（未配置 `weapp.web` 时不生效）。

### 示例

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

export default defineConfig({
  weapp: {
    web: {
      enable: true,
      root: '.',
      srcDir: 'src',
      outDir: 'dist/web',
      pluginOptions: {
        wxss: {
          designWidth: 750,
        },
        form: {
          preventDefault: true,
        },
        runtime: {
          executionMode: 'safe',
          warnings: {
            level: 'warn',
            dedupe: true,
          },
        },
      },
      vite: {
        server: { host: true },
      },
    },
  },
})
```

字段说明：

* `enable`：默认启用（当 `weapp.web` 存在且 `enable !== false` 时生效）。
* `root`：Web 项目根目录（`index.html` 所在目录），默认项目根目录。
* `srcDir`：小程序源码目录（相对于 `root`），默认与 `weapp.srcRoot` 保持一致。
* `outDir`：Web 构建输出目录（相对 `root`），默认 `dist/web`。
* `pluginOptions`：透传给 `weappWebPlugin` 的额外参数。当前可用字段主要包括：
  * `wxss`：WXSS 转换参数（如 `designWidth`、`rpxVar`）。
  * `form`：Web 端表单行为配置（如 `preventDefault`）。
  * `runtime.executionMode`：运行时执行策略（`compat`/`safe`/`strict`）：
    * `compat`（默认）：保持历史行为。
    * `safe`：表达式与 WXS 错误降级为告警并返回空值。
    * `strict`：表达式与 WXS 错误直接抛出，便于开发期快速定位。
  * `runtime.warnings`：运行时告警策略：
    * `level`：`warn`（默认）/`error`/`off`，分别对应 `console.warn`、`console.error`、关闭告警输出。
    * `dedupe`：默认 `true`，同一告警 key 仅输出一次。
  * `srcDir` 由 `weapp.web.srcDir` 自动注入，此处无需手动传入。
* `vite`：额外合并到 Web 构建中的 Vite 内联配置。

> \[!NOTE]
> Web 运行时用于预览/调试，不替代开发者工具与真机行为。

---

---
url: /CHANGELOG.md
description: Store API 统一从主入口导出，并补充 Wevu 使用文档与案例合集。
---

# website-weapp-vite

## 1.0.4

### Patch Changes

* 🐛 **## unify-wevu-entry** [`488f8c4`](https://github.com/weapp-vite/weapp-vite/commit/488f8c4e62dcbd58a5b6823d97992680d077e4f7) by @sonofmagic
  Store API 统一从主入口导出，并补充 Wevu 使用文档与案例合集。

  ## zh-auto-wevu-page-features

  Weapp-vite 在编译阶段自动根据页面中使用的 Wevu hooks（如 `onPageScroll` / `onShareAppMessage` 等）推断并注入对应 `features.enableOnXxx = true`，降低手动维护 `PageFeatures` 标志位的成本。

  * 同时支持 `.vue` SFC 页面与手写 `.ts/.js` 页面（仅在识别到 Wevu 相关调用时才处理，不影响未使用 Wevu 的页面）。
  * 显式写入的 `features` 不会被覆盖（可用 `false` 显式禁用）。

  ## zh-wevu-component-lifetimes-hooks

  补齐组件 `lifetimes/pageLifetimes` 的 hook 派发能力：

  * Wevu：新增 `onMoved` / `onError` / `onResize`，分别对应 `lifetimes.moved` / `lifetimes.error` / `pageLifetimes.resize`。
  * 文档：补充 `defineComponent` 组件侧 lifetimes/pageLifetimes → Wevu hooks 对照表。

  ## zh-wevu-component-only-pages

  Wevu 页面/组件注册统一走小程序 `Component()`：移除 `definePage` 与 `defineComponent({ type: 'page' })` 写法，页面能力通过 `features` 声明（滚动/分享/收藏等）；同时 Weapp-vite 默认处理 `.vue` 时会生成/合并 `json` 并强制写入 `"component": true`（即使未提供 `<json>`）；同步更新文档与 demo，并删除 `createApp().mount()` 相关文档描述。

## 1.0.4-alpha.1

### Patch Changes

* [`25bb59e`](https://github.com/weapp-vite/weapp-vite/commit/25bb59ef81b5c5e85a54919e874b720a7f4d558b) Thanks [@sonofmagic](https://github.com/sonofmagic)! - Weapp-vite 在编译阶段自动根据页面中使用的 Wevu hooks（如 `onPageScroll` / `onShareAppMessage` 等）推断并注入对应 `features.enableOnXxx = true`，降低手动维护 `PageFeatures` 标志位的成本。
  * 同时支持 `.vue` SFC 页面与手写 `.ts/.js` 页面（仅在识别到 Wevu 相关调用时才处理，不影响未使用 Wevu 的页面）。
  * 显式写入的 `features` 不会被覆盖（可用 `false` 显式禁用）。

* [`7af6104`](https://github.com/weapp-vite/weapp-vite/commit/7af6104c5a4ddec0808f7336766adadae3c3801e) Thanks [@sonofmagic](https://github.com/sonofmagic)! - 补齐组件 `lifetimes/pageLifetimes` 的 hook 派发能力：
  * Wevu：新增 `onMoved` / `onError` / `onResize`，分别对应 `lifetimes.moved` / `lifetimes.error` / `pageLifetimes.resize`。
  * 文档：补充 `defineComponent` 组件侧 lifetimes/pageLifetimes → Wevu hooks 对照表。

## 1.0.4-alpha.0

### Patch Changes

* [`e9545a0`](https://github.com/weapp-vite/weapp-vite/commit/e9545a0120ca4183cb956395a53cea0e1d0f5f51) Thanks [@sonofmagic](https://github.com/sonofmagic)! - Wevu 页面/组件注册统一走小程序 `Component()`：移除 `definePage` 与 `defineComponent({ type: 'page' })` 写法，页面能力通过 `features` 声明（滚动/分享/收藏等）；同时 Weapp-vite 默认处理 `.vue` 时会生成/合并 `json` 并强制写入 `"component": true`（即使未提供 `<json>`）；同步更新文档与 demo，并删除 `createApp().mount()` 相关文档描述。

## 1.0.3

### Patch Changes

* [`f1fd325`](https://github.com/weapp-vite/weapp-vite/commit/f1fd3250cfec6a508535618169de0f136ec5cbc2) Thanks [@sonofmagic](https://github.com/sonofmagic)! - chore(deps): upgrade 升级依赖版本

## 1.0.2

### Patch Changes

* [`0ae2a53`](https://github.com/weapp-vite/weapp-vite/commit/0ae2a53198b8d3ab3e8a9ac18ee125e2017a8f51) Thanks [@sonofmagic](https://github.com/sonofmagic)! - chore: change website url

## 1.0.1

---

---
url: /wevu/api.md
description: Wevu API 文档入口页，按主题聚合 API 参考与使用说明，便于快速定位能力域。
---


---

---
url: /wevu/vue3-vs-wevu.md
description: >-
  Wevu vs Vue 3：核心差异与小程序适配，聚焦 Wevu / vue3-vs-wevu 相关场景，覆盖 Weapp-vite 与 Wevu
  的能力、配置和实践要点。
---

# Wevu vs Vue 3：核心差异与小程序适配

> 深入对比 Wevu 与 Vue 3 的架构差异，以及 Wevu 如何适配微信小程序

## 目录

1. [核心架构对比](#核心架构对比)
2. [小程序适配的关键部分](#小程序适配)
3. [生命周期映射](#生命周期映射)
4. [双向绑定适配](#双向绑定)
5. [渲染层对比](#渲染层对比)

***

## 核心架构对比

### 架构图对比

#### Vue 3 架构

```text
┌─────────────────────────────────────────────────────────────┐
│                      Vue 3 Application                       │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐      ┌──────────────┐      ┌────────────┐ │
│  │  Component  │ ───> │ Reactive Sys │ ───> │ Renderer  │ │
│  │   (Setup)   │      │  (Proxy)     │      │  (VNode)   │ │
│  └─────────────┘      └──────────────┘      └────────────┘ │
│         │                    │                    │         │
│         │                    ▼                    ▼         │
│         │              ┌──────────┐         ┌─────────┐   │
│         │              │ Scheduler│         │ DOM API │   │
│         │              │(nextTick)│         │         │   │
│         │              └──────────┘         └─────────┘   │
│         │                                               │
└─────────────────────────────────────────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │    Virtual DOM Tree     │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │     DOM Diff Patch      │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │     Browser DOM         │
        └─────────────────────────┘
```

#### Wevu 架构

```text
┌─────────────────────────────────────────────────────────────┐
│                       wevu Application                       │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐      ┌──────────────┐      ┌────────────┐ │
│  │ Component/  │ ───> │ Reactive Sys │ ───> │ Diff Algo  │ │
│  │    Page     │      │  (Proxy)     │      │(Snapshots) │ │
│  └─────────────┘      └──────────────┘      └────────────┘ │
│         │                    │                    │         │
│         │                    ▼                    ▼         │
│         │              ┌──────────┐         ┌─────────┐   │
│         │              │ Scheduler│         │ Adapter │   │
│         │              │(nextTick)│         │(setData)│   │
│         │              └──────────┘         └─────────┘   │
│         │                                               │
└─────────────────────────────────────────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │    Data Snapshots       │
        │  (Plain JS Objects)     │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │   Diff Algorithm        │
        │  (Path-based Diff)      │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │  Mini-Program setData   │
        │  { 'a.b.c': value }     │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │   WeChat Native View    │
        └─────────────────────────┘
```

### 关键差异表

| 层级           | Vue 3               | Wevu                | 差异说明    |
| -------------- | ------------------- | ------------------- | ----------- |
| **响应式系统** | Proxy + effect      | Proxy + effect      | 相同        |
| **调度器**     | queueJob + nextTick | queueJob + nextTick | 相同        |
| **数据模型**   | Virtual DOM Tree    | Data Snapshots      | ❌ **不同** |
| **渲染算法**   | Virtual DOM Diff    | Snapshot Diff       | ❌ **不同** |
| **视图更新**   | DOM API (patch)     | setData (小程序)    | ❌ **不同** |
| **生命周期**   | Web 标准生命周期    | 小程序生命周期      | ❌ **不同** |

### 相同的部分

#### 1. 响应式系统（100% 相同）

```typescript
// Vue 3 和 wevu 都是这样实现的

class RefImpl<T> {
  get value(): T {
    trackEffects(this.dep) // 收集依赖
    return this._value
  }

  set value(newValue: T) {
    if (!Object.is(newValue, this._rawValue)) {
      this._value = convertToReactive(newValue)
      triggerEffects(this.dep) // 触发更新
    }
  }
}
```

结论：Wevu 直接复用了 Vue 3 的响应式系统设计。

#### 2. 调度器（99% 相同）

```typescript
// Vue 3 和 wevu 的调度器实现几乎一样

const resolvedPromise = Promise.resolve()
const jobQueue = new Set<Job>()

export function queueJob(job: Job) {
  jobQueue.add(job)
  if (!isFlushing) {
    resolvedPromise.then(flushJobs) // 微任务执行
  }
}
```

**唯一区别**：Vue 3 的 job 主要是执行 Virtual DOM patch，Wevu 的 job 是执行 diff + setData。

### 不同的部分

#### 1. 渲染层（完全不同）

**Vue 3 的渲染流程：**

```typescript
// 文件：packages/vue/runtime-core/src/renderer.ts

function patch(n1, n2) {
  // 虚拟 DOM diff
  if (n1.type !== n2.type) {
    // 替换整个节点
  }
  else {
    // 更新属性、子节点
    patchElement(n1, n2)
  }

  // 最终调用 DOM API
  hostInsert(el, parent, anchor)
  hostSetElementText(el, text)
}
```

**Wevu 的渲染流程：**

```typescript
// 文件：packages/wevu/src/runtime/app.ts

function job() {
  // 1. 收集快照（纯 JS 对象）
  const snapshot = collectSnapshot()

  // 2. Diff 快照（不是 Virtual DOM）
  const diff = diffSnapshots(latestSnapshot, snapshot)

  // 3. 调用小程序 setData
  adapter.setData(diff) // { 'user.name': 'Bob' }
}
```

**关键差异：**

| 特性          | Vue 3            | Wevu             |
| ------------- | ---------------- | ---------------- |
| **数据结构**  | Virtual DOM Tree | Plain JS Objects |
| **Diff 算法** | 树形结构 Diff    | 深度对象 Diff    |
| **输出**      | DOM 操作列表     | setData 路径对象 |
| **更新方式**  | DOM API          | setData          |

#### 2. 视图层 API（完全不同）

**Vue 3 的 DOM 操作：**

```typescript
// Vue 3 直接操作 DOM

hostPatchProp(
  el,
  key,
  value,
  isSVG,
  prevChildren
)

// 最终调用：
el.textContent = text
el.setAttribute(key, value)
el.addEventListener(key, handler)
```

**Wevu 的 setData 操作：**

```typescript
// wevu 通过小程序 setData 更新

adapter.setData({
  'user.name': 'Bob',
  'items[0].done': true
})

// 最终调用小程序 API：
this.setData({
  'user.name': 'Bob',
  'items[0].done': true
})
```

***

## 小程序适配

### 适配层架构

```text
┌─────────────────────────────────────────────────────────────┐
│                    wevu 适配层                               │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  1. 注册层 (register.ts)                               │  │
│  │     ├─ registerApp()        → App()                  │  │
│  │     └─ registerComponent()  → Component()            │  │
│  └──────────────────────────────────────────────────────┘  │
│                          ↓                                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  2. 运行时层 (app.ts)                                  │  │
│  │     ├─ mount()               → 创建 runtime           │  │
│  │     ├─ adapter.setData()      → 桥接到小程序          │  │
│  │     └─ effect + scheduler     → 响应式更新            │  │
│  └──────────────────────────────────────────────────────┘  │
│                          ↓                                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  3. Diff 层 (diff.ts)                                  │  │
│  │     ├─ toPlain()              → 响应式转普通对象       │  │
│  │     ├─ diffSnapshots()        → 计算差异              │  │
│  │     └─ assignNestedDiff()     → 生成 setData 路径    │  │
│  └──────────────────────────────────────────────────────┘  │
│                          ↓                                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  4. 双向绑定层 (bindModel.ts)                          │  │
│  │     ├─ bindModel()            → 创建 model 绑定       │  │
│  │     ├─ defaultParser()        → 解析小程序事件        │  │
│  │     └─ model()                → 生成小程序事件属性    │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                          ↓
        ┌─────────────────────────────────────────────┐
        │    微信小程序原生 API                        │
        │    ├─ App() / Component()                   │
        │    ├─ setData()                             │
        │    ├─ triggerEvent()                        │
        │    └─ data / properties / methods            │
        └─────────────────────────────────────────────┘
```

### 1. 注册层适配 (register.ts)

**核心代码：**

```typescript
// 文件：packages/wevu/src/runtime/register.ts

// 关键：桥接到小程序 Component()（在微信中可用于页面/组件）
export function registerComponent<T extends object, C, M>(
  runtimeApp: RuntimeApp<T, C, M>,
  methods: M,
  watch: WatchMap | undefined,
  setup: DefineComponentOptions<T, C, M>['setup'],
  mpOptions: Record<string, any>,
) {
  const componentOptions: Record<string, any> = {
    ...mpOptions,
  }

  // 拦截 onLoad，挂载 runtime
  const userOnLoad = mpOptions.onLoad
  componentOptions.onLoad = function onLoad(this, ...args) {
    // 关键：在这里创建 wevu runtime
    mountRuntimeInstance(this, runtimeApp, watch, setup)

    if (typeof userOnLoad === 'function') {
      userOnLoad.apply(this, args)
    }
  }

  // 拦截 onUnload，清理 runtime
  const userOnUnload = mpOptions.onUnload
  componentOptions.onUnload = function onUnload(this, ...args) {
    teardownRuntimeInstance(this) // 清理

    if (typeof userOnUnload === 'function') {
      userOnUnload.apply(this, args)
    }
  }

  // 调用小程序原生 API
  Page(pageOptions)
}
```

**适配要点：**

1. **生命周期拦截**：在小程序生命周期中挂载/卸载 runtime
2. **方法桥接**：将 runtime.methods 桥接到小程序实例
3. **保留用户代码**：不覆盖用户定义的生命周期

**对比 Vue 3：**

```typescript
// Vue 3 的组件注册（Web）

const app = createApp(RootComponent)
app.mount('#root') // 直接挂载到 DOM

// 不需要拦截，因为 Web 没有生命周期概念
```

### 2. setData 适配 (app.ts + register.ts)

**核心代码：**

```typescript
// 文件：packages/wevu/src/runtime/register.ts

export function mountRuntimeInstance<T extends object, C, M>(
  target: InternalRuntimeState,
  runtimeApp: RuntimeApp<T, C, M>,
  watchMap: WatchMap | undefined,
  setup?: DefineComponentOptions<T, C, M>['setup'],
): RuntimeInstance<T, C, M> {
  // 关键：创建 adapter，桥接到小程序 setData
  const runtime = runtimeApp.mount({
    setData(payload: Record<string, any>) {
      // target 是小程序实例 (this)
      if (typeof target.setData === 'function') {
        target.setData(payload) // 调用小程序原生 API
      }
    },
  })

  // 挂载到实例上
  target.__wevu = runtime
}
```

**在 job 中使用：**

```typescript
// 文件：packages/wevu/src/runtime/app.ts

function job() {
  const snapshot = collectSnapshot()
  const diff = diffSnapshots(latestSnapshot, snapshot)

  // 关键：调用 adapter.setData
  // 实际上调用的是 target.setData()
  if (typeof currentAdapter.setData === 'function') {
    currentAdapter.setData(diff)
  }
}
```

**适配要点：**

1. **Adapter 模式**：通过 adapter 抽象层适配不同平台
2. **setData 路径**：生成小程序兼容的路径（`'a.b.c'`）
3. **错误处理**：捕获 setData 失败，避免中断

**对比 Vue 3：**

```typescript
// Vue 3 的 DOM 更新（Web）

function patch(n1, n2) {
  // 直接操作 DOM
  hostPatchProp(el, key, value)

  // 不需要 adapter，因为 Web 标准 API
}
```

### 3. Diff 算法适配 (diff.ts)

**核心需求：生成小程序 setData 兼容的路径**

```typescript
// 文件：packages/wevu/src/runtime/diff.ts

export function diffSnapshots(
  prev: Record<string, any>,
  next: Record<string, any>
): Record<string, any> {
  const output: Record<string, any> = {}

  const keys = new Set([...Object.keys(prev), ...Object.keys(next)])

  for (const key of keys) {
    const prevValue = prev[key]
    const nextValue = next[key]

    if (!isDeepEqual(prevValue, nextValue)) {
      // 关键：递归 diff，生成嵌套路径
      assignNestedDiff(prevValue, nextValue, key, output)
    }
  }

  return output
}

function assignNestedDiff(
  prev: any,
  next: any,
  path: string, // 路径：'user' -> 'user.name' -> 'user.name.first'
  output: Record<string, any>
) {
  if (isPlainObject(prev) && isPlainObject(next)) {
    const keys = new Set([...Object.keys(prev), ...Object.keys(next)])

    keys.forEach((key) => {
      if (!Object.prototype.hasOwnProperty.call(next, key)) {
        output[`${path}.${key}`] = null // 删除属性
        return
      }

      // 递归，生成嵌套路径
      assignNestedDiff(
        prev[key],
        next[key],
        `${path}.${key}`, // 路径拼接
        output
      )
    })
  }
  else {
    output[path] = normalizeSetDataValue(next) // 最终路径
  }
}
```

**示例：**

```typescript
// 初始状态
const prev = {
  user: {
    profile: {
      name: 'Alice',
      age: 25
    },
    settings: {
      theme: 'dark'
    }
  },
  items: [1, 2, 3]
}

// 修改后
const next = {
  user: {
    profile: {
      name: 'Bob', // ← 改了
      age: 25
    },
    settings: {
      theme: 'dark'
    }
  },
  items: [1, 2, 3, 4] // ← 加了一个
}

// diff 结果（小程序 setData 格式）
const diff = {
  'user.profile.name': 'Bob',
  'items[3]': 4,
}

// 调用小程序 API
this.setData({
  'user.profile.name': 'Bob',
  'items[3]': 4
})
```

**对比 Vue 3：**

```typescript
// Vue 3 的 Virtual DOM diff

const prevVNode = {
  type: 'div',
  props: { className: 'container' },
  children: [
    { type: 'span', children: 'Hello' }
  ]
}

const nextVNode = {
  type: 'div',
  props: { className: 'wrapper' }, // ← 改了
  children: [
    { type: 'span', children: 'Hello' }
  ]
}

// diff 结果：DOM 操作列表
const operations = [
  { op: 'setAttribute', name: 'className', value: 'wrapper' },
]

// 调用 Web API
el.setAttribute('className', 'wrapper')
```

### 4. 双向绑定适配 (bindModel.ts)

**小程序的双向绑定事件**

```vue
<!-- Web Vue 3 -->
<input v-model="username" />

<!-- 编译为 -->
<input
  :value="username"
  @input="username = $event.target.value"
/>
```

```vue
<!-- 小程序 -->
<input model:value="{{username}}" bind:input="handleInput" />

<!-- 需要手动处理 -->
Page({
  data: { username: '' },

  handleInput(e) {
    this.setData({
      username: e.detail.value  // 小程序的事件格式不同
    })
  }
})
```

**Wevu 的适配方案：**

```typescript
// 文件：packages/wevu/src/runtime/bindModel.ts

// 解析小程序事件
export function defaultParser(event: any) {
  if (event == null) {
    return event
  }

  if (typeof event === 'object') {
    // 关键：从小程序事件中提取值
    if ('detail' in event && event.detail && 'value' in event.detail) {
      return event.detail.value // 大多数小程序组件
    }
    if ('target' in event && event.target && 'value' in event.target) {
      return event.target.value // 某些特殊组件
    }
  }

  return event
}

// 创建 model 绑定
export function createBindModel(
  publicInstance: Record<string, any>,
  state: Record<string, any>,
  computedRefs: Record<string, ComputedRef<any>>,
  computedSetters: Record<string, (value: any) => void>,
) {
  return function bindModel<T = any>(path: string, options?: ModelBindingOptions<T>) {
    const segments = toPathSegments(path)

    const resolveValue = () => getFromPath(publicInstance, segments)
    const assignValue = (value: T) => {
      setByPath(state, computedRefs, computedSetters, segments, value)
    }

    return {
      value: resolveValue,
      update: assignValue,

      // 生成小程序事件绑定
      model(modelOptions?: ModelBindingOptions<T>) {
        const handlerKey = `on${capitalize(event)}`
        return {
          [valueProp]: formatter(resolveValue()), // 绑定值
          [handlerKey]: (event: any) => { // 绑定事件
            const parsed = parser(event) // 解析事件
            assignValue(parsed) // 更新值
          }
        }
      }
    }
  }
}
```

**使用示例：**

```typescript
// 组件 setup
import { bindModel, ref } from 'wevu'

export default {
  setup() {
    const username = ref('')

    // 创建 model 绑定
    const usernameModel = bindModel(this, 'username')

    // 生成小程序事件绑定
    const inputBinding = usernameModel.model({
      event: 'input',
      valueProp: 'value'
    })
    // → { value: 'Bob', onInput: fn }

    return {
      username,
      inputBinding
    }
  }
}
```

```vue
<!-- 模板中使用 -->
<input model:value="{{username}}" bind:input="handleInput" />
```

***

## 生命周期映射

### Vue 3 vs 小程序生命周期

```typescript
// 文件：packages/wevu/src/runtime/hooks.ts

// Vue 3 生命周期 → 小程序生命周期映射

export function onMounted(handler: () => void) {
  if (!__currentInstance) {
    throw new Error('onMounted() must be called synchronously inside setup()')
  }
  // 映射到小程序 onReady
  pushHook(__currentInstance, 'onReady', handler)
}

export function onUnmounted(handler: () => void) {
  if (!__currentInstance) {
    throw new Error('onUnmounted() must be called synchronously inside setup()')
  }
  // 映射到小程序 onUnload (Page) 或 detached (Component)
  pushHook(__currentInstance, 'onUnload', handler)
}

export function onActivated(handler: () => void) {
  if (!__currentInstance) {
    throw new Error('onActivated() must be called synchronously inside setup()')
  }
  // 映射到小程序 onShow
  pushHook(__currentInstance, 'onShow', handler)
}

export function onDeactivated(handler: () => void) {
  if (!__currentInstance) {
    throw new Error('onDeactivated() must be called synchronously inside setup()')
  }
  // 映射到小程序 onHide
  pushHook(__currentInstance, 'onHide', handler)
}
```

### 生命周期对比表

| Vue 3             | Page       | Component              | 说明                           |
| ----------------- | ---------- | ---------------------- | ------------------------------ |
| `onBeforeMount`   | -          | -                      | 立即执行（小程序无挂载前钩子） |
| `onMounted`       | `onReady`  | `ready`                | 页面/组件就绪                  |
| `onBeforeUpdate`  | -          | -                      | setData 前立即执行             |
| `onUpdated`       | -          | -                      | setData 后执行（自定义）       |
| `onBeforeUnmount` | -          | -                      | 立即执行（小程序无卸载前钩子） |
| `onUnmounted`     | `onUnload` | `detached`             | 页面卸载/组件移除              |
| `onActivated`     | `onShow`   | `show` (pageLifetimes) | 页面/组件显示                  |
| `onDeactivated`   | `onHide`   | `hide` (pageLifetimes) | 页面/组件隐藏                  |
| `onErrorCaptured` | `onError`  | `error`                | 错误捕获                       |

***

## 双向绑定

### Web Vue 3 的 v-model

```vue
<script setup lang="ts">
import { ref } from 'wevu'

const username = ref('')
const message = ref('')
const selected = ref('a')
</script>

<template>
  <input v-model="username">
  <textarea v-model="message" />
  <select v-model="selected">
    <option value="a">
      A
    </option>
    <option value="b">
      B
    </option>
  </select>
</template>
```

**编译后：**

```vue
<!-- 简化版 -->
<input
  :value="username"
  @input="username = $event.target.value"
/>

<textarea
  :value="message"
  @input="message = $event.target.value"
></textarea>

<select
  :value="selected"
  @change="selected = $event.target.value"
>
  <option value="a">A</option>
  <option value="b">B</option>
</select>
```

### 小程序的 model

```vue
<!-- 小程序原生写法 -->
<input model:value="{{username}}" bind:input="handleInput" />

<textarea model:value="{{message}}" bind:input="handleInput"></textarea>

<picker model:value="{{selected}}" bind:change="handleChange">
  <view>A</view>
  <view>B</view>
</picker>
```

```typescript
Page({
  data: {
    username: '',
    message: '',
    selected: 'a'
  },

  handleInput(e) {
    this.setData({
      username: e.detail.value
    })
  },

  handleChange(e) {
    this.setData({
      selected: e.detail.value
    })
  }
})
```

### Wevu 的 bindModel

```typescript
// 文件：packages/wevu/src/runtime/bindModel.ts

// 创建 model 绑定
const model = bindModel(publicInstance, 'form.username')

// 生成小程序属性
const inputProps = model.model({
  event: 'input',
  valueProp: 'value'
})

// 结果：
// {
//   value: 'Bob',
//   onInput: (e) => {
//     const value = defaultParser(e)  // e.detail.value
//     setByPath(state, ['form', 'username'], value)
//   }
// }
```

**使用示例：**

```vue
<script>
import { ref } from 'wevu'
import { bindModel } from 'wevu/runtime'

export default {
  setup() {
    const username = ref('')
    const message = ref('')

    return {
      username,
      message
    }
  },

  // bindModel 会自动生成这些方法
  methods: {
    handleUsernameInput(e) {
      // 自动更新 username
    },

    handleMessageInput(e) {
      // 自动更新 message
    }
  }
}
</script>

<template>
  <input model:value="{{username}}" bind:input="handleUsernameInput">
  <textarea model:value="{{message}}" bind:input="handleMessageInput" />
</template>
```

***

## 渲染层对比

### Vue 3 的渲染流程

```text
用户代码: state.count++
   ↓
Reactive System: 触发依赖
   ↓
Scheduler: queueJob(patch)
   ↓
微任务: 执行 patch
   ↓
Virtual DOM Diff:
  - 对比新旧 VNode 树
  - 生成最小操作列表
  [
    { type: 'PATCH', prop: 'textContent', value: '1' }
  ]
   ↓
DOM 操作:
  - el.textContent = '1'
   ↓
浏览器渲染引擎更新 DOM
```

### Wevu 的渲染流程

```text
用户代码: state.count++
   ↓
Reactive System: 触发依赖
   ↓
Scheduler: queueJob(job)
   ↓
微任务: 执行 job
   ↓
收集快照:
  {
    count: 1,
    user: { name: 'Alice' }
  }
   ↓
Diff 算法:
  - 深度对比新旧快照
  - 生成 setData 路径
  {
    'count': 1
  }
   ↓
小程序 setData:
  this.setData({ count: 1 })
   ↓
小程序原生渲染引擎更新视图
```

***

## 总结

### 核心差异

| 维度           | Vue 3               | Wevu                | 是否相同 |
| -------------- | ------------------- | ------------------- | -------- |
| **响应式系统** | Proxy + effect      | Proxy + effect      | 相同     |
| **调度器**     | queueJob + nextTick | queueJob + nextTick | 基本相同 |
| **数据模型**   | Virtual DOM         | Data Snapshots      | ❌ 不同  |
| **Diff 算法**  | 树形 Diff           | 深度对象 Diff       | ❌ 不同  |
| **渲染 API**   | DOM API             | setData             | ❌ 不同  |
| **生命周期**   | Web 标准            | 小程序标准          | ❌ 不同  |
| **双向绑定**   | v-model             | bindModel           | ❌ 不同  |

### 小程序适配的关键

1. **注册层 (register.ts)**：拦截小程序生命周期，挂载 runtime
2. **Adapter (app.ts)**：桥接到小程序 setData API
3. **Diff 算法 (diff.ts)**：生成小程序兼容的 setData 路径
4. **双向绑定 (bindModel.ts)**：解析小程序事件，适配 v-model

### 为什么 Wevu 更轻量？

```text
Vue 3 核心代码量：
├── reactivity/      ~5,000 行  wevu 复用
├── runtime-core/   ~10,000 行  ❌ wevu 不需要（Virtual DOM）
├── runtime-dom/    ~5,000 行  ❌ wevu 不需要（DOM 操作）
├── compiler-core/  ~15,000 行  ❌ wevu 不需要（模板编译）
└── compiler-dom/   ~5,000 行  ❌ wevu 不需要（DOM 编译）
Total: ~40,000 行

wevu 核心代码量：
├── reactivity/     ~5,000 行  与 Vue 3 相同
├── runtime/        ~3,000 行  ⚡ 精简版（无 Virtual DOM）
├── scheduler/      ~100 行    与 Vue 3 相同
└── diff/           ~500 行   ⚡ 小程序专用
Total: ~8,600 行

节省：~31,400 行（78%）
```

### 适配策略

| 需求           | Vue 3       | Wevu        | 适配方式                 |
| -------------- | ----------- | ----------- | ------------------------ |
| **数据响应式** | Proxy       | Proxy       | 直接复用                 |
| **批量更新**   | nextTick    | nextTick    | 直接复用                 |
| **视图更新**   | DOM API     | setData     | Adapter 桥接             |
| **事件处理**   | DOM Events  | Mini Events | Parser 解析              |
| **生命周期**   | Web Hooks   | MP Hooks    | 映射转换                 |
| **模板编译**   | VNode → DOM | Vue → WXML  | 编译器处理（Weapp-vite） |

***

## 参考源码

* **Wevu 响应式**: `packages/wevu/src/reactivity/`
* **Wevu 调度器**: `packages/wevu/src/scheduler.ts`
* **Wevu 运行时**: `packages/wevu/src/runtime/app.ts`
* **小程序注册**: `packages/wevu/src/runtime/register.ts`
* **Diff 算法**: `packages/wevu/src/runtime/diff.ts`
* **双向绑定**: `packages/wevu/src/runtime/bindModel.ts`

## 相关阅读

* [Wevu 工作原理](https://github.com/weapp-vite/weapp-vite/blob/main/packages/wevu/ARCHITECTURE.md)
* [Vue 3 兼容性文档](./vue3-compat)
* [小程序 setData 优化](https://developers.weixin.qq.com/miniprogram/dev/framework/performance/tips.html)

---

---
url: /wevu/when-setdata-triggers.md
description: 从触发时机、调度批处理、差量下发与回退策略解释 Wevu 里的 setData 机制，理解它为何在小程序场景下更高效。
---

# Wevu 中的 setData 什么时候触发？

很多同学会把“响应式值变了”直接等同于“立刻调用 `setData`”。
在 Wevu 里，这两件事是分开的：**状态变化先进入调度，再按策略决定是否、何时、以及用多大 payload 调 `setData`。**

这也是 Wevu 在小程序里能保持较好性能的关键。

## 一句话结论

`setData` 触发的前提不是“有赋值”，而是：

1. 运行时仍处于已挂载状态；
2. 本轮调度最终产出了非空更新 payload；
3. 适配器存在可用的 `setData` 方法。

换句话说，赋值只是“候选更新”，不是“必然下发”。

## 触发时机分三类

### 1. 首次挂载时会触发一次初始化更新

runtime 挂载后，Wevu 会主动执行一次 `job()`，把首帧状态推到视图层。
这一步是为了确保初始 `data/setup/computed` 的可视数据完整进入模板。

### 2. 响应式依赖变化后，在微任务批量触发

当你修改了被跟踪的状态（含 `state`、`props/attrs`、`setup` 返回的 `ref/reactive` 等），会先触发 effect 的 scheduler。
scheduler 不会立即 `setData`，而是通过队列合并到同一轮微任务里统一处理。

这意味着同一个同步调用栈里的多次写入，通常只会换来一次更新 flush。

### 3. patch 模式下，按变更路径触发增量更新

当策略是 `patch` 时，Wevu 会记录变更路径，优先走增量 payload。
如果命中回退条件（例如路径过多、payload 过大、需要全量快照），才切回 `diff` 全量快照对比。

这个设计保证了“平时快、异常情况稳”。

## 哪些情况不会触发 setData

下面这些场景常见但不会下发：

1. 值没有真实变化（例如 `Object.is` 结果相等）；
2. 本轮 diff/patch 结果为空（没有可见变化）；
3. 实例已经卸载（`isMounted() === false`）；
4. 字段被 `pick/omit` 等配置过滤后，不在下发范围；
5. 不可序列化值被规范化后没有产生有效输出。

所以看到“代码执行了但没 setData”不一定是 bug，很多时候是有意的性能保护。

## 为什么这套机制在小程序里更高效

### 1. 微任务批处理，减少调用频率

频繁 `setData` 的代价很高，Wevu 默认把同 tick 改动合并后再下发，显著降低桥接次数。

### 2. 差量 payload，减少传输体积

Wevu 不是盲目整包下发，而是优先只发变化路径。
在大对象/大列表场景下，这一点通常比“每次全量推送”更省。

### 3. 有阈值回退，不把极端场景做成性能陷阱

当 patch 的性价比变差时，自动回退到 diff。
这避免了“为了增量而增量”导致的长尾性能问题。

### 4. 可配置调试，便于观察真实开销

`setData` 支持 debug 信息回调与采样，可以看到当前是 patch 还是 diff、为何回退、payload 键数与估算体积。
这让性能调优从“猜”变成“看数据”。

## 常见误解

### 误解 1：响应式等于即时 setData

更准确的说法是：响应式变化会“触发调度资格”，真正下发由 flush 阶段决定。

### 误解 2：增量模式一定比 diff 快

不一定。
Wevu 的策略是“优先 patch，但允许及时回退”，目标是总体吞吐稳定，而不是追求单一策略。

### 误解 3：调用次数少就一定更快

还要看 payload 大小、序列化成本、模板复杂度。
Wevu 的优化是“调用频率 + payload 体积 + 回退策略”一起做。

## 实战建议

1. 高频交互优先保证状态结构稳定，减少无意义字段波动。
2. 大列表场景关注“实际 payload 键数和体积”，不要只看逻辑层赋值次数。
3. 需要时开启 `setData.debug`，先看回退原因再调参数（如 `maxPatchKeys`、`maxPayloadBytes`）。

## 小结

Wevu 的核心不是“让 `setData` 更频繁”，而是“让 `setData` 更克制、更小、更可控”。
这正是它在小程序场景下保持高性能的主要原因之一。

---

---
url: /wevu.md
description: >-
  Wevu 是一个面向小程序（以微信小程序为主）的轻量运行时。可以把它看作“把 Vue 3 的响应式心智模型带到小程序里”，但不引入 Virtual
  DOM，而是用快照 diff 来尽量减少 setData 的更新量。
---

# Wevu 概览

`wevu` 是一个面向小程序（以微信小程序为主）的轻量运行时。可以把它看作“把 Vue 3 的响应式心智模型带到小程序里”，但不引入 Virtual DOM，而是用快照 diff 来尽量减少 `setData` 的更新量。

:::warning 安装方式
`wevu` 建议始终安装在 `devDependencies` 中：

```sh
pnpm add -D wevu
```

不要放到 `dependencies`。在 Weapp-vite 项目里，这样更符合其“构建期依赖内联、运行时依赖单独落位”的产物策略。
:::

它主要提供：

* Vue 3 风格的响应式（`ref` / `reactive` / `computed` / `watch`）
* 基于快照 diff 的最小化 `setData` 更新
* 类 Pinia 的 Store（状态管理）

Wevu 不改变小程序“数据驱动 + 模板渲染”的基本模型：你仍然写 WXML/WXSS（或配合 Weapp-vite 用 Vue SFC 编写模板/样式/配置），但业务逻辑可以用熟悉的 Composition API 组织起来。

## Wevu 在整套体系里的位置

如果你同时使用 Weapp-vite 的 Vue SFC：

* **Weapp-vite（编译期）**：把 `.vue` 编译成 WXML/WXSS/JS/JSON，并做模板语法转换。
* **Wevu（运行期）**：负责响应式、生命周期 hooks、快照 diff 与最小化 `setData`。

因此遇到问题时可以快速分层定位：

* “模板/指令/usingComponents/v-model 怎么编译？” → 先看 `/wevu/vue-sfc`
* “状态为什么不更新 / hooks 为什么不触发？” → 先看 `/wevu/runtime` 与 `/wevu/compatibility`

## 诞生的小故事

这段背景不影响使用，你可以先跳过：

* 最初想叫 `wevue`（weapp + vue），但 npm 已被占用，于是缩写成了 `wevu`。
* 在为 `weapp-vite` 补齐 Vue SFC 支持时，调研过社区方案（如 `vue-mini`），但编译器与运行时都需要大改，最后选择自己实现以更贴合小程序。
* 借鉴 Vue 3 的响应式设计思路，并考虑多小程序平台适配，逐步形成现在的 Wevu。

## 你会用到的能力

* **响应式与调度**：与 Vue 3 相同心智的 `ref` / `reactive` / `computed` / `watch` / `watchEffect`，更新通过微任务批量调度（`nextTick`）。
* **页面/组件注册**：`defineComponent()` 统一通过小程序 `Component()` 注册；`createApp()` 可在存在全局 `App()` 时自动注册应用；`createWevuComponent()` 供 Weapp-vite 编译产物调用。
* **最小化 setData**：运行时把 state + computed 转为 plain snapshot，diff 后只把变化路径传给 `setData`。
* **双向绑定辅助**：`bindModel(path)` 生成适配小程序事件的数据/事件绑定对象。
* **Store（状态管理）**：`defineStore` / `storeToRefs` / `createStore`（可选插件入口）。

:::tip 导入约定
运行时 API 都从 `wevu` 主入口导入。`wevu/compiler` 仅供 Weapp-vite 等编译侧工具使用（非稳定用户 API）。
:::

## 其他子路径导出

除了 `wevu` 主入口外，当前还提供几组按能力拆分的子路径导出：

* [wevu/api](/wevu/api-package)：透传 `@wevu/api`，用于统一多端小程序 API 调用
* [wevu/fetch](/wevu/fetch)：基于 `wpi.request` 的 Fetch 风格接口
* [wevu/router](/wevu/router)：更接近 Vue Router 心智的路由入口
* [wevu/jsx-runtime](/wevu/jsx-runtime)：给 TSX / JSX 类型系统使用的入口

## 编译侧桥接（wevu/compiler）

`wevu/compiler` 用来承载 Wevu 与编译工具之间的共享常量，避免在多个项目里重复写字符串：

* `WE_VU_MODULE_ID`：运行时入口模块名（`wevu`）。
* `WE_VU_RUNTIME_APIS`：运行时 API 名称集合（如 `createApp` / `defineComponent` / `createWevuComponent`）。
* `WE_VU_PAGE_HOOK_TO_FEATURE`：页面 hook 与 features 的映射表。

这些导出面向编译工具（例如 Weapp-vite），应用代码不要依赖它们作为稳定 API。

## 推荐学习顺序（按“最短上手 → 深入理解”）

1. [快速上手](/wevu/quick-start)：先跑通一个页面/组件（含 store）
2. [运行时与生命周期](/wevu/runtime)：理解 `setup(props, ctx)`、生命周期 hooks、`bindModel`、watch 策略
3. [defineComponent（组件）](/wevu/component)：掌握组件字段透传、`properties/props`、`emit/expose` 等细节
4. [Store](/wevu/store)：落地状态管理（订阅、补丁、插件）
5. [兼容性与注意事项](/wevu/compatibility)：了解限制与边界（尤其是 provide/inject、页面事件按需派发）

接下来可以按顺序阅读：

* [快速上手](/wevu/quick-start)
* [运行时与生命周期](/wevu/runtime)
* [defineComponent（组件）](/wevu/component)
* [Store](/wevu/store)
* [API 参考总览](/wevu/api-reference/)
* [wevu/api](/wevu/api-package)
* [wevu/fetch](/wevu/fetch)
* [wevu/router](/wevu/router)
* [wevu/jsx-runtime](/wevu/jsx-runtime)
* [兼容性与注意事项](/wevu/compatibility)
* [Vue 3 兼容性说明（完整）](/wevu/vue3-compat)
* [Wevu vs Vue 3（核心差异）](/wevu/vue3-vs-wevu)

## 扩展阅读

* [为什么没有使用 @vue/runtime-core 的 createRenderer 来实现](/wevu/why-not-runtime-core-create-renderer)
* [Wevu 中的 setData 什么时候触发？](/wevu/when-setdata-triggers)

---

---
url: /wevu/vue3-compat.md
description: Wevu 是一个面向小程序（以微信小程序为主）的 Vue 3 风格运行时：尽量提供熟悉的 Vue 3 API 形态，同时针对小程序运行环境进行适配与约束。
---

# Wevu 的 Vue 3 兼容性说明

`wevu` 是一个面向小程序（以微信小程序为主）的 Vue 3 风格运行时：尽量提供熟悉的 Vue 3 API 形态，同时针对小程序运行环境进行适配与约束。

本文用于帮助你快速判断：

* 哪些 API 可以像 Vue 3 一样直接使用
* 哪些 API 在小程序中存在差异或仅部分兼容
* 哪些 Vue 3 能力在小程序中不适用

## Vue 3 兼容性目标

`wevu` 的核心目标是降低 Vue 开发者进入小程序的心智成本：让你可以继续用 Composition API 组织业务逻辑，并通过快照 diff 最小化 `setData` 更新。

需要注意：小程序不是浏览器环境，没有 DOM / Virtual DOM；事件系统与生命周期也与 Web 存在天然差异，因此 `wevu` 不可能做到“100% 无差别兼容 Vue 3”。

## 完全兼容的 API

以下 API 与 Vue 3 的行为一致（或在 `wevu` 中保持同等语义），可以直接按 Vue 3 的习惯使用。

### 响应式（Reactivity）

* `reactive()`：创建响应式对象
* `ref()`：创建 ref
* `computed()`：创建计算属性
* `watch()`：监听响应式源
* `watchEffect()`：自动追踪依赖的副作用
* `toRefs()`：把响应式对象转换为 refs
* `toRef()`：为指定属性创建 ref
* `toRaw()`：获取原始对象
* `isRef()`：判断是否为 ref
* `isReactive()`：判断是否为 reactive
* `readonly()`：创建只读包装
* `markRaw()`：标记对象跳过响应式转换
* `isRaw()`：判断对象是否被标记为 raw

### 浅层响应式（Shallow Reactivity）

* `shallowReactive()`：创建浅层响应式对象
* `shallowRef()`：创建浅层 ref
* `isShallowReactive()`：判断是否为 shallowReactive
* `isShallowRef()`：判断是否为 shallowRef
* `triggerRef()`：手动触发 ref 更新

### 生命周期钩子（Lifecycle Hooks）

以下钩子在 `wevu` 中提供与 Vue 3 对齐的调用方式（但其触发时机映射到小程序生命周期，具体差异见后文）：

* `onMounted()`：组件/页面已就绪
* `onUpdated()`：更新后（在 `setData` 后触发）
* `onUnmounted()`：组件/页面卸载
* `onBeforeMount()`：挂载前（在小程序里会立即执行，见后文）
* `onBeforeUpdate()`：更新前（在 `setData` 前触发）
* `onBeforeUnmount()`：卸载前（在小程序里会立即执行，见后文）
* `onActivated()`：组件激活（映射 `onShow`）
* `onDeactivated()`：组件失活（映射 `onHide`）
* `onErrorCaptured()`：错误捕获

### 组件与调度（Component API）

* `defineComponent()`：定义组件/页面（底层通过小程序 `Component()` 注册）
* `createApp()`：创建应用实例
* `getCurrentInstance()`：获取当前实例
* `nextTick()`：在下一次更新后执行回调

### 依赖注入（Dependency Injection）

* `provide()`：提供依赖
* `inject()`：注入依赖
* `provideGlobal()` / `injectGlobal()`：全局 provide/inject（已弃用，仅用于兼容/过渡；当前版本仍保留导出）

### Store（Pinia 风格）

`wevu` 内置了 Pinia 风格 Store，并且可以做到“无需全局注册，直接使用”：

* `defineStore()`：定义 Store（Setup/Options 两种模式）
* `storeToRefs()`：从 store 提取 refs
* `createStore()`：可选的 store manager（可做插件入口）
* `$patch`：批量更新 state
* `$reset`：重置 state（仅 Options Store）
* `$subscribe`：订阅 state 变更
* `$onAction`：订阅 action 调用

**关键差异：不需要全局注册**

```ts
// ❌ Pinia：需要全局注册
import { createPinia } from 'pinia'

// wevu：直接使用即可
import { defineStore } from 'wevu'

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  return { count }
})

const pinia = createPinia()
app.use(pinia) // Pinia 必须先注册
```

更多 Store 细节见：[Store 文档](/wevu/store)。

## 部分兼容 / 不同 API

### setup() 上下文（Setup Context）

`setup()` 会收到增强后的 context（在 Vue 3 的 `emit/expose/attrs` 基础上，补充了小程序运行时相关字段）：

```ts
defineComponent({
  setup(props, { emit, expose, attrs }) {
    // Vue 3 风格：props 作为第一个参数（当组件定义了 properties 时）
    // 额外的 context 字段：
    // - props: 组件 properties（来自小程序）
    // - emit: 通过小程序 triggerEvent(eventName, detail?, options?) 派发事件
    // - expose: 暴露公共方法（必定存在）
    // - attrs: attrs（必定存在；小程序场景为空对象）
    // - runtime: wevu 运行时实例
    // - state: 响应式状态
    // - proxy: 公开实例代理
    // - bindModel: 双向绑定辅助方法
    // - watch: watch 辅助方法
    // - instance: 小程序内部实例
  },
})
```

### emit 的差异（triggerEvent 语义）

`emit` 是对小程序 `triggerEvent` 的薄封装：

* `emit(eventName, detail?, options?)`
* `options.bubbles`（默认 `false`）：事件是否冒泡
* `options.composed`（默认 `false`）：事件是否可以穿越组件边界
* `options.capturePhase`（默认 `false`）：事件是否拥有捕获阶段

与 Vue 3 不同：小程序事件只有一个 `detail` 载荷，不支持 `emit(event, ...args)` 的多参数透传。

### 生命周期映射差异

小程序生命周期与 Web 有差异，`wevu` 会做映射：

* `onMounted()` 映射到 `onReady`
* `onUnmounted()` 映射到页面 `onUnload` / 组件 `detached`
* `onActivated()` 映射到 `onShow`
* `onDeactivated()` 映射到 `onHide`
* `onBeforeMount()` / `onBeforeUnmount()` 在小程序中会在 `setup()` 同步阶段立即执行，用于模拟语义

## ❌ 小程序不适用的 Vue 3 API

以下 API 依赖 DOM / Virtual DOM / 浏览器环境，在小程序中不适用：

* `h()` / `createElement()`：小程序没有 Virtual DOM
* `Transition` / `KeepAlive` / `Teleport`：Web 内置组件语义
* `onServerPrefetch()`：无 SSR
* `onRenderTracked()` / `onRenderTriggered()`：无渲染追踪

## 使用示例

### 基础组件

```ts
import { computed, defineComponent, onMounted, ref } from 'wevu'

defineComponent({
  data: () => ({ count: 0 }),

  setup(props, { emit }) {
    const count = ref(0)
    const doubled = computed(() => count.value * 2)

    onMounted(() => {
      console.log('组件已挂载')
    })

    function increment() {
      count.value++
      emit('update', count.value)
    }

    return { count, doubled, increment }
  },
})
```

### 使用 Props

```ts
defineComponent({
  properties: {
    title: String,
    count: Number,
  },

  setup(props) {
    console.log('title:', props.title)
    console.log('count:', props.count)
    return {}
  },
})
```

### Watch 与 WatchEffect

```ts
import { ref, watch, watchEffect } from 'wevu'

defineComponent({
  setup() {
    const count = ref(0)

    watchEffect(() => {
      console.log('Count changed:', count.value)
    })

    watch(count, (newValue, oldValue) => {
      console.log(`Count: ${oldValue} -> ${newValue}`)
    })

    // watch/watchEffect 返回可调用的 stop handle，同时支持 pause / resume
    const { pause, resume, stop } = watch(count, () => {
      console.log('count changed')
    })
    pause()
    resume()
    stop()

    return { count }
  },
})
```

### toRefs：解构同时保持响应式

```ts
import { reactive, toRefs } from 'wevu'

defineComponent({
  setup() {
    const state = reactive({
      count: 0,
      name: 'wevu',
    })

    const { count, name } = toRefs(state)
    count.value++

    return { count, name }
  },
})
```

### Provide / Inject

```ts
// 父组件
defineComponent({
  setup() {
    const theme = ref('dark')
    provide('theme', theme)
    return {}
  },
})

// 子组件
defineComponent({
  setup() {
    const theme = inject('theme', 'light')
    return { theme }
  },
})
```

### 浅层响应式（Shallow）

```ts
import { shallowReactive, shallowRef } from 'wevu'

defineComponent({
  setup() {
    const state = shallowReactive({
      nested: { count: 0 },
    })

    state.nested = { count: 1 } // 会触发 effect
    state.nested.count++ // 不会触发 effect

    const foo = shallowRef({ bar: 1 })
    foo.value = { bar: 2 } // 会触发 effect
    foo.value.bar++ // 不会触发 effect

    return { state, foo }
  },
})
```

### markRaw

```ts
import { markRaw, reactive } from 'wevu'

defineComponent({
  setup() {
    const classInstance = markRaw(new MyClass())

    const state = reactive({
      // classInstance 不会被转换为响应式
      instance: classInstance,
    })

    return { state }
  },
})
```

## API 参考与 TypeScript 支持

`wevu` 提供完整的 TypeScript 类型导出，你可以在项目中直接引用需要的类型：

```ts
import type { ComponentPublicInstance, Ref, SetupContext } from 'wevu'
```

## 从 Vue 3 迁移到 Wevu（迁移要点）

1. 替换导入：把 `from 'vue'` 改为 `from 'wevu'`
2. 生命周期映射：大多数钩子无需改动，但请注意 `onBeforeMount/onBeforeUnmount` 在小程序里会立即执行
3. 模板差异：使用 WXML（而非 HTML）；双向绑定建议使用 `bindModel()` 生成事件/属性绑定对象
4. 组件注册：`wevu` 组件基于小程序 `Component()`；SFC 场景一般由构建侧（如 Weapp-vite）产出注册代码

## License

MIT

---

---
url: /wevu/api-package.md
description: 说明 wevu/api 的跨端 API 门面定位、与 uni/taro 风格对象的类比关系，以及在 Wevu 项目中的完整调用方式。
---

# `wevu/api`

`wevu/api` 不是一个零散工具集合，而应该被理解成一个“跨端 API 门面对象”。

如果你熟悉 `uni` 或 `Taro` 的全局 API 心智，可以把它理解成同一类东西：

* 业务层不直接依赖单个平台的 `wx / my / tt`
* 统一通过一个对象来调用小程序能力
* 由这层对象负责“平台探测、方法映射、Promise 化、能力缺失时的错误语义”

在 Wevu 体系里，这个角色就是 `wpi`，而 `wevu/api` 则是 `@wevu/api` 在 `wevu/*` 命名空间下的入口。

:::warning 安装方式
`wevu` 请安装在 `devDependencies` 中，而不是 `dependencies`。

推荐写法：

```sh
pnpm add -D wevu
```

原因是 Weapp-vite 会把这类构建期依赖内联到产物里；如果误放到 `dependencies`，通常会被当成运行时 npm 依赖处理，增加产物体积与依赖落位复杂度。
:::

## 它和 `@wevu/api` 的关系

* `wevu/api`：Wevu 体系下的子路径入口
* `@wevu/api`：真正的独立包本体
* 当前导出语义：`wevu/api` 等价于 `export * from '@wevu/api'`

也就是说，`wevu/api` 本质上是“命名空间更统一的入口”，不是另一套独立实现。

## 推荐怎么理解它

不要把它理解成“几个请求工具函数”。

更准确的理解是：

* `wpi` 像 `uni` / `Taro` 暴露出来的统一 API 对象
* 你可以把它当成“跨端版 `wx`”
* 你写的是微信命名 API
* 底层会根据当前宿主平台，决定是直连、显式映射，还是返回 unsupported

例如：

```ts
import { wpi } from 'wevu/api'

await wpi.showToast({
  title: '保存成功',
  icon: 'success',
})
```

这段代码的业务心智是“调用一个统一 API 对象”，而不是“我现在一定跑在微信上，所以我要手动写 `wx.showToast`”。

## 适合什么场景

* 你已经在项目里使用 `wevu`，希望导入路径统一走 `wevu/*`
* 你想通过一个对象统一调用 `wx / my / tt` 等平台能力
* 你希望业务层保持“微信命名 API”写法，同时把平台映射收敛到底层
* 你希望兼顾 Promise 风格与传统回调风格

## 导出项总览

这页最常用的导出有两个：

* `wpi`
* `createWeapi`

```ts
import { createWeapi, wpi } from 'wevu/api'
```

### `wpi`

默认实例，推荐直接使用。

特点：

* 自动探测当前运行平台对象
* 自动做方法映射
* 自动处理 Promise / 回调两种调用语义

### `createWeapi`

手动创建一个 API 实例。

适合场景：

* 测试环境
* 需要显式绑定某个平台对象
* 想在运行时切换 adapter

## 可调用方式一览

这部分是最重要的。`wevu/api` 的“可调用方式”，可以分成 8 类。

### 1. 默认实例调用

最常见、最推荐的方式：

```ts
import { wpi } from 'wevu/api'

await wpi.request({
  url: 'https://example.com/api/list',
  method: 'GET',
})
```

这里的 `wpi` 就是“跨端 API 门面对象”。

### 2. Promise 风格调用

如果最后一个参数里没有传 `success/fail/complete`，则默认走 Promise 风格：

```ts
import { wpi } from 'wevu/api'

const res = await wpi.chooseImage({
  count: 1,
})
```

这也是最推荐的业务写法。

### 3. 回调风格调用

如果你传了小程序传统回调字段，它会保留原有回调语义：

```ts
import { wpi } from 'wevu/api'

wpi.request({
  url: 'https://example.com/api/list',
  success(res) {
    console.log(res.data)
  },
  fail(error) {
    console.error(error)
  },
})
```

这让老代码可以渐进迁移，而不是一次性全改 Promise。

### 4. `*Sync` 直连调用

对于同步 API，不会 Promise 化，直接保持宿主原语义：

```ts
import { wpi } from 'wevu/api'

const systemInfo = wpi.getSystemInfoSync()
const storage = wpi.getStorageSync({ key: 'token' })
```

心智上可以直接把它当成“统一版的同步平台 API”。

### 5. `onXxx / offXxx` 事件订阅调用

对于事件订阅类 API，也不会 Promise 化：

```ts
import { wpi } from 'wevu/api'

function onResize(res: any) {
  console.log('resize', res)
}

wpi.onWindowResize(onResize)
wpi.offWindowResize(onResize)
```

这类 API 保持和平台原生对象一致的调用习惯。

### 6. 显式创建实例调用

如果你不想依赖自动探测，可以手动创建实例：

```ts
import { createWeapi } from 'wevu/api'

const api = createWeapi({
  adapter: wx,
  platform: 'wx',
})

await api.showToast({
  title: 'hello',
  icon: 'none',
})
```

这很适合测试、沙箱运行、或多宿主适配实验。

### 7. 能力探测调用

`wevu/api` 不只是“调用”，还支持“先判断再调用”。

#### `resolveTarget(method)`

查看某个微信命名 API 在当前平台会映射到什么：

```ts
import { wpi } from 'wevu/api'

const target = wpi.resolveTarget('showToast')

console.log(target.method)
console.log(target.target)
console.log(target.platform)
console.log(target.supported)
console.log(target.supportLevel)
console.log(target.semanticAligned)
```

你可以把它理解成“路由表查询”或“平台适配结果解释器”。

#### `supports(method, options?)`

判断某个 API 是否可用：

```ts
import { wpi } from 'wevu/api'

if (wpi.supports('chooseImage')) {
  await wpi.chooseImage({ count: 1 })
}

if (wpi.supports('showToast', { semantic: true })) {
  await wpi.showToast({ title: 'ok' })
}
```

其中：

* 默认 `supports('xxx')` 只看“能不能调用”
* `supports('xxx', { semantic: true })` 看“是不是语义对齐的调用”

### 8. 运行时读取和切换 adapter

实例本身也暴露了 adapter 管理能力。

#### `platform`

读取当前平台标识：

```ts
import { wpi } from 'wevu/api'

console.log(wpi.platform)
```

#### `raw`

读取当前宿主原始对象：

```ts
import { wpi } from 'wevu/api'

console.log(wpi.raw)
```

#### `getAdapter()`

获取当前实例绑定的 adapter：

```ts
import { wpi } from 'wevu/api'

const adapter = wpi.getAdapter()
```

#### `setAdapter(adapter, platform?)`

运行时替换 adapter：

```ts
import { createWeapi } from 'wevu/api'

const api = createWeapi()

api.setAdapter(my, 'my')
await api.showToast({ title: '支付宝环境', icon: 'none' })
```

这在测试里尤其有用。

## 一句话总结这些调用方式

你可以把 `wevu/api` 理解成：

* 一个统一 API 对象：像 `uni` / `Taro`
* 一个默认实例：`wpi`
* 一个实例工厂：`createWeapi`
* 一套能力探测接口：`resolveTarget` / `supports`
* 一组运行时 adapter 控制接口：`platform / raw / getAdapter / setAdapter`

## 业务里最常见的写法

如果你只是日常写业务，通常只会用这两种：

### 写法 A：直接用 `wpi`

```ts
import { wpi } from 'wevu/api'

await wpi.request({
  url: 'https://example.com/api/todos',
})

await wpi.showToast({
  title: '加载完成',
  icon: 'success',
})
```

### 写法 B：先判断能力再调用

```ts
import { wpi } from 'wevu/api'

if (wpi.supports('chooseAddress')) {
  await wpi.chooseAddress()
}
else {
  await wpi.showToast({
    title: '当前平台暂不支持地址选择',
    icon: 'none',
  })
}
```

## 关于“全量 API 列表”

`wevu/api` 理论上可以调用微信命名体系下的大量 API，数量非常多，不适合在这一页逐条罗列。

更实用的阅读方式是：

* 在这里理解“对象心智”和“调用方式”
* 去 [@wevu/api 包文档](/packages/weapi/) 看平台支持矩阵和独立包说明
* 在编辑器里直接通过 `wpi.` 获得类型提示与补全

换句话说，这一页回答的是“怎么用这层对象”，而不是“把 400 多个方法名机械抄一遍”。

## 何时仍然直接看 `@wevu/api` 文档

当你需要：

* 查看独立包定位与发布说明
* 了解平台支持矩阵
* 跟踪 `@wevu/api` 自身的能力边界
* 查看更偏独立包视角的说明

请直接阅读 [@wevu/api 包文档](/packages/weapi/)。

## 相关页面

* [wevu/fetch](/wevu/fetch)
* [wevu/router](/wevu/router)
* [运行时与生命周期](/wevu/runtime)

---

---
url: /wevu/fetch.md
description: 基于 @wevu/api 的 request 能力提供 Fetch 风格接口，说明 wevu/fetch 的定位、限制与推荐用法。
---

# `wevu/fetch`

`wevu/fetch` 提供了一个接近标准 Fetch 的接口，但底层仍然走小程序请求能力。当前实现基于 `@wevu/api` 的 `wpi.request`，适合想用 `fetch(url, init)` 心智写小程序请求的场景。

:::warning 安装方式
`wevu` 请安装在 `devDependencies` 中：

```sh
pnpm add -D wevu
```

这是 Weapp-vite + Wevu 的推荐组合方式。
:::

## 导出内容

* `fetch(input, init?)`

```ts
import { fetch } from 'wevu/fetch'

const response = await fetch('https://example.com/api/user?id=1')
const data = await response.json()
```

## 行为特点

* 返回值是 `Promise<Response>`
* HTTP `4xx/5xx` 不会自动抛错，和标准 Fetch 一致
* 网络层失败会抛出 `TypeError`
* 支持 `AbortSignal`
* `GET/HEAD` 请求不允许携带 `body`
* 默认使用 `arraybuffer` 响应，再按 `Response` 接口能力解码

## 常见示例

### JSON 请求

```ts
import { fetch } from 'wevu/fetch'

const response = await fetch('https://example.com/api/todos', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
  },
  body: JSON.stringify({ title: 'write docs' }),
})

const result = await response.json()
```

### 取消请求

```ts
import { fetch } from 'wevu/fetch'

const controller = new AbortController()

const request = fetch('https://example.com/api/slow', {
  signal: controller.signal,
})

controller.abort()

await request
```

## 与浏览器原生 Fetch 的差异

* `FormData` 请求体当前不支持
* fallback `Response` 下的 `formData()` 也不支持
* 请求最终还是映射到小程序的 `request` 语义，不是浏览器网络栈
* `Headers` / `Response` 在低能力环境下会回退到内部兼容实现

如果你需要的是“统一多端小程序 API 风格”，而不是 Fetch 语义，优先看 [wevu/api](/wevu/api-package)。

## 适合什么场景

* 团队已经习惯 `fetch` 接口
* 想减少 `wx.request` / `wpi.request` 的回调式心智
* 需要和 Web 侧共享一部分请求封装思路

## 相关页面

* [wevu/api](/wevu/api-package)
* [运行时与生命周期](/wevu/runtime)

---

---
url: /wevu/jsx-runtime.md
description: 说明 wevu/jsx-runtime 的用途、适用范围与 TypeScript JSX 配置方式。
---

# `wevu/jsx-runtime`

`wevu/jsx-runtime` 主要是一个类型入口，用于让 TypeScript 在 `jsxImportSource: "wevu"` 场景下正确理解 Wevu 的 JSX 命名空间与小程序内建标签类型。

它不是一个面向业务的“运行时 API 集合”，更接近“给 JSX/TSX 类型系统用的入口”。

:::warning 安装方式
`wevu` 请安装在 `devDependencies` 中：

```sh
pnpm add -D wevu
```

:::

## 当前定位

* 子路径：`wevu/jsx-runtime`
* 主要导出：`JSX` 命名空间类型
* 作用：补充 `IntrinsicElements`、`GlobalComponents` 与小程序标签的属性推导

## 什么时候需要它

* 你在项目里启用了 TSX / JSX
* 你希望通过 `jsxImportSource: "wevu"` 获得更准确的类型提示
* 你在做底层组件封装、类型实验或自定义编译链适配

如果你的项目主要是 `.vue` SFC 或传统小程序页面，不一定会直接接触这个子路径。

## TypeScript 配置示例

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "wevu"
  }
}
```

当配置为 `jsxImportSource: "wevu"` 时，TypeScript 会解析 `wevu/jsx-runtime` 的类型入口。

## 它解决什么问题

* 让 JSX 环境下的小程序标签有更合理的属性提示
* 让全局组件类型可以合并进 `IntrinsicElements`
* 避免 JSX 类型系统默认回落到不适合 Wevu 的 Web/Vue 语义

## 注意事项

* 这是“类型辅助入口”，不是常规运行时导入入口
* 业务代码日常仍然优先从 `wevu` 主入口导入 API
* 如果你没有启用 JSX/TSX，通常不需要显式导入它

## 相关页面

* [Core API](/wevu/api-reference/core)
* [Vue SFC 基础](/wevu/vue-sfc/basics)

---

---
url: /wevu/router.md
description: wevu/router 子路径文档，介绍路径式导航、守卫、失败分类与小程序环境下的边界。
---

# `wevu/router`

`wevu/router` 是 Wevu 提供的独立路由子入口，目标是尽量对齐 Vue Router 的导航心智，同时保持对小程序路由能力边界的明确约束。

如果你只需要拿到原生页面路由对象，请继续使用 `wevu` 主入口里的 `useNativeRouter()` / `useNativePageRouter()`；如果你需要守卫、失败分类、`resolve()` 与更统一的导航封装，请使用 `wevu/router`。

:::tip 创建与获取

* `createRouter()`：负责创建并注册默认 router 实例
* `useRouter()`：负责获取当前已创建的 router 实例

推荐在应用入口或上层 `setup()` 中先调用一次 `createRouter()`，后续业务代码里再通过 `useRouter()` 读取。
:::

:::warning 安装方式
`wevu` 请安装到 `devDependencies`：

```sh
pnpm add -D wevu
```

不要把它放到 `dependencies`。
:::

## 什么时候使用

* 想把页面跳转从“零散 `wx.navigateTo` 调用”升级到统一导航入口
* 想把跳转前判断收敛到 `beforeEach` / `beforeResolve` / `beforeEnter`
* 想获得更接近 Vue Router 的 `resolve()`、`currentRoute` 与失败分类能力

## 最小示例

```ts
import { createRouter, useRouter } from 'wevu/router'

// 在应用入口或上层 setup 中先创建一次
createRouter()

// 业务代码里只负责获取实例
const router = useRouter()

await router.push('/pages/home/index')
await router.replace('/pages/profile/index?tab=security')
await router.back(1)
```

## 在 App 中注册

推荐在应用入口或 App 级 `setup()` 中创建一次 router：

```ts
import { createApp } from 'wevu'
import { createRouter } from 'wevu/router'

const router = createRouter()

createApp({
  setup() {
    // 这里通常不需要额外返回 router
  },
}).use(router)
```

如果你只是想让后续页面/组件里的 `useRouter()` 能拿到默认实例，最关键的是这句：

```ts
const router = createRouter()
```

`createRouter()` 创建时就会注册当前默认 router；`createApp(...).use(router)` 则会把它同步挂到 `app.config.globalProperties.$router`。

### `app.vue` + `<script setup>` 写法

如果你使用的是 Weapp-vite + Vue SFC，通常可以直接在 `app.vue` 顶层创建：

```vue
<script setup lang="ts">
import { createRouter } from 'wevu/router'

createRouter()
</script>
```

关键点：

* 必须是顶层语句
* 不要放进 `onLaunch()`、`onShow()` 或其他 hook 里
* 这样后续页面/组件里的 `useRouter()` 才能直接拿到默认实例

## 核心能力

* `useRouter()`：获取当前已创建的路由实例
* `createRouter()`：创建带守卫、失败分类的高阶路由器
* `useRoute()`：读取当前路由快照
* `resolveRouteLocation()`：预解析目标位置
* `parseQuery()` / `stringifyQuery()`：query 处理工具
* `createNavigationFailure()` / `isNavigationFailure()`：失败对象与判定
* `NavigationFailureType`：失败类别枚举

## 常见心智

### 路径优先

```ts
await router.push('/pages/post/1/index?preview=0')
```

在小程序里，页面物理路径本身就是分包、注册和跳转语义的一部分，所以文档更推荐你直接使用真实页面路径。

### 守卫用于统一前置判断

```ts
import { createRouter } from 'wevu/router'

// 常见做法是在应用入口统一创建 router
const router = createRouter({
  beforeEach(to) {
    if (to.path.startsWith('/pages/private/') && !isLoggedIn()) {
      return '/pages/login/index'
    }
  },
})
```

这样比把跳转限制散落在各个页面里更容易维护。

### 小程序不支持真正 forward 栈

```ts
const result = await router.forward()
```

这在小程序里通常会返回 `NavigationFailureType.aborted`，属于预期行为，不是 bug。

## 调试与迁移建议

* 用 `resolve()` 提前检查 `href / matched / redirectedFrom`
* 把业务里的零散跳转判断迁移到守卫，而不是继续散落在页面逻辑里
* 优先保留小程序真实路径，不要过早抽象成重度命名路由体系

## 相关页面

* [wevu/api-reference/setup-context](/wevu/api-reference/setup-context)
* [wevu/api-reference/runtime-bridge](/wevu/api-reference/runtime-bridge)
* [wevu/api-package](/wevu/api-package)

---

---
url: /config/worker.md
description: 当 app.json 配置了 workers 目录，Weapp-vite 可以帮助编译 Worker 入口脚本。
---

# Worker 配置 {#worker-config}

当 `app.json` 配置了 `workers` 目录，`weapp-vite` 可以帮助编译 Worker 入口脚本。

\[\[toc]]

## `weapp.worker` {#weapp-worker}

* **类型**：
  ```ts
  {
    entry?: string | string[]
  }
  ```
* **默认值**：`undefined`

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

export default defineConfig({
  weapp: {
    worker: {
      entry: ['calc.ts', 'image.ts'],
    },
  },
})
```

说明：

* `entry` 为 **相对于 `app.json.workers` 目录** 的路径。
* 若未写扩展名，会自动尝试 `.js/.ts`。
* Worker 构建会复用 TS/别名/依赖解析能力，并输出到同一 `dist/` 目录下的 `workers/` 目录。

常见问题：

* **未指定 `entry` 会怎样？** 不会额外构建 Worker；你可以自行维护产物，但无法享受自动编译。
* **Worker 入口不存在？** 构建时会输出警告，并跳过该入口。

***

更多调试手段请见 [共享配置 · weapp.debug](/config/shared.md#weapp-debug)。

---

---
url: /guide/directory-structure/workers.md
description: Worker 入口的推荐目录，可与 app.json 和 worker 配置联动。
---

# `workers/`

`workers/` 适合放小程序 Worker 入口。

它不是自动路由目录，也不是自动导入组件目录，但如果项目启用了 Worker，这里通常是一个清晰的落点。

相关能力见：[Worker 配置](/config/worker)

---

---
url: /packages/weapi/overview.md
description: wpi 是 @wevu/api 提供的统一跨端 API 对象，支持 Promise、回调、能力探测与显式平台注入。
---

# `wpi` 概览

`wpi` 是 `@wevu/api` 提供的统一跨端 API 对象。

如果你熟悉 `uni` 或 `Taro` 的全局 API 心智，可以把它理解成同一类能力层：

* 业务层不直接依赖单个平台的 `wx / my / tt`
* 统一通过一个对象调用小程序能力
* 由这层对象负责平台探测、方法映射、Promise 化和错误语义

## 何时使用

* 你希望在业务层统一调用 `wx / my / tt` 等平台能力
* 你希望优先使用 Promise，减少回调嵌套
* 你希望在运行时探测某个微信命名 API 是否可用
* 你希望按平台显式注入 adapter 做测试或多宿主适配

## 安装

```bash
pnpm add -D wevu
```

如果你已经使用 `wevu`，也可以从 [`wevu/api`](/wevu/api-package) 导入同一套能力。

## 基本用法

### Promise 风格

```ts
import { wpi } from 'wevu/api'

const res = await wpi.request({
  url: 'https://example.com',
  method: 'GET',
})
```

### 回调风格

```ts
import { wpi } from 'wevu/api'

wpi.request({
  url: 'https://example.com',
  success(res) {
    console.log(res)
  },
})
```

### 显式实例

```ts
import { createWeapi } from 'wevu/api'

const api = createWeapi({
  adapter: wx,
  platform: 'wx',
})
```

## 行为说明

* 仅在未传回调时返回 Promise
* `*Sync` 与 `onXxx/offXxx` 直连宿主 API
* 可通过 `resolveTarget()` / `supports()` 做能力探测
* 缺失 API 时，Promise 风格会 `reject`，回调风格会触发 `fail`

## 下一步

* 想看整体覆盖情况：[/packages/weapi/compat-overview](/packages/weapi/compat-overview)
* 想查具体 API：[/packages/weapi/wx-method-list](/packages/weapi/wx-method-list)
* 想理解 Wevu 体系里的入口区别：[/wevu/api-package](/wevu/api-package)

---

---
url: /guide/wxml.md
description: WXML 增强，聚焦 guide / wxml 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# WXML 增强

`weapp-vite` 对 WXML 做了两类增强：

* **自动收集 WXML 依赖**：把 `import` / `include` 引到的模板文件自动带进产物
* **事件语法糖（可选）**：允许写 `@tap="fn"`，构建时自动转换成原生 `bind:tap`

本页介绍它们的工作方式，以及不需要时如何关闭。

## 静态分析与额外文件

默认情况下，框架会扫描页面、组件、分包目录，解析 `import` / `include` 中的 `src`，将对应的 WXML 文件复制到产物目录，并保持路径一致。

> \[!IMPORTANT]
> 该分析是静态的，无法推断运行时动态拼接的路径。当前版本的 `weapp.isAdditionalWxml` 仍为预留字段，**不会参与扫描**。如果必须走动态路径，请确保这些模板能通过某个固定的 `import` / `include` 被引用，或在构建流程中自行补充产物。

## 事件绑定语法糖（可选）

开启 `weapp.wxml` 后，可以使用类似 Vue 的 `@` 语法，Weapp-vite 会在构建时转换为原生事件写法：

```html
<!-- 源代码 -->
<view @tap="hello"></view>
<!-- 编译结果 -->
<view bind:tap="hello"></view>
```

对应关系示例：

| 写法                                        | 转换结果            |
| ------------------------------------------- | ------------------- |
| `@tap`                                      | `bind:tap`          |
| `@tap.catch`                                | `catch:tap`         |
| `@tap.mut`                                  | `mut-bind:tap`      |
| `@tap.capture`                              | `capture-bind:tap`  |
| `@tap.capture.catch` / `@tap.catch.capture` | `capture-catch:tap` |

更多事件类型可参考[官方事件分类](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxml/event.html)。

> \[!WARNING]
> 某些第三方 WXML 插件的格式化功能可能无法识别 `@tap` 等语法糖。当前版本暂无单独开关，建议直接使用原生 `bind:` 写法规避冲突。

## 当前可配置的范围

目前 `weapp.wxml` 仅影响 **扫描阶段**（`excludeComponent` / `platform`），模板处理阶段的 `transformEvent` / `removeComment` 等选项尚未接入，详见 [WXML 配置](/config/wxml.md#weapp-wxml)。

---

---
url: /config/wxml.md
description: Weapp-vite 会扫描 WXML 以完成组件自动导入、WXS 依赖分析与模板产物输出。本页说明 weapp.wxml 的配置项与当前生效范围。
---

# WXML 配置 {#wxml-config}

`weapp-vite` 会扫描 WXML 以完成组件自动导入、WXS 依赖分析与模板产物输出。本页说明 `weapp.wxml` 的配置项与当前生效范围。

\[\[toc]]

## `weapp.wxml` {#weapp-wxml}

* **类型**：
  ```ts
  boolean | {
    // 扫描阶段
    excludeComponent?: (tagName: string) => boolean
    platform?: MpPlatform

    // 模板处理阶段（当前版本未接入配置）
    removeComment?: boolean
    transformEvent?: boolean
    scriptModuleExtension?: string
    scriptModuleTag?: string
    templateExtension?: string
  }
  ```
* **默认值**：`true`

### 当前版本的实际生效范围

* **已生效**：`excludeComponent` / `platform`（影响 WXML 扫描）。
* **尚未接入**：`removeComment` / `transformEvent` / `scriptModuleExtension` / `scriptModuleTag` / `templateExtension`。

### 示例

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

export default defineConfig({
  weapp: {
    wxml: {
      excludeComponent(tag) {
        return tag.startsWith('demo-')
      },
    },
  },
})
```

> \[!NOTE]
> 当前版本即便设置 `weapp.wxml = false`，仍会进行基础扫描与产物输出；该字段主要保留用于后续增强选项的统一入口。

***

相关能力：

* [自动导入组件配置](/config/auto-import-components.md#weapp-autoimportcomponents)
* [WXS 配置](/config/wxs.md)

---

---
url: /guide/wxs.md
description: >-
  WXS（WeiXin Script）是微信小程序提供的轻量脚本语言，常用于在模板里做一些同步的、简单的逻辑处理。它和 JavaScript
  不完全一样，能力也更受限。
---

# WXS 增强 experimental

WXS（WeiXin Script）是微信小程序提供的轻量脚本语言，常用于在模板里做一些同步的、简单的逻辑处理。它和 JavaScript 不完全一样，能力也更受限。

`weapp-vite` 为 WXS 提供了实验性的增强：你可以用 `.wxs.js` / `.wxs.ts` 写代码，或在 `<wxs>` 里用 `lang="js/ts"` 内联编写，再由构建阶段转换为标准 `.wxs`。

本页说明怎么用、能用到什么程度，以及遇到问题时如何回退。

> \[!WARNING]
> 该能力仍处于实验阶段，仅支持部分 ES 语法。请务必编写单元测试或在开发者工具中充分验证输出结果。

## 外部文件：`.wxs.js` / `.wxs.ts`

* 在引用 WXS 时，可以把 `src` 指向 `.wxs.js` 或 `.wxs.ts`：
  ```html
  <wxs module="test" src="index.wxs.ts" />
  ```
* 构建产物中会自动生成 `index.wxs` 文件，并把 `src` 改写为 `.wxs`。
* 文件内部可以使用部分 ES 语法（如解构、`const`），但仍需遵守 WXS 运行时的限制：
  * 只能使用 `require`，不能使用 `import`。
  * 不能访问浏览器/Node API。
  * 某些语法（例如 `for...of`、`Array.prototype.map`）仍不被支持。

推荐组合 TypeScript 或 JSDoc 的类型提示，在编辑器中获得更好的开发体验。

## 内联 WXS：`lang="js"` / `lang="ts"`

在 WXML 中内联 WXS 时，可以给 `<wxs>` 标签添加 `lang` 属性，让 Weapp-vite 帮你完成转译：

```html
<view>{{test.foo}}</view>
<view @tap="{{test.trigger}}">{{test.label}}</view>

<wxs module="test" lang="ts">
const { foo, bar } = require('./index.wxs.js')
const extra = require('./extra.wxs')

export const label = 'demo'

export function trigger(value: string) {
  console.log(value, label)
}

export {
  foo,
  bar,
  extra,
}
</wxs>
```

转译后会自动去除类型标注、保留 `require` 调用，并输出合法的 WXS。

## 当前支持的语法

* 变量声明：`const` / `let` / `var`
* 解构赋值、模板字符串、对象展开（大部分场景）
* 函数声明与导出（`export const`、`export function`、`export { ... }`）
* 简单的 TypeScript 类型标注（会在构建时剥离）

> \[!TIP]
> WXS 不支持 Promise 等异步能力，很多 JS 原生方法也不可用；`weapp-vite` 不会自动 polyfill。建议只在 WXS 里写同步、轻量的逻辑。

## 调试与回退方案

* 构建产物位于 `dist/**.wxs`，可直接打开查看 Weapp-vite 的转译结果。
* 若遇到构建失败或运行异常，可临时回退到手写 `.wxs` 版本，或提交 Issue 反馈不兼容的语法。
* 对于复杂逻辑，推荐改写为普通 JS/TS 工具函数，在页面脚本中使用，而不是放在 WXS 中。

随着更多反馈，我们会持续完善 WXS 转译器的兼容性和报错提示。

---

---
url: /config/wxs.md
description: >-
  Weapp-vite 会对 .wxs/.sjs（以及 .wxs.ts/.wxs.js）进行编译输出，并在 Vue SFC 的 class/style
  运行时中按需使用 WXS。
---

# WXS 配置 experimental {#wxs-config}

`weapp-vite` 会对 `.wxs/.sjs`（以及 `.wxs.ts/.wxs.js`）进行编译输出，并在 Vue SFC 的 class/style 运行时中按需使用 WXS。

> \[!WARNING]
> WXS 增强仍处于实验阶段（experimental），建议在开发者工具中充分验证编译与运行结果。

\[\[toc]]

## `weapp.wxs` {#weapp-wxs}

* **类型**：`boolean`
* **默认值**：`true`

### 实际生效范围

* **影响**：Vue SFC 模板编译阶段的 `class/style` 运行时选择（`auto` 时是否优先 WXS）。
* **不影响**：WXML 中显式引用的 `.wxs/.sjs` 仍会被编译输出。

### 示例

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

export default defineConfig({
  weapp: {
    wxs: false, // 禁用 SFC class/style 使用 WXS，强制回退 JS 运行时
  },
})
```

### 常见问题

* **WXML 引用的 `.wxs` 仍然被输出？** 是的，该行为与 `weapp.wxs` 无关。
* **Vue SFC 的 class/style 绑定走 JS 了？** 若设置了 `weapp.wxs = false`，会强制回退到 JS 运行时。

***

相关能力：

* [Vue SFC 配置](/config/vue.md)
* [WXML 配置](/config/wxml.md)

---

---
url: /guide/wxss.md
description: >-
  Weapp-vite 继承了 Vite 的样式处理能力：支持 .wxss、.css、.scss、.less、.sass、.styl
  等格式，并输出为小程序可识别的 WXSS。
---

# WXSS 样式增强与注意点

`weapp-vite` 继承了 Vite 的样式处理能力：支持 `.wxss`、`.css`、`.scss`、`.less`、`.sass`、`.styl` 等格式，并输出为小程序可识别的 WXSS。

本页主要讲两件事：

1. Weapp-vite 会怎么收集/编译同名样式文件
2. 小程序场景里为什么有些 `@import` 不能被“提前内联”，以及怎么处理

## 支持的样式格式

入口脚本（如 `pages/index/index.ts`）在构建时会按固定顺序注入同名样式文件：

```ts
import './pages/index/index.wxss'
import './pages/index/index.css'
import './pages/index/index.scss'
import './pages/index/index.less'
import './pages/index/index.sass'
import './pages/index/index.styl'
```

只要安装了对应的预处理器依赖（`sass`、`less`、`stylus`），上述文件都会被 Rolldown 处理并转换成 WXSS。

## Vite 的默认行为

在 Web 项目中，Vite 会解析样式里的 `@import`、`url()` 等语句，在构建阶段将其“内联”成一份完整的样式。这在小程序项目里同样适用：

```scss
/* input.scss */
@import './base.scss';
.box {
  background: pink;
}
```

```css
/* output.wxss */
/* from base.scss */
.base {
  background: pink;
}
.box {
  background: pink;
}
```

> \[!NOTE]
> 预处理器通常不会识别 `.wxss` 扩展名。如果需要在 SCSS 中引用 `.wxss` 文件，需要额外配置 resolver，或使用同名的 `.scss` 文件。

## 小程序场景下的差异

小程序原生支持 `@import`，由运行时解析路径并加载对应文件。部分生态（如 TDesign 的主题切换）依赖这种机制，如果被 Vite 内联，就会破坏原有逻辑。

为此 Weapp-vite 提供了一个自定义指令 `@wv-keep-import`，用于跳过 Vite 的内联处理：

```diff
- @import 'miniprogram_npm/tdesign-miniprogram/common/style/theme/_index.wxss';
+ @wv-keep-import 'miniprogram_npm/tdesign-miniprogram/common/style/theme/_index.wxss';
```

编译后会恢复为原生写法：

```css
@import 'miniprogram_npm/tdesign-miniprogram/common/style/theme/_index.wxss';
```

这样微信开发者工具就能在运行时继续处理该依赖。

### 何时使用 `@wv-keep-import`

* 需要把 `@import` 原封不动交给小程序运行时。
* 引用路径指向 `miniprogram_npm`、分包或其他构建后目录。
* 希望在 WXSS 里保留官方语法（尤其是 `_index.wxss`、`theme` 等主题相关文件）。

对于普通的样式拆分，仍建议使用默认的 `@import` 或 `@use`，让构建器提前合并，提升首屏效率。

## 资源引用与公共样式

* 使用 `@/`、`./` 等路径导入图片时，Rolldown 会自动复制并生成正确的产物路径。
* 若资源位于 `public/`，请改用绝对路径 `/icons/logo.png`，该目录会被原样复制。
* 可结合 [`weapp.subPackages[].styles`](/config/subpackages.md#subpackages-styles) 在普通或独立分包中注入共享主题、变量。

## 常见问题

* **样式顺序异常？** Weapp-vite 会按固定顺序注入不同后缀的文件，建议团队统一主力格式（例如全部使用 `.scss`）。
* **SCSS 引入 `.wxss` 报错？** 这是 Sass 的限制。可以将共享样式改为 `.scss`，或在编译后通过 `@wv-keep-import` 保留 WXSS 引入。
* **`@wv-keep-import` 不生效？** 请确认对应文件在构建产物中仍保留了 `@import`，若被其他插件处理，可尝试调整插件顺序或在 PostCSS 阶段配置 `exclude`。

---

---
url: /wevu/why-not-runtime-core-create-renderer.md
description: >-
  解释 Wevu 为什么没有采用 @vue/runtime-core 的 createRenderer
  作为主实现路径，并给出当前架构下的可行替代方案与技术判断。
---

# 为什么没有使用 @vue/runtime-core 的 createRenderer 来实现

这个问题可以拆成两层：

1. **技术上能不能做**：可以做。
2. **在 Wevu 当前目标下是否应该作为主实现**：不建议。

核心原因不是 `createRenderer` 不先进，而是它要求的“宿主能力模型”和小程序运行时的“数据驱动 + `setData`”模型并不对齐。

## 先看官方定义：createRenderer 需要什么

Vue 官方对自定义渲染器的定义很明确：`createRenderer(options)` 需要你提供一整套宿主节点操作（`patchProp`、`insert`、`remove`、`createElement`、`createText`、`parentNode`、`nextSibling` 等）。

* 官方文档：<https://vuejs.org/api/custom-renderer.html>
* 中文文档：<https://cn.vuejs.org/api/custom-renderer>

这套接口天然是“节点树增删改查”范式，适合 DOM、Canvas、Native UI 树这类可以被**命令式节点操作**驱动的宿主环境。

## Wevu 当前解决的问题是什么

Wevu 不是在做“替代浏览器 DOM 的通用渲染器”，而是在做“小程序运行时桥接”：

* 编译期（wevu/compiler + Weapp-vite）把模板编译为 WXML；
* 运行期维护响应式状态；
* 通过快照 diff 生成最小化 `setData` payload；
* 把更新下发到小程序视图层。

换句话说，Wevu 的关键优化点是：**控制 `setData` 的时机和体积**，而不是维护一棵可命令式操作的 host node 树。

## 架构不对齐的关键点

### 1) 注册模型不同：小程序以 App/Component 为中心

Wevu 的页面/组件注册直接走小程序 `App()` / `Component()`，生命周期与能力边界也围绕它们展开。

这意味着 Wevu 的“实例边界”天然是小程序实例，而不是 renderer 的“容器 + vnode root”。

### 2) 更新通道不同：setData payload，不是 host node patch

Wevu 更新链路的核心是：

`reactive/effect -> scheduler -> snapshot -> diff -> setData(payload)`

这个链路与 renderer 的 host ops 模型是两套抽象：

* renderer 关心“节点如何插入/删除/重排”
* Wevu 关心“哪些路径需要进 payload，如何控制字节大小和回退策略”

### 3) 编译契约不同：当前产物不是 render function 契约

Wevu 的 SFC/模板编译链路输出的是“小程序模板 + 运行时桥接代码”，不是交给 runtime renderer 执行的 vnode render 函数契约。

如果主架构迁移到 `createRenderer`，编译器与运行时契约需要一起重写，成本非常高。

## 为什么说“可以做，但不建议做主实现”

可以做 PoC 的原因：

* 可以人为构造一套 host node 抽象，把节点操作最终折叠成数据更新。

不建议作为主实现的原因：

* 会引入“抽象错位”：为了满足 host ops，不得不在小程序之上再模拟一层节点树；
* 可能出现“双重成本”：既有 renderer patch 成本，又要处理 `setData` 约束；
* 迁移收益不确定：Wevu 当前痛点（payload 控制、生命周期桥接、平台差异）不会因为用了 `createRenderer` 自动消失。

## 关于 “Taro 那种大 base.wxml 方案” 的结论

这类路线（一个较大的 `base.wxml` + 运行时驱动节点树）在技术上可行，Wevu 也不是绝对不能做。

但在小程序语境里，主流情况下会有下面这个工程事实：

1. 运行时需要维护额外的节点/实例映射与协调过程，计算与内存开销更高；
2. `base.wxml` 体积与通用性提高后，模板解析与初始化成本通常也会变重；
3. 最终仍要落到小程序 `setData`，因此上层抽象并不能绕开桥接成本。

因此更务实的结论是：

* **“可以做”**：是；
* **“默认性能会更好”**：通常不是；
* **“多数业务场景下，性能大概率低于当前 Wevu 的快照 diff + 最小 setData 链路”**：是更常见的结果。

## 当前策略与后续路线

当前策略：

* 主线继续保持“编译到 WXML + 运行时快照 diff + 最小 setData”的架构。

建议路线：

1. 若要验证 `createRenderer`，放在实验分支或独立实验包进行。
2. PoC 验收只看三件事：功能覆盖、更新性能、payload 体积。
3. 在未证明明显收益前，不替换现有主链路。

## 一句话总结

`createRenderer` 是优秀的“通用渲染器内核能力”；Wevu 解决的是“小程序 setData 语义下的运行时工程问题”。
在当前目标下，Wevu 选择不把 `createRenderer` 作为主实现，是一个更务实的工程取舍。

---

---
url: /guide/what-is-weapp-vite.md
description: >-
  Weapp-vite 是一个面向微信小程序的现代构建框架：尽量不改变你写原生小程序的方式（语法、目录结构都能沿用），但把 Vite
  生态、TypeScript、CSS 预处理器和更顺滑的开发/构建流程带进来。你仍然写小程序，但开发体验会更…
---

# 什么是 Weapp-vite ?

## 核心简介

`weapp-vite` 是一个面向微信小程序的现代构建框架：尽量不改变你写原生小程序的方式（语法、目录结构都能沿用），但把 Vite 生态、TypeScript、CSS 预处理器和更顺滑的开发/构建流程带进来。你仍然写小程序，但开发体验会更接近“现代前端工程”。

## 我们想解决的问题

* 原生工具链缺少一些现代体验：模块化、自动刷新、类型提示等效率工具不够完善。
* 跨端框架虽然功能丰富，但抽象层更厚，学习/调试成本更高；并不适合想坚持原生写法的团队。
* 老项目常见的 gulp / 自研脚本维护成本高：升级依赖、接入新能力都比较费劲。

## Weapp-vite 的能力亮点

* **原生写法 0 改动**：保留微信原生语法和目录组织方式，逐步引入现代能力。
* **Vite/Rolldown 生态**：兼容 Vite 配置与插件，底层打包器 Rolldown 针对小程序场景做了分包、样式注入等优化。
* **工程化开箱即用**：默认支持 TypeScript、PostCSS、Sass/Less、Tailwind CSS、JSONC 等常用特性，并提供 `pnpm create weapp-vite` 和 `pnpm g` 等脚手架命令。
* **小程序特色增强**：自动构建 `miniprogram_npm`、智能分包依赖分析、自动组件注册、WeChat Developer Tools CLI 集成。
* **良好的调试体验**：保存即热更新、详细的构建日志、`weapp.debug` 钩子帮助排查路径解析、产物归属等问题。

## 什么时候适合选择 Weapp-vite

* 你想坚持原生小程序写法，同时想要现代前端工具链（TS、模块化、热更新等）。
* 团队有存量项目，想尽量不动业务代码就升级构建流程。
* 你需要深入用微信提供的底层能力（如 Skyline、Donut），对运行时兼容层比较谨慎。

## 什么时候可以考虑其他方案

* 项目需要“一套代码多端运行”，或想直接用 `Vue`/`React` 写界面：可以优先评估 `uni-app`、`taro` 等跨端框架。
* 如果你只需要很基础的构建能力，并且已经投入了其他脚手架：可以先沿用现有方案，合适的时候再迁移。

## 迁移与生态

* `weapp-vite init` 支持在现有原生项目上直接生成配置，沿用原目录结构即可。
* 构建产物完全兼容微信开发者工具，分包、插件、Worker 等官方能力都可以继续使用。
* 通过 Vite 插件体系可以快速接入 Tailwind CSS、UnoCSS、自动化测试、Rollup 插件等生态资源。

想要快速验证效果？前往 [快速开始](/guide/) 章节，十分钟内完成首个项目的创建、运行与调试。

---

---
url: /migration/v3.md
description: 这可能会导致一些 vite 的配置项失效，请根据 v6 的文档进行配置。
---

# 从 v2 升级到 v3

## 重大变更

### 升级了内置 `vite` 的版本，从 `v5` 到 `v6`,

这可能会导致一些 `vite` 的配置项失效，请根据 `v6` 的文档进行配置。

同时由于内部的 `rollup` 插件也得到了升级，可能会导致一些 `commonjs` 和 `esm` 混用的情况失效

## 修复

* 修复了构建 `npm` 包，不自动构建依赖的问题 [#104](https://github.com/weapp-vite/weapp-vite/issues/104)
* 修复了自动构建 `npm` 时，会删除独立子包中的 `miniprogram_npm` 目录问题

---

---
url: /migration/v4.md
description: '由于 4 的更改，这导致我们项目中，假如需要引用外部的 cjs / umd 模块，比如: visactor index-wx-simple.min.js'
---

# 从 v3 升级到 v4

## 重大变更

1. 现在 `autoImportComponents.globs` 是以 `srcRoot` 作为路径，以前是以 `cwd` 作为基准路径，鼓励将所有的资源都放在 `srcRoot` 内部

```diff
    enhance: {
      autoImportComponents: {
-       globs: ['src/components/**/*'],
+       globs: ['components/**/*.wxml'],
      },
    }
```

2. 完全重构的编译核心，带来了更高效的处理速度的同时，也带来了更加强大的扩展性
3. 放弃了 `ts-morph` 编译 `worker` 的实现，因为太慢了，转变为直接使用 `vite` 进行编译
4. 使用 `vite-plugin-commonjs` 来处理项目中带有的 `require` 问题，而不是使用 `@rollup/plugin-commonjs`

由于 `4` 的更改，这导致我们项目中，假如需要引用外部的 `cjs` / `umd` 模块，比如: [visactor index-wx-simple.min.js](https://visactor.io/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/mini-app/wx)

我们需要手动把 `index-wx-simple.min.js` 重命名为 `index-wx-simple.min.cjs` (`js` -> `cjs`)

然后再在你的项目中进行引入:

```ts
import VChart, { vglobal } from './vchart/index-wx-simple.min.cjs'
```

这样就可以正常使用了, [Demo案例](https://github.com/weapp-vite/weapp-vite/tree/main/apps/vite-native/components/chart)

---

---
url: /migration/v5.md
description: 从 v4 升级到 v5，聚焦 migration / v5 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 从 v4 升级到 v5

`weapp-vite@5` 版本编号: `不破不立`

## 重大变更

### 1. 从 `vite` 切换到 `rolldown-vite`

为了带给用户更好的体验，我决定从 `vite` 切换到 `rolldown-vite` 来解决经常被用户诟病的热更新慢的问题

然后我以我一个复杂的测试案例进行性能测试，主包有 `726` 个模块，独立分包有 `643` 个模块，测试结果如下：

整体平均构建时间提升：约 `1.86` 倍

热更新平均构建时间提升：约 `2.50` 倍

`vite` 的整体平均构建时间为 `4302.26` ms, 构建热更新平均构建时间为 `2216.58` ms

切换到 `rolldown-vite` 后，整体平均构建时间为 `2317.75` ms, 构建热更新平均构建时间为 `887.56` ms

### 2. 从 `tsup` 切换到 `tsdown`

都是基于 `rolldown` 生态的

### 3. 从 `bunldle-require` 切换到 `rolldown-require`

`rolldown-require` 是我在这个项目写的一个包，基于 `rolldown` 的

使用 `API` 和配置方面，参考了 `bunldle-require` 但是代码完全不同，代码绝大部分都是从 `rolldown-vite` 抽离出来的

## 迁移成本

目前测试用例暂时都是全部通过的，配置项也完全一致。

基本不需要做什么配置上的变更，就能平滑升级上来。

## 是否过于激进?

本来这种事情就是不破不立，我希望给用户带来极致的体验，而不是保存一下等半天，这会让我感觉到自己很失败

我试了我所有的模板，还有 `200` 个测试用例都跑通了，所以 `weapp-vite` 认为 `v5` 升级还是利极大的大于弊的。

---

---
url: /migration/v6.md
description: 从 v5 升级到 v6，聚焦 migration / v6 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 从 v5 升级到 v6

> 提示：如果要在小程序中使用 Vue SFC，请先安装 Wevu 运行时，并确认 Volar 插件已就绪。

## 升级步骤

1. **升级依赖**

   ```sh
   pnpm up weapp-vite@latest
   pnpm install
   ```

2. **安装 Wevu（开启 Vue SFC 能力）**
   * 安装 `wevu`：

     ::: code-group

     ```sh [pnpm]
     pnpm add -D wevu
     ```

     ```sh [yarn]
     yarn add -D wevu
     ```

     ```sh [npm]
     npm i -D wevu
     ```

     ```sh [bun]
     bun add -D wevu
     ```

     :::

   * 在页面/组件中直接从 `wevu` 导入 `defineComponent/ref/reactive` 等 API（页面也直接使用 `defineComponent(...)`）。

   * 旧的外置 Vue 插件已不再需要。

3. **Volar/类型提示检查**
   * 确认 `tsconfig.app.json`（或项目主 `tsconfig.json`）里已包含：
     ```json
     {
       "vueCompilerOptions": {
         "plugins": ["weapp-vite/volar"]
       }
     }
     ```
   * VSCode 安装 “Vue - Official (Volar)” 扩展，必要时重启 TS Server。

## 变更要点

* Weapp-vite 内置 Vue SFC 编译链；无需额外插件。
* Vue SFC 运行依赖 Wevu，请显式安装并从主入口导入。
* 其余配置与 v5 基本兼容，原生小程序代码无须改动。

---

---
url: /wevu/migration/from-native-to-vue-sfc.md
description: >-
  这是一份面向实际项目的迁移手册，不是概念介绍。目标是让你在**不重写业务**的前提下，把原生小程序稳定迁移到 Weapp-vite + Wevu + Vue
  SFC。
---

# 从原生小程序迁移到 Vue SFC（详细指南）

这是一份面向实际项目的迁移手册，不是概念介绍。目标是让你在**不重写业务**的前提下，把原生小程序稳定迁移到 `weapp-vite + Wevu + Vue SFC`。

适用场景：

* 线上已有原生小程序，想提升工程效率与可维护性。
* 新项目计划直接采用 Vue SFC 写法，同时保留小程序原生能力。

## 迁移目标与验收标准

建议先明确“迁移完成”意味着什么，避免只完成了语法替换。

* 功能等价：核心页面流程（浏览、下单、支付、售后）行为与原版一致。
* 稳定性提升：常见空值场景不再出现 `map/forEach of undefined`。
* 结构升级：页面和组件统一为 `.vue` + `<script setup lang="ts">`。
* 可持续迭代：新增需求不再依赖 `setData` 大对象回写。
* 工程闭环：`build + 定向 e2e` 可覆盖关键链路。

## 迁移前准备（必须做）

### 1. 版本与工程基线

* 升级到 `weapp-vite@6.x`（Vue SFC 支持前提）。
* 安装并启用 `wevu` 运行时。
* 确认 `tsconfig.app.json` 已配置：
  * `"vueCompilerOptions.plugins": ["weapp-vite/volar"]`
  * `"vueCompilerOptions.lib": "wevu"`

### 2. 冻结阶段策略

迁移周期内，建议对核心页面采用“冻结功能、只修缺陷”的策略。

* 先控制变量，再改技术栈。
* 每次迁移只涉及一个页面族（如订单、优惠券），避免并发大改。

### 3. 建立对照样本

至少挑 1 个“中等复杂度页面”做试点：

* 有列表渲染（`map/forEach`）
* 有异步请求
* 有页面参数（`onLoad(query)`）
* 有导航/分享/滚动等页面事件

## 总体迁移路线（推荐 4 阶段）

```mermaid
flowchart LR
  A[阶段 0<br/>接入 weapp-vite] --> B[阶段 1<br/>机械迁移到 .vue]
  B --> C[阶段 2<br/>语义迁移到 Composition API]
  C --> D[阶段 3<br/>收口与回归]
```

### 阶段 0：只替构建链路，不改业务行为

先接入 `weapp-vite` 并保证原功能可跑，不立即重构逻辑。

验证最小闭环：

* `pnpm build`
* 在开发者工具中打开并手测 1 到 2 个核心页面

### 阶段 1：机械迁移（重点是“等价”）

先把原 `js + wxml + wxss + json` 聚合成单个 `.vue`，不追求代码优雅。

### 阶段 2：语义迁移（重点是“可维护”）

把 `this.data + this.setData + methods` 逐步替换为 `ref/reactive/computed/watch`。

### 阶段 3：收口（重点是“可持续”）

统一风格、补齐测试、清理历史写法，沉淀迁移规范。

## 原生到 Vue SFC 映射表（高频）

| 原生小程序                 | Vue SFC / Wevu 对应                                                  | 迁移建议                             |
| -------------------------- | -------------------------------------------------------------------- | ------------------------------------ |
| `Page({...})`              | `<script setup>` + `definePageJson` + Wevu hooks                     | 页面不再写原生构造器                 |
| `Component({...})`         | `<script setup>` + `defineComponentJson` + `defineProps/defineEmits` | 组件声明聚合到 SFC                   |
| `data: {}`                 | `ref/reactive`                                                       | 细粒度状态更易维护                   |
| `this.setData({...})`      | 直接赋值：`state.xxx = y`                                            | 由 Wevu 负责最小更新                 |
| `onLoad/onShow/onHide/...` | `onLoad/onShow/onHide/...`（从 `wevu` 导入）                         | 生命周期迁移成本低                   |
| `observers`                | `watch` / `watchEffect`                                              | 逻辑更明确，易测试                   |
| `properties`               | `defineProps`（推荐）或兼容 `properties`                             | 新代码优先 Vue 风格                  |
| `triggerEvent`             | `defineEmits` + `emit(...)`                                          | 类型更清晰                           |
| `usingComponents`          | `definePageJson/defineComponentJson` 或 `<json>`                     | 不要在脚本里 `import` 注册小程序组件 |

## 迁移波次设计（建议 2 到 6 周）

如果你是存量项目，建议按“波次”推进，而不是按“技术点”推进。一次只迁移一个业务域，能显著降低回归成本。

| 波次   | 范围     | 目标                                | 退出条件                         |
| ------ | -------- | ----------------------------------- | -------------------------------- |
| Wave 0 | 框架接入 | 接入 Weapp-vite + Wevu，业务 0 改动 | `build` 可过，首页可打开         |
| Wave 1 | 低风险页 | 列表页、展示页迁移到 SFC            | 页面冒烟 + 基础 e2e 通过         |
| Wave 2 | 中风险页 | 表单页、筛选页、详情页              | 正/反向流程通过，参数健壮性通过  |
| Wave 3 | 高风险页 | 下单、支付、售后等核心路径          | 关键链路 e2e 通过 + 真机回归通过 |
| Wave 4 | 收口     | 清理遗留 `setData` 大对象写法       | 编码规范统一，迁移文档补齐       |

每个波次建议都固定执行这 4 步：

1. 迁移前记录基线行为（页面入口、关键交互、关键接口）。
2. 机械迁移为 `.vue`，不做业务重构。
3. 语义迁移到 `ref/reactive/watch/emit`。
4. 做定向验证并沉淀坑位清单。

## setup 上下文迁移：`this` 到 `ctx/instance` 对照

原生代码常直接依赖 `this` 上的方法（如 `triggerEvent`、`createSelectorQuery`、`setData`）。
迁移到 Wevu 后，建议使用 `setup(props, { emit, instance })`，优先通过 `emit` 与响应式状态完成业务，必要时再使用 `instance` 访问原生能力。

```ts
import { defineComponent, ref } from 'wevu'

export default defineComponent({
  setup(_, { emit, instance }) {
    const count = ref(0)

    function onTap() {
      count.value += 1
      emit('change', count.value)
    }

    function queryRect() {
      return instance
        .createSelectorQuery()
        .select('.card')
        .boundingClientRect()
        .exec()
    }

    function patchPayload(payload: Record<string, any>) {
      return instance.setData(payload)
    }

    return { count, onTap, queryRect, patchPayload }
  },
})
```

迁移建议：

* `triggerEvent` 优先改为 `emit`，只在明确需要原生语义时用 `instance.triggerEvent`。
* 不建议把 `instance` 暴露到模板或返回给外部模块。
* 如果只是更新视图状态，优先直接写响应式变量，不要回退到手写 `setData`。

## 组件契约迁移：`properties/observers` 到 `defineProps/defineEmits/watch`

迁移组件时，推荐先把“输入契约”和“输出契约”类型化，再迁移内部逻辑。这样能在迁移阶段提前暴露大量隐藏问题。

```vue
<script setup lang="ts">
import { computed, watch } from 'wevu'

const props = withDefaults(defineProps<{
  modelValue?: number
  disabled?: boolean
}>(), {
  modelValue: 0,
  disabled: false,
})

const emit = defineEmits<{
  change: [id: number]
  update: [value: number]
}>()

const value = computed({
  get: () => props.modelValue,
  set: next => emit('update', next),
})

watch(() => props.disabled, (disabled) => {
  if (disabled) {
    emit('change', -1)
  }
})
</script>
```

迁移建议：

* `properties` 优先迁移到 `defineProps`，保留默认值和可选关系。
* `observers` 优先迁移到 `watch`，避免“隐式副作用”扩散。
* `triggerEvent` 统一迁移到 `defineEmits` + `emit`，事件名和 payload 类型显式定义。

## Behavior 迁移：`Behavior({...})` 到 Wevu 组件体系

在原生小程序里，`Behavior` 本质是组件选项复用机制。迁移到 Wevu 后，建议保留这个模型，不要把 behavior 逻辑拆散到多个自定义工具函数里。

迁移原则：

* `wevu` 不重写 `behaviors` 的合并/覆盖规则，仍交给小程序原生 `Component()` 处理。
* behavior 文件继续保持“单独导出 + 组件引用”的结构，降低回归风险。
* 新代码优先迁移组件主逻辑到 `setup`，behavior 里保留“横切能力”。

### 字段对照（原生 Behavior -> Wevu）

| 原生 Behavior 字段                   | 迁移后位置                                                    | 说明                                         |
| ------------------------------------ | ------------------------------------------------------------- | -------------------------------------------- |
| `data`                               | 保留在 behavior 内，或迁移到组件 `setup` 状态                 | 推荐保留 behavior 内的数据契约，避免语义漂移 |
| `properties`                         | 组件优先改为 `defineProps`；behavior 内的 `properties` 可保留 | 组件声明覆盖 behavior 同名字段（原生语义）   |
| `methods`                            | 保留在 behavior 或迁移到 `setup` 返回函数                     | 事件/实例方法都可继续复用                    |
| `lifetimes` / `pageLifetimes`        | 继续写在 behavior / 组件中                                    | 执行顺序仍以微信官方规则为准                 |
| `observers`                          | 可保留；新逻辑推荐迁移到 `watch/watchEffect`                  | 复杂表达式监听仍可留在 `observers`           |
| `definitionFilter` / `export` / 其他 | 继续写在组件选项中                                            | Wevu 透传给原生 `Component()`                |

### 推荐写法 A：`<script>` + `defineComponent`

```vue
<script lang="ts">
import { defineComponent } from 'wevu'
import SkylineBehavior from '@/behaviors/skyline'

export default defineComponent({
  behaviors: [SkylineBehavior],
  lifetimes: {
    attached() {
      // 组件自身逻辑
    },
  },
})
</script>
```

### 推荐写法 B：`<script setup>` + `defineOptions`

```vue
<script setup lang="ts">
import SkylineBehavior from '@/behaviors/skyline'

defineOptions({
  behaviors: [SkylineBehavior],
})
</script>
```

补充：

* 内建 behavior（如 `wx://component-export`）可直接写字符串。
* 若 behavior 条目来自原生 `Behavior()` 返回值，`defineOptions` 在编译阶段会保留该表达式继续转换，不会因为构建环境无全局 `Behavior` 而中断。
* 若同名字段在组件与 behavior 同时声明，最终行为仍以微信官方 `behaviors` 覆盖与执行顺序规则为准。

### Behavior 迁移清单（建议按顺序执行）

1. 先保留 behavior 文件结构与导出方式，不做业务重构。
2. 在组件里先接入 `behaviors: [...]`，确认功能基线一致。
3. 将组件主流程迁移到 `setup`，behavior 仅保留复用横切逻辑。
4. 把新增观察逻辑优先写成 `watch/watchEffect`，旧 `observers` 逐步清理。
5. 最后再处理命名/目录规范，不与行为迁移混在同一提交。

## 多平台差异处理：`import.meta.env.PLATFORM`

当你在同一套业务代码中兼容微信、抖音、支付宝等平台时，迁移阶段就要把平台分支显式化，避免在运行时才踩到 `wx`/`my` 不存在的问题。

```ts
const platform = import.meta.env.PLATFORM

if (platform === 'weapp') {
  wx.showToast({ title: '微信环境' })
}
else if (platform === 'tt') {
  tt.showToast({ title: '抖音环境' })
}
```

实践建议：

* 新增平台分支时，优先按能力分组，不要按页面复制逻辑。
* 把平台判断集中在 `shared/platform.ts` 之类的模块，减少散落分支。
* 迁移验收时至少覆盖“主平台 + 一个次平台”。

## 实操：从 4 文件迁移为 1 个 SFC

### 迁移前（原生页面）

```js
// pages/coupon/coupon-activity-goods/index.js
Page({
  data: {
    goods: [],
    detail: {},
  },
  onLoad(query) {
    const id = Number(query.id)
    this.id = id
    this.getCouponDetail(id)
    this.getGoodsList(id)
  },
  getGoodsList(id) {
    fetchGoodsList(id).then((goods) => {
      this.setData({ goods })
    })
  },
})
```

### 迁移后（Vue SFC 页面）

```vue
<script setup lang="ts">
import { onLoad, ref } from 'wevu'
import { fetchGoodsList } from '../../../services/good/fetchGoods'

definePageJson(() => ({
  navigationBarTitleText: '活动商品',
  usingComponents: {
    'goods-list': '/components/goods-list/index',
  },
}))

const goods = ref<any[]>([])
const couponId = ref<number>(0)

onLoad(async (query) => {
  couponId.value = Number(query?.id ?? 0)
  await getGoodsList(couponId.value)
})

async function getGoodsList(id: number) {
  const list = await fetchGoodsList(id)
  goods.value = Array.isArray(list) ? list : []
}
</script>

<template>
  <goods-list :goods-list="goods" />
</template>
```

> 迁移第一步允许“结构升级但逻辑不重构”。先跑通，再优化。

## 两种落地策略：渐进式 vs 直接式

### 方案 A：渐进式（推荐）

先用 `<script setup>` + `defineOptions({...})` 保持原对象风格，再逐步迁移到组合式 API。

适合：存量页很多、业务变更频繁、团队迁移经验不足。

### 方案 B：直接式

一步到位改成 `ref/reactive/watch + hooks`。

适合：页面规模小、测试完善、迁移窗口集中。

## 最容易出错的 8 个点（含修复方式）

### 1. `map/forEach of undefined`

根因：接口字段为空、类型不稳定、参数解析失败。

修复：

* 所有列表统一 `Array.isArray` 兜底。
* JSON 参数反序列化加 `try/catch`。
* 模板里避免对可空对象深链访问。

```ts
const skuDetailVos = Array.isArray(ele.skuDetailVos) ? ele.skuDetailVos : []
const specs = Array.isArray(item.skuSpecLst)
  ? item.skuSpecLst.map(s => s?.specValue).filter(Boolean)
  : []
```

### 2. 组件不渲染

根因：只在脚本里 `import`，没有写 `usingComponents`。

修复：把注册写到 `definePageJson/defineComponentJson` 或 `<json>`。

### 3. `v-model` 行为不符合预期

根因：小程序不是 DOM 事件模型，且存在标签映射限制。

修复：复杂组件改为显式 `:value` + `@input/@change`；必要时使用 `useBindModel`。

### 4. 生命周期没触发

根因：迁移后把页面事件写成普通函数，未通过 Wevu hooks 注册。

修复：从 `wevu` 导入 `onLoad/onPageScroll/onShareAppMessage/...`。

### 5. 页面参数类型错乱

根因：`query` 全是字符串，直接当 number/object 使用。

修复：统一做 parse 层和默认值层。

### 6. 本地开发能跑，但构建后页面崩溃

根因：只验证了 dev 场景，没有验证 build 产物与真机行为。

修复：每轮迁移都执行“开发调试通过 -> 构建验证通过 -> 真机关键路径回归”。

### 7. 一次迁移太多页面导致回滚困难

根因：提交粒度过大。

修复：按“页面族”迁移，每次只处理一个业务域并可单独回滚。

### 8. 先重构再迁移，问题难定位

根因：把“技术迁移”和“业务重构”耦合。

修复：先机械迁移，再结构优化。

## 推荐目录与分层（迁移后）

建议每个页面按“页面 SFC + 同目录服务/工具”组织，避免继续堆在大 `index.vue`。

```text
pages/order/order-confirm/
  index.vue
  pay.ts
  mapper.ts
  guards.ts
```

拆分规则：

* `mapper.ts`：接口 DTO -> 视图模型转换。
* `guards.ts`：空值保护、参数合法化、兜底逻辑。
* `pay.ts`：支付等副作用流程。

## 页面迁移清单（可直接执行）

### 清单 A：机械迁移

1. 合并 `index.js/wxml/wxss/json` 到 `index.vue`。
2. 保留原函数名与流程，不动业务逻辑。
3. 补齐 JSON 配置（导航栏、组件注册、页面配置）。
4. build 并手测页面主路径。

### 清单 B：语义升级

1. 用 `ref/reactive` 替代 `this.data`。
2. 用直接赋值替代 `setData`。
3. 用 `watch/watchEffect` 替代 `observers`。
4. 抽离 `mapper/guards`，减少页面脚本复杂度。

### 清单 C：发布前联调

1. 把迁移页面按真实用户路径串起来联调一遍（进入、操作、返回、再进入）。
2. 对核心接口做异常场景验证（空数组、空对象、字段缺失、接口超时）。
3. 确认构建产物在开发者工具与真机表现一致。

## 验证策略（从小到大）

### 1. 单页面冒烟

* 进入页面
* 请求成功/失败分支
* 操作按钮
* 页面返回与再次进入

### 2. 目标构建验证

```bash
pnpm build
```

### 3. 关键链路 e2e

只覆盖高价值路径，不建议迁移阶段就跑全量：

* 下单确认
* 优惠券活动商品
* 地址选择/回填

### 4. e2e 捕获渲染报错（推荐接入）

迁移阶段最常见的问题不是“构建失败”，而是“运行时报错但没有被测试显式失败”。
建议在 e2e 里统一接入运行时错误收集器，把 `console.error`、异常栈直接挂到断言失败信息里。

仓库里已有可复用实现：`e2e/ide/runtimeErrors.ts`。

```ts
import { attachRuntimeErrorCollector } from '../runtimeErrors'

const collector = attachRuntimeErrorCollector(miniProgram)
const marker = collector.mark()

// 执行页面操作...

const runtimeErrors = collector.getSince(marker)
expect(runtimeErrors).toEqual([])
collector.dispose()
```

建议把它作为所有迁移 e2e 的标准模板，确保：

* TypeError / RangeError 不会被吞掉。
* 页面“看起来可渲染但日志持续报错”的情况能被 CI 阻断。

## 回滚与灰度策略（强烈建议）

迁移中最怕“问题发现晚 + 回滚成本高”。建议在流程上预埋回滚点：

1. 以页面族为单位提交，单个提交可独立回滚。
2. 新旧实现并行保留 1 个短周期（例如 1 到 2 个迭代）。
3. 关键路径迁移后优先灰度给内部账号或测试环境。
4. 明确“立即回滚条件”：支付失败、崩溃率上升、核心埋点缺失。

## 团队协作建议（通用）

* 一次提交只做一类改动：迁移或重构二选一。
* 每次改动都要记录“迁移前后行为对照”和“回滚点”。
* 页面新增或调整后，及时更新团队调试文档与常用入口配置。

## 最终验收（Definition of Done）

当以下条件都成立，迁移可以视为完成：

* 核心页面已迁移到 `<script setup lang="ts">`，不再使用 `Page/Component` 原生构造器。
* 页面逻辑不依赖大面积 `setData`，状态更新路径可追踪。
* 常见空值崩溃点（数组/对象）有统一防御策略。
* 开发调试、构建产物、真机表现三者一致。
* 有最小 e2e 用例覆盖关键业务链路。

## 延伸阅读

* [Vue SFC：基础与组成](/wevu/vue-sfc/basics)
* [Vue SFC：配置与宏](/wevu/vue-sfc/config)
* [Vue SFC：模板与指令](/wevu/vue-sfc/template)
* [Vue SFC：调试与排错](/wevu/vue-sfc/troubleshoot)
* [运行时与生命周期](/wevu/runtime)

---

---
url: /wevu/vue-sfc/migrate-from-native.md
description: 本章节已迁移为独立迁移指南，不再归属到“Vue SFC 开发”子章节。
---

# 章节已迁移

本章节已迁移为独立迁移指南，不再归属到“Vue SFC 开发”子章节。

请访问新地址：

* [从原生小程序迁移到 Vue SFC（详细指南）](/wevu/migration/from-native-to-vue-sfc)

---

---
url: /community/showcase.md
description: 优秀案例展示，聚焦 community / showcase 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 优秀案例展示

## xiaomusic 小程序客户端

> 开源小程序音乐播放器，可控制小爱音箱播放本地/NAS音乐

![xiaomusic](/cases/0.jpeg)

`GitHub 地址`: https://github.com/F-loat/xiaoplayer

---

---
url: /guide/json-enhance.md
description: >-
  小程序项目里有很多结构相似的 json 配置（页面/组件/App）。Weapp-vite 在兼容原生 json/jsonc 的基础上，允许你用
  json.ts / json.js 生成最终配置，让配置也能享受模块化、类型提示和复用能力。
---

# 使用 TS/JS 生成 JSON

小程序项目里有很多结构相似的 `json` 配置（页面/组件/App）。`weapp-vite` 在兼容原生 `json/jsonc` 的基础上，允许你用 `json.ts` / `json.js` 生成最终配置，让配置也能享受模块化、类型提示和复用能力。

一个组件若名为 `custom`，框架会按以下优先级查找配置文件：`custom.jsonc` → `custom.json` → `custom.json.ts` → `custom.json.js`。因此你可以在需要时逐步升级为脚本驱动的配置。

## 为什么要用脚本生成 JSON？

* **复用与拆分**：直接 `import` 共享配置，避免复制粘贴。
* **类型安全**：借助 TypeScript 或 JSDoc 获得智能提示、错误提示。
* **动态拼装**：在同一文件中根据条件判断、合并配置，更易维护。

## 快速示例

下面示例展示了同一个组件的三种写法。`defineComponentJson` 只是为了提供类型提示，不会修改你传入的内容。

> 如果你使用的是 Vue SFC（`.vue`）并希望把配置写在 `<script setup>` 里（而不是单独写 `*.json.ts`），可以使用 `definePageJson / defineComponentJson` 等 build-time 宏，详见：[Vue SFC · Script Setup JSON 宏](/wevu/vue-sfc/config#script-setup-json-macros)。

::: code-group

```json [navigation-bar.json]
{
  "component": true,
  "styleIsolation": "apply-shared",
  "usingComponents": {}
}
```

```ts [navigation-bar.json.ts]
import { defineComponentJson } from 'weapp-vite/json'

export default defineComponentJson({
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
})
```

```js [navigation-bar.json.js]
import { defineComponentJson } from 'weapp-vite/json'

export default defineComponentJson({
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
})
```

:::

同理，你可以使用 `defineAppJson`、`definePageJson`、`defineSitemapJson`、`defineThemeJson` 等帮助函数（详见 `@/snippets/export-json.ts`）。

> \[!WARNING]
> 这些 `defineXXX` 函数只提供类型辅助，不会自动补齐字段。例如组件配置仍需显式写出 `"component": true`。

## 获得类型提示

`weapp-vite/json` 导出了多种类型定义，支持直接在 TypeScript 或 JSDoc 中使用。

::: code-group

```ts [navigation-bar.json.ts]
import type { Component } from 'weapp-vite/json'

export default <Component>{
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
}
```

```js [navigation-bar.json.js]
/**
 * @type {import('weapp-vite/json').Component}
 */
export default {
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
}
```

:::

更多导出类型可在 `@/snippets/export-json-type.ts` 中查看。

## 组合与复用配置

使用脚本后，可以像写普通模块一样组合配置、引入别名路径：

```ts
import type { Page } from 'weapp-vite/json'
import sharedTheme from '@/assets/shared.config'
import sharedLocal from './shared.json.ts'

export default <Page>{
  usingComponents: {
    't-button': 'tdesign-miniprogram/button/button',
    't-divider': 'tdesign-miniprogram/divider/divider',
    'ice-avatar': '@/avatar/avatar',
  },
  ...sharedTheme,
  ...sharedLocal,
}
```

* `@/assets/shared.config` 通过别名引入，Weapp-vite 会根据 `tsconfig.json` 的 `baseUrl` 和 `paths` 自动解析。
* 多个配置对象会被合并后再输出到最终的 `page.json`。

## 提示与最佳实践

* 优先使用 `jsonc`：需要简单注释时，`jsonc` 就足够；当出现跨模块复用、条件拼装时再升级到 `json.ts`。
* 保持纯函数：尽量让 `json.ts` 导出的对象保持幂等，避免引入与构建环境相关的副作用。
* 配合 `lint-staged`：如果团队使用格式化工具，记得把 `.json.ts`、`.json.js` 也纳入格式化与校验流程。

---

---
url: /deep/scan.md
description: >-
  当 Weapp-vite
  启动构建或监听时，会先确定哪些文件属于入口，然后递归分析它们之间的引用关系。理解这一流程有助于调试“页面没有被构建”“组件样式缺失”等问题。本页以文字和示意图梳理扫描逻辑，方便贡献者和高级用户参考。
---

# 依赖分析扫描流程

当 Weapp-vite 启动构建或监听时，会先确定哪些文件属于入口，然后递归分析它们之间的引用关系。理解这一流程有助于调试“页面没有被构建”“组件样式缺失”等问题。本页以文字和示意图梳理扫描逻辑，方便贡献者和高级用户参考。

## 入口类型判定

1. **应用入口（App）**
   * 默认查找 `app.json`（支持 `.json/.jsonc/.json.ts/.json.js`），并解析其中的 `pages`、`subPackages`、`usingComponents` 作为后续扫描起点。
   * 入口脚本优先解析 `app.ts/js`；若不存在则回退到 `app.vue`，并尝试从 `<json>` 提取配置。
2. **页面入口（Page）**
   * 由 `app.json.pages` / `subPackages.pages` 提供的路径决定（若路径无扩展名，会优先解析到 `.vue`，其次是 `.ts/.js`）。
   * 若同目录存在 `page.json` / `page.wxss` / `page.wxml` 会一并纳入构建；`.vue` 内的 `<json>` 也可作为页面配置来源。
3. **组件入口（Component）**
   * 来自 `usingComponents` / 自动导入 / `<script setup>` 自动注册。
   * 组件通常具备 `*.json` 且 `component: true`；缺失时可从 `.vue` 中的 `<json>` 提取。
4. **WXML 片段（Fragment）**
   * 通过 `import` / `include` 引入的 `.wxml` 文件。
   * 动态拼接路径不会被静态分析捕获，需保证模板能被固定路径引用或在构建阶段手动补充产物。

## 引用边与递归规则

* App → Page：来自 `app.json.pages`。
* App → Component：来自 `app.json.usingComponents`。
* App → SubPackage：来自 `app.json.subPackages`。（分包内再递归页面与组件。）
* Page → Component：来自页面 `json` 的 `usingComponents`。
* Component → 子组件：同样来自组件 `json` 的 `usingComponents`。

Weapp-vite 使用静态分析完成上述递归，因此运行时动态拼接的路径不会被自动识别。

```mermaid
---
title: weapp-vite 依赖扫描流程
---
flowchart TB
App -- pages --> Page
App -- usingComponents --> Component
App -- subPackages --> SubPackage
SubPackage -- pages --> Page
Page -- usingComponents --> Component
Component -- usingComponents --> Component
```

## 调试建议

* **确认入口是否完整**：缺少 `.json` 或 `json.component === true` 会导致节点被跳过。
* **关注静态路径**：尽量避免在运行时拼接 `import` 路径；若必须使用，建议提供固定入口或自定义构建脚本补充产物。
* **结合 `weapp.debug`**：使用 [`watchFiles`、`resolveId`](/config/shared.md#weapp-debug) 查看是否扫描到对应文件，快速定位异常。

---

---
url: /guide/chunks.md
description: weapp.chunks 用于控制 **复用模块的输出位置和形态**，常用于分包优化、避免不必要的 common.js、或减少重复体积。
---

# 共享 Chunk 策略（weapp.chunks）

`weapp.chunks` 用于控制 **复用模块的输出位置和形态**，常用于分包优化、避免不必要的 `common.js`、或减少重复体积。

可以把它看作两层策略：

* **sharedStrategy**：共享模块“落在哪里”（主包 vs 分包）。
* **sharedMode**：共享模块“长什么样”（common.js / 按路径 / 内联）。

## 基础示例

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

export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'common',
      dynamicImports: 'preserve',
      logOptimization: true,
    },
  },
})
```

## sharedStrategy：共享模块落盘策略

* `duplicate`（默认）：跨分包共享模块复制到各自分包，避免分包首开时回主包取依赖。
* `hoist`：共享模块统一提到主包，减少重复体积。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'hoist',
    },
  },
})
```

## sharedMode：共享模块输出形态

### 1) common（默认）

共享模块会汇总为 `common.js`，入口会自动改写引用该文件。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'common',
    },
  },
})
```

### 2) path（按源码路径输出）

共享模块按源码相对路径输出，避免 `common.js`，同时保持路径稳定。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'path',
      sharedPathRoot: 'src',
    },
  },
})
```

### 3) inline（禁用共享 chunk）

复用模块会被内联到引用方，完全不生成共享 chunk。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'inline',
    },
  },
})
```

## sharedOverrides：针对模块覆盖输出形态

你可以为特定目录或模块设置不同的 `sharedMode`：

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'common',
      sharedOverrides: [
        { test: 'components/**', mode: 'path' },
        { test: /legacy\//, mode: 'inline' },
      ],
    },
  },
})
```

* `test` 支持 glob 字符串或正则表达式
* 匹配基于 `srcRoot` 相对路径或绝对路径

## sharedPathRoot：路径型共享输出的根目录

当 `sharedMode = 'path'` 时，`sharedPathRoot` 用于计算输出路径的根目录（相对 `cwd`）。

* 未设置时默认使用 `srcRoot`
* 若设置的目录不在 `srcRoot` 内，构建会自动回退到 `srcRoot`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'path',
      sharedPathRoot: 'src/shared',
    },
  },
})
```

## dynamicImports：动态 import 的处理方式

* `preserve`（默认）：保留独立的动态 chunk。
* `inline`：尽量内联动态 import，减少额外 chunk。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      dynamicImports: 'inline',
    },
  },
})
```

## forceDuplicatePatterns：强制复制共享模块

当共享模块的直接导入方命中这些规则时，即使主包也引用该模块，仍会按 `duplicate` 策略复制到分包：

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      forceDuplicatePatterns: ['action/**', /services\//],
    },
  },
})
```

## duplicateWarningBytes：冗余体积告警

当共享模块复制后的冗余体积超过阈值时输出警告：

```ts
export default defineConfig({
  weapp: {
    chunks: {
      duplicateWarningBytes: 768 * 1024,
    },
  },
})
```

设置为 `0` 或 `undefined` 可关闭提醒。

## logOptimization：输出优化日志

启用后会在构建日志中输出共享模块的复制/回退信息，便于确认策略是否生效。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      logOptimization: true,
    },
  },
})
```

## 组合示例：禁用 common.js 并保持路径

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'path',
      sharedPathRoot: 'src',
      dynamicImports: 'preserve',
    },
  },
})
```

这样会避免生成 `common.js`，同时让共享模块保持与源码一致的相对路径。

---

---
url: /config/shared.md
description: 除了 WXML/WXS 这些“底层开关”，Weapp-vite 还有一些通用增强能力，比如自动路由、调试钩子等。本页主要讲：
---

# 共享配置 {#shared-config}

除了 WXML/WXS 这些“底层开关”，`weapp-vite` 还有一些通用增强能力，比如自动路由、调试钩子等。本页主要讲：

* `weapp.autoRoutes`：生成路由清单与类型，供 `app.json.ts` 或业务代码使用
* `weapp.debug`：遇到“为什么没扫描到 / 为什么没输出”时怎么定位
* `weapp.logger`：控制 CLI / 构建日志级别与标签输出
* `weapp.injectWeapi`：在运行时注入 `@wevu/api` 的 `wpi` 实例
* `weapp.mcp`：AI 协作时的 MCP 服务开关与监听配置

组件自动导入已经拆到 [自动导入组件配置](/config/auto-import-components.md) 单独说明。

\[\[toc]]

## `weapp.autoRoutes` {#weapp-autoroutes}

* **类型**：`boolean | { enabled?: boolean; typedRouter?: boolean; include?: string | RegExp | Array<string | RegExp>; persistentCache?: boolean | string; watch?: boolean }`
* **默认值**：`false`
* **适用场景**：
  * 希望从目录结构自动生成 `pages` 清单，不再手动维护 `app.json.pages`。
  * 希望在 TypeScript 里拿到“页面路径”的类型提示，避免字符串拼错。

### 配置示例

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

export default defineConfig({
  weapp: {
    autoRoutes: {
      enabled: true,
      typedRouter: true,
      include: ['pages/**'],
      persistentCache: false,
      watch: true,
    },
  },
})
```

如果只是快速启用，也可以直接写：

```ts
export default defineConfig({
  weapp: {
    autoRoutes: true,
  },
})
```

开启后 Weapp-vite 会：

* 持续扫描主包和分包下的页面目录，维护 `routes`、`entries`、`pages`、`subPackages` 等清单；
* 在配置文件同级输出 `typed-router.d.ts`，提供 `AutoRoutes` 等类型；
* 自动暴露虚拟模块 `weapp-vite/auto-routes`，支持在代码中直接导入最新的路由数据。

字段说明：

* `enabled`：总开关；设为 `false` 时完全关闭自动路由。
* `typedRouter`：是否输出 `typed-router.d.ts`。
* `include`：自动路由扫描规则。支持单个 glob、正则或它们的数组；默认是主包 `pages/**`，并额外包含已声明分包 root 下的 `pages/**`。
* `persistentCache`：是否启用持久化缓存；传 `true` 时使用默认 `.weapp-vite/auto-routes.cache.json`，传字符串时表示自定义缓存文件路径，默认关闭。
* `watch`：开发模式下是否监听页面目录变化并实时刷新路由清单。

> \[!NOTE]
> 自动路由默认扫描 `srcRoot/pages/**`，以及已声明分包 root 下的 `pages/**`。它不会把任意 `**/pages/**` 都当作页面目录；如果目录结构不同，可以通过 `include` 自定义 glob / 正则规则。分包页面若不再使用 `root/pages/**` 约定，建议同时声明 `weapp.subPackages`，这样 `autoRoutes` 才能稳定推断 `subPackages` 输出。

> \[!TIP]
> 如果你在 `src/subpackages/foo/pages/**`、`src/packageA/pages/**` 这类目录下放页面，但没有在 `weapp.subPackages` 中声明对应 root，那么这些页面在默认规则下不会被自动收集。要么补 `weapp.subPackages`，要么显式配置 `autoRoutes.include`。

## `weapp.debug` {#weapp-debug}

* **类型**：
  ```ts
  {
    watchFiles?: (files: string[], meta?: SubPackageMetaValue) => void
    resolveId?: (id: string, meta?: SubPackageMetaValue) => void
    load?: (id: string, meta?: SubPackageMetaValue) => void
    inspect?: WrapPluginOptions
  }
  ```
* **适用场景**：排查“监听了哪些文件”“模块是怎么解析的”“某个文件有没有走到预期插件”“产物为什么没生成”等问题。

### 调试示例

```ts
export default defineConfig({
  weapp: {
    debug: {
      watchFiles(files, meta) {
        const scope = meta?.subPackage.root ?? 'main'
        console.info(`[watch:${scope}]`, files)
      },
      resolveId(id) {
        if (id.includes('lodash')) {
          console.log('[resolveId]', id)
        }
      },
      load(id) {
        if (id.endsWith('.wxml')) {
          console.log('[load wxml]', id)
        }
      },
      inspect: { hooks: 'all', threshold: 16 },
    },
  },
})
```

* `watchFiles`: 构建结束时返回监听到的文件，可区分主包与分包。
* `resolveId`: 追踪模块解析路径，适合定位别名、入口解析或分包引用问题。
* `load`: 监听模块加载，常用于确认模板、脚本等是否经过预期的转换。
* `inspect`: 基于 `vite-plugin-performance` 的 `wrapPlugin` 能力，记录插件钩子的耗时与调用情况（默认输出到控制台）。

### 常见调试技巧

1. **确认分包有没有参与构建**：用 `watchFiles` 看看独立分包的 `miniprogram_npm` 是否生成、文件是否被监听到。
2. **定位构建卡顿**：在 `resolveId` / `load` 里打时间戳，快速找出慢的模块或目录。
3. **排查组件自动导入**：组件没被识别时，先确认 `.json` 是否包含 `component: true`，再看 `autoImportComponents.globs` 是否命中。

## `weapp.logger` {#weapp-logger}

* **类型**：`LoggerConfig`
* **作用**：透传给 `@weapp-core/logger`，统一控制 `weapp-vite` CLI、构建器和分析命令的日志输出。

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

export default defineConfig({
  weapp: {
    logger: {
      level: 'info',
      tags: {
        build: true,
        mcp: false,
      },
    },
  },
})
```

适用场景：

* CI 中希望减少冗余日志，只保留警告/错误。
* 本地调试时希望只打开构建、分析或特定子系统的日志标签。

> \[!TIP]
> 字段细节以 `@weapp-core/logger` 的类型提示为准；`weapp-vite` 这里只做透传，不额外扩展私有字段。

## `weapp.injectWeapi` {#weapp-injectweapi}

* **类型**：`boolean | { enabled?: boolean; replaceWx?: boolean; globalName?: string }`
* **默认值**：`{ enabled: false, replaceWx: false, globalName: 'wpi' }`
* **作用**：在 App 入口注入 `@wevu/api` 导出的 `wpi` 实例；可选地把全局 `wx` / `my` / 当前平台对象代理到该实例上。

### 配置示例

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

export default defineConfig({
  weapp: {
    injectWeapi: {
      enabled: true,
      replaceWx: false,
      globalName: 'wpi',
    },
  },
})
```

### 字段说明

1. `enabled`：是否启用 `wpi` 注入。
2. `replaceWx`：是否把源码中的 `wx` / `my` / 当前平台全局对象访问重写到注入实例。
3. `globalName`：挂到全局对象上的变量名，默认是 `wpi`。

### 使用建议

* 仅想在运行时全局暴露 `wpi`，但不改动现有 `wx.xxx` 调用：`enabled: true, replaceWx: false`。
* 想统一走 `@wevu/api` 的适配层：再开启 `replaceWx: true`。
* 若项目未安装 `@wevu/api`，构建时会跳过注入并给出告警。

## `weapp.mcp` {#weapp-mcp}

* **类型**：`boolean | { enabled?: boolean; autoStart?: boolean; host?: string; port?: number; endpoint?: string }`
* **默认值**：`{ enabled: true, autoStart: false, host: '127.0.0.1', port: 3088, endpoint: '/mcp' }`
* **适用场景**：
  * 需要让 AI 助手直接读取仓库源码与文档。
  * 希望在本地开发时按需自动拉起 MCP HTTP 服务。

### 配置示例

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

export default defineConfig({
  weapp: {
    mcp: {
      enabled: true,
      autoStart: true,
      host: '127.0.0.1',
      port: 3088,
      endpoint: '/mcp',
    },
  },
})
```

关闭自动启动（保留手动 `weapp-vite mcp`）：

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

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

完全关闭 MCP：

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

export default defineConfig({
  weapp: {
    mcp: false,
  },
})
```

### 字段说明

1. `enabled`: 是否启用 MCP 能力。
2. `autoStart`: 是否在 `weapp-vite` 原生命令执行时自动启动 MCP HTTP 服务。
3. `host/port/endpoint`: 自动启动时的监听地址配置。

> \[!TIP]
> 完整接入流程、客户端配置与测试建议请看：[AI 协作指南](/guide/ai)。

## `weapp.wevu.defaults` {#weapp-wevu-defaults}

* **类型**：`WevuDefaults`
* **作用**：在编译 `app.vue` 时自动注入 `setWevuDefaults()`，统一控制 Wevu 的 `createApp/defineComponent` 默认值。
* **适用场景**：
  * 希望全局配置 `setData` 策略（例如 `includeComputed` / `strategy`）。
  * 希望统一小程序 `Component` 选项默认值（例如 `options.addGlobalClass`）。

### 配置示例

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

export default defineConfig({
  weapp: {
    wevu: {
      defaults: {
        app: {
          setData: {
            includeComputed: false,
            strategy: 'patch',
          },
        },
        component: {
          options: {
            addGlobalClass: true,
          },
          setData: {
            strategy: 'patch',
          },
        },
      },
    },
  },
})
```

### 注意事项

* 仅对 `app.vue` 生效：Weapp-vite 会在编译产物中插入 `setWevuDefaults()`，并确保它在 `createApp()` 之前执行。
* 配置必须可序列化（JSON 兼容）：不支持函数、`Symbol`、循环引用。
* 局部显式配置会覆盖默认值；`setData` 与 `options` 会做浅合并，其余字段按对象顶层合并。
* 若你希望手动控制时机，可以在 `app.vue` 顶层显式调用 `setWevuDefaults()`，并关闭此配置以避免重复注入。
* 当 `app.vue`/组件导出为对象字面量时，Weapp-vite 会把默认值直接合并进编译产物，方便排查与调试；若导出是变量或函数，仍会回落到运行时合并。
* 若设置了 `component.options.virtualHost = true`，Weapp-vite 会在 **页面** 入口自动补上 `virtualHost: false`，避免页面虚拟节点导致的渲染层错误；需要为页面开启时请在页面内显式配置。

> \[!TIP]
> 如果你不通过 Weapp-vite 构建，也可以在运行时手动调用 `setWevuDefaults()`（见 `/wevu/runtime`）。

## `weapp.wevu.preset` {#weapp-wevu-preset}

* **类型**：`'performance'`
* **默认值**：`undefined`
* **作用**：一键启用性能向默认项，降低 setData 快照与后台态更新带来的开销。

### 配置示例

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

export default defineConfig({
  weapp: {
    wevu: {
      preset: 'performance',
    },
  },
})
```

### `performance` 预设内容

* 为 `app/component` 注入 `setData.strategy: 'patch'`。
* 为 `app/component` 注入 `setData.suspendWhenHidden: true`。
* 为 `app/component` 注入开发态高频告警：`setData.highFrequencyWarning = { enabled: true, devOnly: true }`。
* 默认启用 `autoSetDataPick`（若你显式设置 `autoSetDataPick: false`，则以显式配置为准）。

### 覆盖规则

* 预设先应用，再与 `weapp.wevu.defaults` 做浅合并（`setData/options` 仍按字段浅合并）。
* 你在 `weapp.wevu.defaults` 中写的同名字段，优先级高于预设默认值。

## `weapp.wevu.autoSetDataPick` {#weapp-wevu-auto-setdata-pick}

* **类型**：`boolean`
* **默认值**：`false`
* **作用**：在编译阶段从模板表达式自动提取渲染相关顶层 key，并注入到组件/页面的 `setData.pick`，减少非渲染字段参与快照与下发。

> \[!IMPORTANT]
> 该能力默认关闭，不会在未配置时自动开启。只有显式设置 `weapp.wevu.autoSetDataPick: true` 才会生效。
> 从旧版本升级到新版本时，若你未手动开启该项，行为保持不变。
> 如果启用了 `weapp.wevu.preset: 'performance'`，则会默认开启该项（仍可通过显式 `false` 覆盖）。

### 配置示例

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

export default defineConfig({
  weapp: {
    wevu: {
      autoSetDataPick: true,
    },
  },
})
```

### 行为说明

* 仅对 `defineComponent/createWevuComponent` 产物生效；`app.vue` 不会注入。
* 若组件已显式声明 `setData.pick` 数组，会与自动推导结果做去重合并。
* 若 `setData` 为变量或表达式（例如 `setData: externalConfig`），会包裹为 `{ pick: [...], ...externalConfig }` 以保持兼容。
* 建议在“状态很大但模板只使用少量字段”的页面优先开启；若模板几乎使用全部字段，收益通常不明显。

### FAQ

#### Q: `autoSetDataPick` 默认会自动开启吗？

不会。默认值是 `false`，只有显式配置 `weapp.wevu.autoSetDataPick: true` 才会生效。

#### Q: 为什么我在 `app.vue` 里看不到注入结果？

这是预期行为。该能力仅对 `defineComponent/createWevuComponent` 产物生效，不会对 `app.vue` 注入 `setData.pick`。

#### Q: 我已经手写了 `setData.pick`，会被覆盖吗？

不会。自动推导结果会与已有 `setData.pick` 做去重合并，不会丢掉你手写的 key。

#### Q: 怎么快速确认它是否生效？

先执行一次构建，然后检查页面/组件产物 JS 中是否出现 `setData.pick`。若模板含调用表达式，通常也会看到 `__wv_bind_*` 被写入 `pick` 数组。

## `weapp.hmr.sharedChunks` {#weapp-hmr-sharedchunks}

* **类型**：`'full' | 'auto' | 'off'`
* **默认值**：`'auto'`
* **适用场景**：开发态 HMR 时控制共享 chunk 的重建策略。

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

export default defineConfig({
  weapp: {
    hmr: {
      sharedChunks: 'auto',
    },
  },
})
```

* `full`: 每次更新都重新产出全部 entry（最稳、最慢）。
* `auto`: 只在共享 chunk 可能被覆盖时回退 full（折中）。
* `off`: 仅更新变更 entry（最快，但可能导致共享 chunk 导出不一致）。

## `weapp.hmr.touchAppWxss` {#weapp-hmr-touchappwxss}

* **类型**：`boolean | 'auto'`
* **默认值**：`'auto'`
* **适用场景**：开发态构建结束后，额外触碰 `app.wxss`，触发微信开发者工具的热重载。

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

export default defineConfig({
  weapp: {
    hmr: {
      touchAppWxss: 'auto',
    },
  },
})
```

* `true`: 总是启用。
* `false`: 关闭。
* `auto`: 检测到安装 `weapp-tailwindcss` 时启用。

## `weapp.chunks` {#weapp-chunks}

* **类型**：`ChunksConfig`
* **适用场景**：控制跨分包共享代码如何输出，降低重复体积或减少主包依赖。

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

export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'common',
      sharedOverrides: [{ test: 'components/**', mode: 'path' }],
      sharedPathRoot: 'src',
      dynamicImports: 'preserve',
      logOptimization: true,
      forceDuplicatePatterns: ['components/**', /legacy\//],
      duplicateWarningBytes: 512 * 1024,
    },
  },
})
```

字段说明：

* `sharedStrategy`: `duplicate`（默认）复制到各分包，或 `hoist` 提到主包。
* `sharedMode`: `common`（默认）输出 `common.js`，`path` 按源码路径输出，`inline` 内联到引用方。
* `sharedOverrides`: 针对特定模块覆盖 `sharedMode` 的规则数组（`test` 支持字符串或正则）。
* `sharedPathRoot`: `sharedMode: 'path'` 时用于计算输出路径的根目录（相对 `cwd`）。
* `dynamicImports`: `preserve`（默认）保留动态 chunk，`inline` 尝试内联动态 import。
* `logOptimization`: 输出分包优化日志，帮助确认复制/回退位置。
* `forceDuplicatePatterns`: 强制按分包复制的模块匹配规则（字符串或正则）。
* `duplicateWarningBytes`: 冗余体积超过阈值时发出警告；设置为 `0` 关闭。

详细用法与示例请参考：[共享 Chunk 策略](/guide/chunks)。

## 关联阅读

* [WXML 配置](/config/wxml.md)：了解模板增强与组件扫描的协作方式。
* [WXS 配置](/config/wxs.md)：掌握脚本增强开关与调试方法。
* [npm 配置](/config/npm.md)：在调试过程中同时控制 npm 构建策略。

---

---
url: /packages/weapi/gap-notes.md
description: '@wevu/api 兼容报告中的特殊命名、类型来源差异与 gap 说明。'
---

# 兼容差异说明

本页解释兼容报告中一些容易误读的地方，例如 typings 差异、命名例外和 unsupported 的含义。

# 05 兼容差异说明

## 说明范围

本文件记录“类型来源差异”与“命名对齐特殊点”，用于解释为何某些 API 在报告里显示不兼容。

## 关键差异

* 核心差异映射中存在不在微信方法清单的条目：
  * `saveFile`

* 报告中的 `fallback` 表示方法可调用但仅通过通用兜底目标适配，语义可能与微信不一致。

* 抖音 typings 中缺失 `showActionSheet`（但映射规则保留该能力），因此在类型清单统计中视为不支持。

* 报告中的“不支持”表示：按当前 typings 清单与映射规则，`wpi.<wxMethod>` 在该平台找不到可调用目标方法；运行时仍可能因宿主扩展而可用。

## 后续建议

1. 若需继续提升覆盖率，优先补充“同能力异名 API”映射（按业务优先级增量添加）。
2. 持续维护 `strict-alias:check` 与 `coverage:check` 门禁阈值；如发生有意变更，请同步更新阈值与报告。

---

---
url: /wevu/compatibility.md
description: 本页用于快速排雷：哪些能力能用、有哪些限制来自小程序环境，以及哪些点最容易踩坑。
---

# 兼容性与注意事项

本页用于快速排雷：哪些能力能用、有哪些限制来自小程序环境，以及哪些点最容易踩坑。

* **运行环境**：Wevu 依赖 `Proxy` / `WeakMap` / `Symbol` 等能力，建议微信小程序基础库 ≥ 3.0.0；模板/样式/配置通常配合 Weapp-vite 构建产物使用。
* **Router 基础库门槛**：`this.router / this.pageRouter` 原生能力从基础库 `2.16.1+` 可用；`useRouter()/usePageRouter()` 在低版本会自动回退到全局 `wx/my/tt` 路由方法。若需要跨版本路径基准稳定，优先绝对路径或优先 `usePageRouter()`。
* **无 DOM/浏览器 API**：不要使用 `window`/`document`，请使用小程序原生能力（如 `wx.request`）。
* **defineComponent 的前提**：`defineComponent()` 会直接调用全局 `Component()`，请确保代码在小程序运行时执行（或测试环境自行 stub）。
* **createApp 的行为**：`createApp()` 只会在检测到全局 `App()` 时自动注册；否则仅返回运行时对象，适用于测试或自定义适配。
* **生命周期钩子约束**：所有钩子必须在 `setup()` 同步阶段调用；分享/收藏/退出状态等“返回值型钩子”为单实例（后注册覆盖先注册）。
* **页面事件按需派发**：如 `onPageScroll`/分享/朋友圈/收藏等，只有定义了对应页面方法才会触发；Wevu 也仅在你定义了这些页面方法时桥接 `setup()` 中注册的同名 hooks。
* **Vue 别名的差异**：`onBeforeMount/onBeforeUnmount` 在 `setup()` 同步阶段立即执行；`onBeforeUpdate/onUpdated` 会在每次 `setData` 前/后触发（用于补齐“小程序缺少更新生命周期”的语义）。
* **Provide/Inject 的限制**：当前版本没有组件树父子指针，`inject()` 不会向上查找祖先组件；组件内只会命中“当前实例提供的值”，否则回落到全局存储。
* **watch 深度策略**：`deep` 默认采用“版本信号”策略（不做深层遍历），可通过 `setDeepWatchStrategy('traverse')` 切换为遍历策略。
* **setData diff 规则**：缺失字段与 `undefined` 会被归一化为 `null`；运行时只下发 state + computed 的差量路径；`setData()` 返回 Promise 时会吞掉 reject 以避免阻塞更新链路。
* **组件与模板规则**：小程序组件必须声明 `usingComponents`（可写在 `<json>`，也可用 Script Setup JSON 宏注入）；`@tap`、`v-if`、`v-for` 等语法由编译侧（如 Weapp-vite）转换为 WXML。
* **样式**：输出为 `wxss`；即使使用 SFC 的 `scoped`，仍需遵守小程序样式能力与选择器限制。

---

---
url: /guide/subpackage.md
description: 微信小程序的分包机制在 Weapp-vite 中得到完整支持。本页帮你快速搞清楚两件事：
---

# 分包指南

微信小程序的分包机制在 `weapp-vite` 中得到完整支持。本页帮你快速搞清楚两件事：

* **普通分包 vs 独立分包** 有什么区别（哪些能互相引用、哪些不能）
* **Weapp-vite 会怎么分发产物**（共享代码/依赖/样式会落到哪里）

如果你需要原理级配置（`weapp.subPackages`、`weapp.chunks` 等），请继续阅读 [配置文档 · 分包配置](/config/subpackages.md) 与 [配置文档 · Worker 配置](/config/worker.md)。

先记住 3 句话：

* **只想开启分包**：直接沿用官方 `app.json.subPackages` 写法即可，Weapp-vite 会识别并按分包输出。
* **想共享主题/基础样式**：用 [`weapp.subPackages[].styles`](/config/subpackages.md#subpackages-styles) 交给构建器注入，别手写一堆相对路径 `@import`。
* **想控制共享代码怎么落盘**：关注 `weapp.chunks.sharedStrategy`（`duplicate` vs `hoist`）。

官方说明可参考：[分包加载 - 微信官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages.html)。以下内容聚焦于 `weapp-vite` 的行为和调优手段。

::: tip 分包配置入口
通过 [`weapp.subPackages`](/config/subpackages.md#weapp-subpackages) 可以为每个 `root` 单独开启独立编译、注入 `inlineConfig`、覆盖自动组件导入和共享样式。若还要控制 npm 依赖落位，请配合 [`weapp.npm.subPackages`](/config/npm.md#主包--分包依赖落位) 使用。
:::

> \[!NOTE]
> 文档里提到的 **Rolldown** 是 `weapp-vite` 内置的打包器：语法与 Vite/Rollup 插件体系兼容，但针对小程序做了额外的“分包产物分发”优化。可以把它看作「为小程序量身定制的 Rollup」；同一个 Rolldown 上下文意味着编译出的模块、样式和资源可以互相复用。

先看总览模型：

```mermaid
flowchart LR
  SRC[源码模块] --> NORMAL[普通分包: 同一构建上下文]
  SRC --> IND[独立分包: 隔离构建上下文]
  NORMAL --> CH[可用 sharedStrategy 做共享优化]
  IND --> ISO[不与主包/其它分包共享 JS 产物]
```

## 普通分包

普通分包会被视为和整个 `app` 是一个整体：主包 + 所有普通分包在**同一个 Rolldown 上下文**里构建，因此“共享/复制模块”这类优化是可行的。

微信运行时的限制（简化版）：

* `packageA` 不能直接 `require` `packageB` 的 JS，但可以引用主包与自身分包内的 JS。（使用“分包异步化”时此限制会放宽）
* `packageA` 不能引用 `packageB` 的模板（WXML），但可以引用主包与自身分包内的模板。
* `packageA` 不能直接使用 `packageB` 的静态资源，但可以使用主包与自身分包内的资源。

### 代码产物的位置（核心 4 条）

1. 模块只被一个分包引用：产物只在该分包内。
2. 模块被多个分包引用且主包不引用：由 `sharedStrategy` 决定落位。
3. 模块被主包和任一分包同时引用：统一进入主包 `common.js`。
4. 分包 A 不能直接引用分包 B 的源码：需先抽到主包或公共目录。

```mermaid
flowchart TD
  S[识别模块引用方] --> M{主包是否引用?}
  M -->|是| R[落到主包 common.js]
  M -->|否| N{是否被多个分包引用?}
  N -->|否| P[落到单分包产物]
  N -->|是| C[按 sharedStrategy 分发]
```

### sharedStrategy = duplicate（默认）

适合“分包首开优先”。跨分包共享模块会复制到各分包共享产物，避免回主包拉取。

```mermaid
flowchart LR
  A[subpackage A page] --> U[共享模块 util 或 npm]
  B[subpackage B page] --> U
  U --> SA[A/__shared__/common.js]
  U --> SB[B/__shared__/common.js]
```

### sharedStrategy = hoist

适合“减少重复代码优先”。跨分包共享模块统一提升到主包 `common.js`。

```mermaid
flowchart LR
  A[subpackage A page] --> U[共享模块 util 或 npm]
  B[subpackage B page] --> U
  U --> R[main/common.js]
```

### 何时选 duplicate / hoist

```mermaid
flowchart TD
  T[确定优化目标] --> Q{更在意什么?}
  Q -->|分包首开速度| D[选 duplicate]
  Q -->|包体去重与统一管理| H[选 hoist]
```

### 精细化参数（按需开启）

* `forceDuplicatePatterns`：当导入图里出现“伪主包引用”时，强制某些目录仍按分包复制。
* `duplicateWarningBytes`：给 `duplicate` 的冗余体积设置告警阈值。

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

export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate', // 或 'hoist'
      // forceDuplicatePatterns: ['action/**'],
      // duplicateWarningBytes: 768 * 1024,
    },
  },
})
```

## 独立分包

独立分包和整个 `app` 是隔离的：它们会在**不同的 Rolldown 上下文**里构建，因此不会和主包/其他分包共享复用的 JS 代码。

```mermaid
flowchart LR
  MAIN[主包 + 普通分包] --> MCTX[上下文 A]
  IND[独立分包] --> ICTX[上下文 B]
  MCTX -. 不共享 JS 产物 .-> ICTX
```

* **独立分包不能依赖主包和其他分包的内容**，包括 JS、模板、WXSS、自定义组件、插件等。（使用“分包异步化”时，JS/自定义组件/插件会放宽）
* 主包的 `app.wxss` 对独立分包无效：不要依赖主包全局样式。
* `App` 只能在主包里定义：独立分包里不要定义 `App()`，否则行为不可预期。
* 独立分包中暂时不支持使用插件。

### 单独开发某个分包（把它当成独立分包）

当你想“只专注开发某个分包”（例如一个业务域由独立小组交付、或希望尽量隔离主包依赖）时，推荐把该分包按 **独立分包** 的方式组织与编译：运行时隔离、构建时独立上下文、依赖/样式/组件策略也能只对这个分包生效。

1. 在 `app.json` 里把目标分包标记为 `independent: true`（并确保分包 `pages` 指向你要调试的页面）：

```jsonc
// src/app.json
{
  "pages": ["pages/index/index"],
  "subPackages": [
    {
      "root": "packages/order",
      "pages": ["pages/index", "pages/detail"],
      "independent": true,
      // 可选：分包级入口（基于 root 的相对路径），用于放分包初始化逻辑
      "entry": "index.ts"
    }
  ]
}
```

2. 在 `vite.config.ts` 里为该 `root` 配置 `weapp.subPackages`（关键是 `independent`，其余按需）：

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

export default defineConfig({
  weapp: {
    subPackages: {
      'packages/order': {
        independent: true,
        inlineConfig: {
          // 在这里添加独立分包的大包配置
          define: {
            'import.meta.env.ORDER_DEV': JSON.stringify(true),
          },
        },
      },
    },
  },
})
```

> \[!TIP]
> 如果你不想把“独立分包开发”的配置长期留在主配置里，可以单独新建一个 `vite.config.order.ts`，再用 `weapp-vite dev -c vite.config.order.ts` 运行；生产构建仍用默认的 `vite.config.ts`。

## 分包样式共享

[`weapp.subPackages[].styles`](/config/subpackages.md#subpackages-styles) 能把重复的 `@import` 交还给构建器处理：声明一次主题、设计令牌或基础布局，普通分包与独立分包都会在生成样式时自动插入对应的共享入口。

```mermaid
flowchart LR
  STYLES[styles 配置] --> NORMAL[普通分包]
  STYLES --> IND[独立分包]
  NORMAL --> NINJ[复用样式产物并注入 @import]
  IND --> IINJ[在独立上下文编译并注入 @import]
```

> \[!TIP]
> 分包根目录下若存在 `index.*` / `pages.*` / `components.*`（默认扫描 `.wxss`/`.css`），Weapp-vite 会自动识别它们作为共享入口，零配置即可复用。

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

export default defineConfig({
  weapp: {
    subPackages: {
      'packages/member': {
        // 普通分包：共享主题变量和页面级样式
        styles: [
          'styles/tokens.css',
          { source: 'styles/layout.wxss', scope: 'pages' },
        ],
      },
      'packages/offline': {
        independent: true,
        // 独立分包：会在独立上下文重新编译并注入 @import
        styles: [
          {
            source: 'styles/offline-theme.scss',
            include: ['pages/**/*.wxss', 'components/**/*.wxss'],
          },
        ],
      },
    },
  },
})
```

* 普通分包与主包共享 Rolldown 上下文，样式产物只生成一次，并在分包页面/组件头部自动注入 `@import`。
* 独立分包会在专属上下文重新编译同一份源文件，保持样式同步且无需手动维护相对路径。
* `scope` / `include` / `exclude` 可精准控制注入范围，配合 HMR 调试体验与主包一致。

更多细节（如产物位置与对象写法）可查看[配置文档 · 样式共享实战](/config/subpackages.md#subpackages-styles)。

### 调试建议

1. 确认 `app.json` 中的 `independent: true` 是否与 `vite.config.ts` 中的 `weapp.subPackages` 保持一致。
2. 利用 `weapp.debug.watchFiles` 查看产物位置，确认独立分包是否生成独立的 `miniprogram_npm`。
3. 如果分包引用到了主包路径，构建会报错提示，请及时调整引用方式或拆分公共模块。

### 分析产物布局

快速核对“源码最终落在主包 / 分包 / 共享 chunk”的最短路径：

```json
{
  "scripts": {
    "analyze": "weapp-vite analyze"
  }
}
```

然后执行：

```bash
pnpm run analyze
```

默认会输出人类可读摘要。需要对接 CI 或自定义检查时，用 JSON 模式：

```bash
pnpm run analyze -- --json --output report/analyze.json
```

输出文件会包含主包、分包、共享 chunk 与源码映射，便于做体积预警和规则校验。

## 常见问题

* **本地运行时报路径错误？** 检查页面是否引用了其他分包的资源，或在 `weapp.chunks` 中启用了与你项目不符的策略。
* **产物体积过大？** 使用 `weapp.npm.mainPackage.dependencies` 与 `weapp.npm.subPackages.<root>.dependencies` 精确声明主包/分包 npm 依赖落位。
* **想在分包中调试 Worker？** 记得同时在 `weapp.worker` 中声明入口，并确保 Worker 文件位于对应分包目录。

---

---
url: /config/subpackages.md
description: >-
  Weapp-vite 会读取 app.json.subPackages 来生成分包产物；weapp.subPackages 则用于
  **构建期补充配置**（独立分包、依赖裁剪、共享样式等）。
---

# 分包配置 {#subpackages-config}

`weapp-vite` 会读取 `app.json.subPackages` 来生成分包产物；`weapp.subPackages` 则用于 **构建期补充配置**（独立分包、`inlineConfig`、自动导入组件覆盖、共享样式等）。
`weapp.subPackages` 本身不再负责 npm 依赖裁剪；这部分能力已收敛到 [`weapp.npm.mainPackage` / `weapp.npm.subPackages`](/config/npm.md#主包--分包依赖落位)。

\[\[toc]]

## `weapp.subPackages` {#weapp-subpackages}

* **类型**：
  ```ts
  Record<string, {
    independent?: boolean
    inlineConfig?: Partial<InlineConfig>
    autoImportComponents?: AutoImportComponents | false
    watchSharedStyles?: boolean
    styles?: SubPackageStyleConfigEntry | SubPackageStyleConfigEntry[]
  }>
  ```
* **默认值**：`undefined`

示例：

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

export default defineConfig({
  weapp: {
    subPackages: {
      marketing: {
        independent: true,
        autoImportComponents: false,
        styles: [
          'styles/shared.wxss',
          { source: 'styles/pages.wxss', scope: 'pages' },
        ],
      },
    },
  },
})
```

### 字段说明

* `independent`：启用 **独立分包构建上下文**。常与 `app.json` 中的 `independent: true` 搭配使用。
* `inlineConfig`：为该分包注入额外 Vite 配置（Rolldown/Rollup 插件、define 等）。
* `autoImportComponents`：为该分包单独配置/禁用自动导入。
* `watchSharedStyles`：分包文件变更时是否强制重新生成共享样式（默认 `true`）。
* `styles`：分包共享样式入口，详见下文。

> \[!NOTE]
> `weapp.subPackages` 的 key 必须与 `app.json.subPackages[].root` 对应，否则不会生效。

> \[!TIP]
> 若你想控制某个分包的 npm 依赖落位，请到 [npm 配置](/config/npm.md) 使用 `weapp.npm.subPackages.<root>.dependencies`，而不是写在 `weapp.subPackages` 里。

> \[!TIP]
> 当你开启 `weapp.autoRoutes` 时，`weapp.subPackages` 还有另一层作用：它会告诉自动路由“哪些 root 应按分包页面目录处理”。默认规则下，自动路由只会扫描 `srcRoot/pages/**` 与这些已声明 root 下的 `pages/**`。

## `subPackages.*.styles` {#subpackages-styles}

**类型**：`string | SubPackageStyleConfigObject | (string | SubPackageStyleConfigObject)[]`

`SubPackageStyleConfigObject` 结构：

```ts
{
  source: string
  scope?: 'all' | 'pages' | 'components'
  include?: string | string[]
  exclude?: string | string[]
}
```

说明：

* `source` 支持 **相对分包 root / 相对 srcRoot / 绝对路径**。
* `scope` 提供快捷范围：
  * `all`（默认）分包内所有页面/组件
  * `pages` 仅 `pages/**`
  * `components` 仅 `components/**`
* `include/exclude` 用于精确匹配（基于分包 root 的相对路径）。

***

更多分包实践与产物示例，请阅读 [分包指南](/guide/subpackage)。

---

---
url: /guide/alias.md
description: >-
  Weapp-vite 同时支持 **JS/TS 别名** 与 **JSON/JSONC
  别名**，让你在脚本和配置文件里都能用同一套路径前缀。本页先给出最常见的配置方式，再补充一些使用建议；更细的字段说明请参考 配置文档 · JSON 配…
---

# 别名 {#alias}

`weapp-vite` 同时支持 **JS/TS 别名** 与 **JSON/JSONC 别名**，让你在脚本和配置文件里都能用同一套路径前缀。本页先给出最常见的配置方式，再补充一些使用建议；更细的字段说明请参考 [配置文档 · JSON 配置](/config/json.md) 与 [配置文档 · JS 配置](/config/js.md)。

## 适用场景

* 统一业务组件、工具方法的导入路径，避免深层级的 `../../`。
* 让 JSON 配置和 TypeScript 源码共享同一套别名，减少路径维护成本。
* 按团队约定快速切换不同的路径前缀（如 `@components/*`、`@shared/*`）。

设置完成后，Vite Dev Server 与小程序产物都会自动替你做路径转换，不需要在不同环境下手动调整。

## JS/TS 别名

项目默认会在检测到 `tsconfig.json` / `jsconfig.json` 中存在 `baseUrl` 或 `paths` 时启用 Vite 8 原生的 `resolve.tsconfigPaths`，所以你只要完成这些配置，就能在代码中直接使用别名。

例如：

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "./*"
      ]
    }
  }
}
```

然后你就可以在代码里这样写：

```ts
import utils from '@/utils'
```

运行 `weapp-vite dev` / `weapp-vite build` 时，别名会被自动解析成真实文件位置。

> \[!TIP]
> 默认场景建议直接使用原生 `resolve.tsconfigPaths`。如果需要指定多个 `tsconfig` 或忽略某些目录，再在 `vite.config.ts` 中通过 [`weapp.tsconfigPaths`](/config/js.md#weapp-tsconfigpaths) 传入对象启用 `vite-tsconfig-paths` 的高级选项。

## JSON / JSONC 别名

`weapp-vite` 对所有 JSON 配置文件做了增强，既允许使用注释，也支持别名映射，帮助你更好地组织大型项目。

首先，`weapp-vite` 允许你在应用/页面/组件的 `json/jsonc` 文件里写注释，例如：

* `// 这是注释`
* `/* 这也是注释 */`

```json
{
  "pages": [
    // 首页
    "pages/index/index"
  ],
  "usingComponents": {
    // 全局组件
    "navigation-bar": "/components/navigation-bar/navigation-bar"
  },
  "subPackages": [
    // 分包 A
    {
      "root": "packageA",
      "name": "pack1",
      "pages": [
        "pages/cat",
        "pages/dog"
      ]
    },
    // 分包 B 是独立分包
    {
      "root": "packageB",
      "name": "pack2",
      "pages": [
        "pages/apple",
        "pages/banana"
      ],
      // "entry": "index.js",
      // 独立分包应该特殊处理, 单独创建上下文
      "independent": true
    }
  ]
}
```

这些注释不会触发构建错误，并会在产物阶段被剔除。

要启用 JSON 别名，可在 `vite.config.ts` 中配置 [`weapp.jsonAlias.entries`](/config/json.md#weapp-jsonalias)。语法与 Vite 的 `resolve.alias` 完全一致：

> `weapp.jsonAlias.entries` 配置项传入的参数，同原先 `vite` 的 `resolve.alias` 配置项，[详见地址](https://vite.dev/config/shared-options.html#resolve-alias)

```ts
import type { UserConfig } from 'weapp-vite/config'
import path from 'node:path'

export default <UserConfig>{
  weapp: {
    jsonAlias: {
      entries: [
        {
          find: '@',
          replacement: path.resolve(import.meta.dirname, 'components'),
        },
      ],
    },
  },
}
```

配置完成后，就可以在 `usingComponents` 中直接书写别名（仅该字段会被重写）：

```json
{
  "usingComponents": {
    "navigation-bar": "@/navigation-bar/navigation-bar",
    "ice-avatar": "@/avatar/avatar"
  }
}
```

构建时会自动转化成相对路径：

```json
{
  "usingComponents": {
    "navigation-bar": "../../components/navigation-bar/navigation-bar",
    "ice-avatar": "../../components/avatar/avatar"
  }
}
```

最终产物的路径拼装取决于你在 `entries` 中的替换逻辑；如果希望使用绝对路径，也可以直接以 `/` 开头：

```json
{
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar"
  }
}
```

该写法会被解析为项目根目录下的实际文件。

## 常见问题排查

* **别名未生效？** 请确认 `pnpm dev` 重启过——`tsconfig` 修改后需要重新启动进程，Rolldown 才能读取新的 `paths`。
* **JSON 中提示路径不存在？** 开发者工具的校验不理解别名是正常现象，编译产物仍会替换为真实路径。若想在 IDE 内消除警告，可借助自定义类型定义或在 `usingComponents` 上方写注释标记。
* **同时使用多个 `tsconfig`？** 可以在 `vite.config.ts` 中配置 [`weapp.tsconfigPaths.projects`](../config/js.md#weapp-tsconfigpaths) 指定额外的配置文件，让 monorepo 子包共享同一套别名。

---

---
url: /community/group.md
description: 如果你在使用中遇到什么问题，也欢迎你进入交流群进行提问。提问时请尽量携带最小复现案例，我们会更快定位问题。
---

# 加入技术交流群

如果你在使用中遇到什么问题，也欢迎你进入交流群进行提问。提问时请尽量携带最小复现案例，我们会更快定位问题。

:::tip
注意⚠️: 添加时注明来自 `GitHub: weapp-vite` 项目
:::

> \[!NOTE]
> 参与社区交流时，请遵守项目的 [行为准则](https://github.com/weapp-vite/weapp-vite/blob/main/CODE_OF_CONDUCT.md) 与 Issue 模板，一起维护良好的讨论氛围。

> \[!IMPORTANT]
> 为了确保二维码与入群指引保持最新，请访问 [社区交流群指南](https://tw.icebreaker.top/docs/community/group)。按照文档提示即可加入微信或 QQ 群。

---

---
url: /packages/rolldown-require/cache.zh.md
description: 本文梳理 bundleRequire 在内部如何打包、落盘与加载，并介绍缓存相关的实用配置。
---

# 加载流程与缓存策略

> 语言： [English](/packages/rolldown-require/cache) | 中文

本文梳理 `bundleRequire` 在内部如何打包、落盘与加载，并介绍缓存相关的实用配置。

## 整体流程

1. **解析入口**：根据 `filepath` 与 `cwd` 生成绝对路径，并用后缀/`package.json.type` 推断 `format`（可手动覆盖）。
2. **rolldown 打包**：
   * 固定 `platform: 'node'`、`inlineDynamicImports: true`、`treeshake: false`，保证生成单入口产物并完整收集依赖。
   * 注入 `__dirname`/`__filename`/`import.meta.url`，让运行时代码感知源文件真实路径。
   * 通过 `externalize-deps` 插件外部化大部分 `node_modules` 依赖，同时保留 JSON 内联；尊重 `module-sync` 条件导出。
3. **执行临时产物**：
   * ESM：写入临时 `.mjs`/`.cjs` 或 data URL，再用 `import()` 加载。
   * CJS：通过 `_require.extensions` 临时钩子编译源文件。
4. **结果返回**：提供 `mod` 与 `dependencies`（包含入口以外的打包依赖）便于监听或调试。

## 外部化与解析

* 解析行为与 Vite/rolldown 对齐：使用相同的主字段优先级与 `tsconfig` 路径解析（若未禁用）。
* Node 内置与 `node:`/`npm:` 命名空间依赖会被直接标记为 external。
* 若依赖处于入口目录下的嵌套 `node_modules` 中，为保证临时产物可执行，会自动内联而非 external。
* JSON 资源暂不外部化，始终交给 rolldown 处理。

## 临时产物控制

* 默认写入最近的 `node_modules/.rolldown-require`，找不到时退回系统临时目录；文件名会包含随机哈希，避免并发冲突。
* 通过 `getOutputFile` 可自定义写入路径；`preserveTemporaryFile` 设为 `true` 时不会自动清理，便于直接查看产物。
* 若所有落盘尝试失败且目标为 ESM，会回退到 `data:` URL 写入。

## 缓存策略

缓存默认关闭。`cache: true` 或传入对象即可开启，包含持久化与进程内缓存：

* **缓存位置**：默认选择最近的 `node_modules/.rolldown-require-cache`，否则使用 `os.tmpdir()/rolldown-require-cache`。可通过 `cache.dir` 指定。
* **缓存键**：入口路径、`mtime`/`size`、`format`、`tsconfig` 路径、Node 版本以及 `rolldownOptions` 摘要共同决定。
* **有效性校验**：在命中缓存后，会逐个比对入口与依赖的 `mtime`/`size`；任意文件变化即视为失效。
* **内存缓存**：默认开启（`cache.memory !== false`），命中后直接返回已加载模块，避免额外的文件系统读写。
* **重置与事件**：
  * `cache.reset: true` 会在写入前清理旧的 code/meta 文件。
  * `cache.onEvent` 可获取 `hit`/`miss`/`store`/`skip-invalid` 事件，`skip-invalid` 的 `reason` 可能是 `missing-entry`、`format-mismatch`、`stale-deps` 等。

示例：记录缓存事件并自定义目录

```ts
await bundleRequire({
  filepath: './config/vite.config.ts',
  cache: {
    enabled: true,
    dir: './.cache/rolldown-require',
    onEvent: (e) => {
      console.log(`[cache] ${e.type}`, e)
    },
  },
})
```

## 调试建议

* 监听 `dependencies`，在文件变更后决定是否重新调用 `bundleRequire`。
* 配合 `preserveTemporaryFile: true` 检查生成的临时代码，或在缓存目录里直接比对 `*.code.mjs/cjs`。
* 若需要排查缓存误命中，可临时设置 `cache.reset: true` 或直接关闭缓存。
* 当入口后缀与 `package.json.type` 不匹配时，手动传入 `format` 可以避免 Node/rolldown 解析差异。

---

---
url: /packages.md
description: Weapp-vite 不只是一个构建器，packages/* 里还提供了脚手架、CLI、编译器、跨端 API、实验运行时和性能分析工具。
---

# 周边包总览

`weapp-vite` 不只是一个构建器，`packages/*` 里还提供了脚手架、CLI、编译器、跨端 API、实验运行时和性能分析工具。

做技术选型时，建议先看本页，再按需进入对应子页面。

## 选型建议（先看这个）

* 新建项目：优先用 `create-weapp-vite`
* 在 CI/脚本里调用微信开发者工具：用 `weapp-ide-cli`
* 需要“打包后执行配置文件”：用 `rolldown-require`
* 想追踪 Vite 插件耗时瓶颈：用 `vite-plugin-performance`
* 想在非 Vite 场景复用 Wevu 编译能力：用 `@wevu/compiler`
* 想统一多端小程序 API 调用风格：用 `@wevu/api`
* 想在浏览器里做小程序语法实验运行：用 `@weapp-vite/web`（实验）
* 想把 weapp-vite/wevu 能力暴露给 AI 助手：用 `@weapp-vite/mcp`
* 想增强 `<json>` 配置块智能提示：用 `@weapp-vite/volar`

## 包能力矩阵

| 包名                      | 定位                                     | 适用场景                       | 文档入口                                                                   |
| ------------------------- | ---------------------------------------- | ------------------------------ | -------------------------------------------------------------------------- |
| `create-weapp-vite`       | 官方脚手架                               | 快速创建模板项目、统一模板版本 | [/packages/create-weapp-vite](/packages/create-weapp-vite)                 |
| `weapp-ide-cli`           | 微信开发者工具 CLI 增强封装              | 本地自动化、CI 预览/上传       | [/packages/weapp-ide-cli](/packages/weapp-ide-cli)                         |
| `rolldown-require`        | 以 Rolldown 为核心的 bundle+require 工具 | 加载 TS/MJS/CJS 配置文件       | [/packages/rolldown-require/index.zh](/packages/rolldown-require/index.zh) |
| `vite-plugin-performance` | Vite 插件 Hook 耗时分析                  | 定位构建慢点、插件调优         | [/packages/vite-plugin-performance](/packages/vite-plugin-performance)     |
| `@wevu/compiler`          | Wevu 编译能力底座                        | 复用 SFC/模板编译管线          | [/packages/wevu-compiler](/packages/wevu-compiler)                         |
| `@wevu/api`               | 跨平台小程序 API 封装                    | Promise 风格统一调用           | [/packages/weapi/](/packages/weapi/)                                       |
| `@weapp-vite/web`         | Web 端实验运行时与插件                   | 浏览器侧验证小程序语法/页面    | [/packages/web](/packages/web)                                             |
| `@weapp-vite/mcp`         | MCP 服务实现                             | AI 代码助手接入与仓库能力开放  | [/packages/mcp](/packages/mcp)                                             |
| `@weapp-vite/volar`       | Volar 语言插件                           | `<json>` 配置块补全与校验      | [/packages/volar](/packages/volar)                                         |

## 已有独立文档模块

* `weapp-vite` 主包：见 [指引](/guide/) 与 [配置](/config/)
* `wevu` 运行时：见 [Wevu 专区](/wevu/)

## 说明

* `rolldown-require-bench` 主要用于基准测试，不建议直接作为业务依赖。
* `@weapp-vite/web` 仍偏实验用途，适合技术验证与学习。
* `@weapp-vite/mcp` 已被 `weapp-vite` CLI 集成，可直接用于 AI 协作流程。

---

---
url: /config/paths.md
description: >-
  基础目录与资源收集 {#paths-config}，聚焦 config / paths 相关场景，覆盖 Weapp-vite 与 Wevu
  的能力、配置和实践要点。
---

# 基础目录与资源收集 {#paths-config}

本页涵盖：

1. **源码根目录**（`app.json` 在哪）
2. **插件根目录**（是否同时构建小程序插件）
3. **静态资源收集与复制**（哪些文件会被搬进 `dist/`）
4. **额外 WXML**（可选，当前版本为预留字段）

\[\[toc]]

## `weapp.srcRoot` {#weapp-srcroot}

* **类型**：`string`
* **默认值**：项目根目录（`''` 等价于 `.`）
* **适用场景**：`app.json` 不在仓库根目录，或你希望把源码统一放在 `src/`、`miniprogram/` 等目录。

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

export default defineConfig({
  weapp: {
    srcRoot: './miniprogram',
  },
})
```

说明：

* `srcRoot` 会影响 **扫描入口**、**产物路径**、**资源复制** 与 **自动路由** 等行为。
* 构建时会从该目录寻找 `app.json`，找不到会直接报错。

## `weapp.pluginRoot` {#weapp-pluginroot}

* **类型**：`string`
* **默认值**：`undefined`
* **适用场景**：项目中同时维护“小程序插件”，需要一起打包 `plugin.json` 与插件代码。

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

export default defineConfig({
  weapp: {
    srcRoot: '.',
    pluginRoot: './plugin',
  },
})
```

说明：

* `pluginRoot` 指向 `plugin.json` 所在目录。
* 插件产物输出路径会根据 `project.config.json` 的 `pluginRoot`（若有）或构建输出目录自动推导。
* 插件构建与主应用构建复用同一套 alias/TS/依赖处理能力。

## `weapp.copy` {#weapp-copy}

* **类型**：`{ include?: string[]; exclude?: string[]; filter?: (filePath: string) => boolean }`
* **默认值**：`undefined`
* **适用场景**：把字体/证书/自定义数据等 **非代码资源** 复制到 `dist/`。

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

export default defineConfig({
  weapp: {
    copy: {
      include: ['**/*.ttf', '**/*.cer'],
      exclude: ['**/examples/**'],
      filter(filePath) {
        return !filePath.includes('README')
      },
    },
  },
})
```

行为说明：

* 默认会收集常见静态资源后缀（如 `png/jpg/svg/mp3/mp4/wasm`），并排除 `node_modules`、`miniprogram_npm`、`.wevu-config` 等目录。
* `include` / `exclude` 是 glob 列表，匹配范围基于 `srcRoot`（主应用）或 `pluginRoot`（插件构建）。
* `filter` 会在 glob 命中后再次过滤。

> \[!TIP]
> Vite 的 `public/` 目录仍会被原样复制。如果资源已经放在 `public/`，通常不需要再配置 `weapp.copy`。

## `weapp.isAdditionalWxml` {#weapp-isadditionalwxml}

* **类型**：`(wxmlFilePath: string) => boolean`
* **默认值**：`() => false`
* **状态**：**当前版本为预留字段**（尚未接入扫描/产物流程）。

如果你的项目依赖“运行时动态拼接 WXML 路径”，建议 **改用显式文件引用** 或在构建阶段自行补充产物；该字段目前不会影响构建图谱。

***

下一步：需要构建输出与兼容策略？请前往 [构建输出与兼容](./build-and-output.md)。

---

---
url: /troubleshoot.md
description: 遇到构建或运行异常？先从以下问题入手自检，大多数情况都能在几分钟内定位原因。若仍未解决，可携带日志在 Issue 或社区群反馈。
---

# 常见问题排查

遇到构建或运行异常？先从以下问题入手自检，大多数情况都能在几分钟内定位原因。若仍未解决，可携带日志在 Issue 或社区群反馈。

## 启动开发时出现 `EMFILE` / `ENOSPC` 或 `unable to start FSEvent stream`？

* **症状**：执行 `pnpm dev` / `pnpm dev:open` 时报监听相关错误，例如：
  * `EMFILE: too many open files`
  * `ENOSPC: System limit for number of file watchers reached`
  * `unable to start FSEvent stream`
* **原因**：系统文件描述符或文件监听器上限不足，构建器无法继续创建 watch。

### 临时处理（当前终端生效）

macOS / Linux 可先执行：

```bash
ulimit -n 65536
```

然后重新运行 `pnpm dev`。

### 长期处理（推荐）

#### macOS

1. 新建并加载 `launchd` 配置（将软/硬限制都提到 `65536`）：

```bash
sudo tee /Library/LaunchDaemons/limit.maxfiles.plist >/dev/null <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>limit.maxfiles</string>
    <key>ProgramArguments</key>
    <array>
      <string>launchctl</string>
      <string>limit</string>
      <string>maxfiles</string>
      <string>65536</string>
      <string>65536</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>ServiceIPC</key>
    <false/>
  </dict>
</plist>
EOF

sudo launchctl bootstrap system /Library/LaunchDaemons/limit.maxfiles.plist
sudo launchctl enable system/limit.maxfiles
```

2. 重启系统后，用 `ulimit -n` 或 `launchctl limit maxfiles` 检查是否生效。

#### Linux（inotify 上限）

```bash
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
echo fs.inotify.max_user_instances=1024 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```

### 仍有问题时建议一并检查

1. 是否在同一终端里重复启动了多个 `pnpm dev`；
2. 微信开发者工具是否打开了过多项目；
3. 项目根目录是否包含超大体量临时文件且未被忽略。

## 构建产物里只有 WXML？

* **症状**：`dist/` 中只有 `.wxml`，缺失 `.js`、`.wxss`、`.json`。
* **常见原因**：页面未在 `app.json.pages` 注册，或组件缺少 `json.component = true`。
* **排查步骤**：
  1. 打开 `app.json` 是否包含该页面路径；
  2. 检查组件是否位于 `usingComponents`，以及是否具备同名 `.json`；
  3. 使用 [`weapp.debug.watchFiles`](/config/shared.md#weapp-debug) 输出监听列表确认扫描情况。

> \[!TIP]
> 依赖扫描流程详见 [依赖分析扫描流程](/deep/scan.md)。了解入口判定规则可以更快定位遗漏。

## 目录结构正确仍报 `require()` 错误？

这通常是微信开发者工具缓存造成的。试试：

1. 在开发者工具中临时开启「将 JS 编译成 ES5」，触发一次重新编译；
2. 再关闭该选项并重启工具；
3. 若仍未恢复，可删除项目目录下的 `miniprogram_npm`、`dist` 后重新执行 `pnpm build`。

## 引入 UMD/CJS 模块时报错？

* 例如 `visactor` 的 `index-wx-simple.min.js` 体积较大并依赖 CommonJS，直接 `import` 会导致 ESM 分析失败。
* 解决方案：将文件重命名为 `.cjs` 或在源码中显式 `require()`，提示 bundler 将其按 CommonJS 处理。
* 参考案例：[issue #115](https://github.com/weapp-vite/weapp-vite/issues/115)。

## `custom-tab-bar` 不生效？

确保同时满足两点：

1. `custom-tab-bar/` 文件夹与 `app.json` 位于同级目录（例如二者都在 `src/` 下）。
2. `app.json.tabBar.custom` 设置为 `true`。

> \[!NOTE]
> Skyline 的 [全局工具栏](https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/skyline/appbar.html#%E4%BD%BF%E7%94%A8%E6%B5%81%E7%A8%8B) 也遵循同样的目录要求。

***

若以上方案未解决问题，请收集：

* 复现步骤与最小示例仓库；
* `pnpm build` 输出日志、微信开发者工具控制台日志；
* `vite.config.ts`、`app.json` 关键配置。

然后在 [GitHub Issues](https://github.com/weapp-vite/weapp-vite/issues) 或社区群提问，我们会尽快协助排查。

---

---
url: /packages/weapi/platform-only-methods.md
description: '@wevu/api 三端类型来源中，相对微信命名体系的支付宝/抖音独有 API 清单。'
---

# 平台独有 API 清单

本页展示相对微信命名体系而言，支付宝和抖音 typings 中额外存在的独有 API。

# 06 平台独有方法清单

## 支付宝独有（相对微信命名）

总计：93

* `alert`
* `calculateRoute`
* `call`
* `cancelBluetoothPair`
* `checkBeforeAddOrder`
* `checkIsIfaaEnrolledInDevice`
* `checkIsSupportIfaaAuthentication`
* `chooseAlipayContact`
* `chooseCity`
* `chooseDistrict`
* `choosePhoneContact`
* `confirm`
* `connectBLEDevice`
* `createLottieContext`
* `createRewardedAd`
* `createWebViewContext`
* `datePicker`
* `detectFileType`
* `disconnectBLEDevice`
* `generateImageFromCode`
* `getAccessibilityManager`
* `getAddress`
* `getAppIdSync`
* `getAuthCode`
* `getBLEDeviceStatus`
* `getBluetoothPairs`
* `getClipboard`
* `getFileInfo`
* `getGeocoder`
* `getLeftButtonsBoundingClientRect`
* `getMapInfo`
* `getOpenUserInfo`
* `getParentAppId`
* `getParentAppIdSync`
* `getPhoneNumber`
* `getPluginIdSync`
* `getRunData`
* `getRunScene`
* `getSavedFileInfo`
* `getSavedFileList`
* `getServerTime`
* `getTitleColor`
* `hideAddToDesktopMenu`
* `hideAllAddToDesktopMenu`
* `hideBackHome`
* `isScreenReaderEnabled`
* `loadPlugin`
* `multiLevelSelect`
* `off`
* `offBLEConnectionStateChanged`
* `offComponentError`
* `offLocatedComplete`
* `offSocketClose`
* `offSocketError`
* `offSocketMessage`
* `offSocketOpen`
* `on`
* `onBLEConnectionStateChanged`
* `onComponentError`
* `onLocatedComplete`
* `openKBVoucherDetail`
* `openMerchantTicketList`
* `openMerchantVoucherList`
* `openOtherApp`
* `openTicketDetail`
* `openTicketList`
* `openVoucherDetail`
* `openVoucherList`
* `optionsSelect`
* `paySignCenter`
* `prompt`
* `regionPicker`
* `registerSSID`
* `removeSavedFile`
* `rsa`
* `saveFile`
* `saveImage`
* `scan`
* `setCanPullDown`
* `setClipboard`
* `setLocatedCity`
* `setNavigationBar`
* `setNavigationBarBottomLineColor`
* `showAuthGuide`
* `showBLEPermissionGuide`
* `showSharePanel`
* `startAPVerify`
* `startIfaaAuthentication`
* `tradePay`
* `unregisterSSID`
* `unsubscribeMessage`
* `vibrate`
* `watchShake`

## 抖音独有（相对微信命名）

总计：55

* `applyEcCoupon`
* `applyRefund`
* `canIPutStuffOverComponent`
* `checkFollowAwemeState`
* `checkFollowState`
* `completePaySync`
* `completeRefundSync`
* `continueToPay`
* `createBytennEngineContext`
* `createCloud`
* `createMerchantOrder`
* `createOrder`
* `createRefundOrder`
* `createRtcRoomContext`
* `createStickerManager`
* `followAwemeUser`
* `followOfficialAccount`
* `getAnalysisInfo`
* `getCustomButtonBoundingClientRect`
* `getEnvInfoSync`
* `getFileInfo`
* `getLiveUserInfo`
* `getMenuButtonLayout`
* `getMicroappInfo`
* `getRefundOrder`
* `getRoomInfo`
* `getSavedFileList`
* `getSelfCommentCountDuringPluginRunning`
* `getShopRecordToken`
* `getSidebarActivity`
* `hideInteractionBar`
* `isFollowingAnchor`
* `navigateToScene`
* `navigateToVideoView`
* `onReceiveAudiencesFollowAction`
* `onReceiveSpecifiedComment`
* `openAwemeUserProfile`
* `pay`
* `preloadDrawAd`
* `prerenderVideo`
* `removeSavedFile`
* `saveFile`
* `showDouyinOpenAuth`
* `showFavoriteGuide`
* `showInteractionBar`
* `submitEcCustomGoods`
* `subscribeAudiencesFollowAction`
* `subscribeSpecifiedContentComment`
* `subscribeSpecifiedUserComment`
* `unsubscribeAllSpecifiedContentComment`
* `unsubscribeAllSpecifiedUserComment`
* `unsubscribeAudiencesFollowAction`
* `updateExitGuideWindowInfo`
* `updateShopMemberPoints`
* `updateSidebarActivity`

---

---
url: /config/lib.md
description: Weapp-vite 的 lib 模式用于构建小程序组件库或业务模块。本页聚焦 weapp.lib 的入口、输出路径、组件 JSON 和 DTS 选项。
---

# 库模式配置 {#lib-config}

`weapp.lib` 用于把 `weapp-vite` 切换到 **库模式**：只构建你声明的入口及其依赖，不生成 `app.json`、页面路由和应用级产物。

如果你想先理解使用场景、模板结构和完整产物示例，先看 [组件库构建（lib 模式）](/guide/lib-mode)。本页只聚焦配置项本身。

\[\[toc]]

## `weapp.lib` {#weapp-lib}

* **类型**：
  ```ts
  {
    entry: string | string[] | Record<string, string>
    root?: string
    outDir?: string
    preservePath?: boolean
    fileName?: string | ((ctx: { name: string; input: string }) => string)
    componentJson?: boolean | 'auto' | ((ctx: { name: string; input: string }) => Record<string, any>)
    dts?: boolean | {
      enabled?: boolean
      mode?: 'internal' | 'vue-tsc'
      internal?: {
        tsconfig?: string | false
        compilerOptions?: CompilerOptions
        vueCompilerOptions?: Record<string, any>
      }
      rolldown?: RolldownDtsOptions
      vueTsc?: {
        tsconfig?: Record<string, any>
        compilerOptions?: CompilerOptions
        vueCompilerOptions?: Record<string, any>
      }
    }
  }
  ```
* **默认值**：未配置时不开启 lib 模式。

### 基础示例

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

export default defineConfig({
  weapp: {
    srcRoot: 'src',
    lib: {
      entry: {
        button: 'components/button/index.vue',
        card: 'components/card/index.vue',
      },
      outDir: 'dist-lib',
      preservePath: true,
      componentJson: 'auto',
    },
  },
})
```

### 字段说明

* `entry`：必填。声明库入口，支持单入口、数组多入口和具名入口对象。
* `root`：库源码根目录，默认沿用 `weapp.srcRoot`。
* `outDir`：lib 产物输出目录，默认沿用 `build.outDir`。
* `preservePath`：是否保留源码相对路径。默认 `true`，适合组件库保持现有目录结构。
* `fileName`：自定义 JS 产物路径，不包含扩展名。适合把多入口统一映射成 `[name]/index` 之类的结构。
* `componentJson`：
  * `false`：不自动生成组件 JSON；
  * `true`：总是生成；
  * `'auto'`：仅在入口缺少 JSON 且看起来是组件入口时自动生成；
  * `function`：按入口动态返回 JSON 内容。

## `weapp.lib.dts` {#weapp-lib-dts}

* **默认值**：`true`
* **作用**：为 lib 入口生成 `d.ts`，尤其适合导出 `.vue` 组件时保留类型能力。

### 快速示例

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: ['components/button/index.vue'],
      dts: {
        mode: 'vue-tsc',
        vueTsc: {
          compilerOptions: {
            declarationMap: true,
          },
        },
      },
    },
  },
})
```

### 选项说明

* `false`：关闭 DTS 生成。
* `true`：使用默认配置生成 DTS。
* `enabled`：显式控制是否输出类型文件。
* `mode`：
  * `internal`：默认模式，走内置方案，启动成本更低；
  * `vue-tsc`：交给 `vue-tsc` 生成，更贴近 Vue 生态工具链。
* `internal`：调整内置方案的 `tsconfig` / `compilerOptions` / `vueCompilerOptions`。
* `rolldown`：透传给 `rolldown-plugin-dts` 的附加配置，内置关键字段会被覆盖。
* `vueTsc`：当 `mode: 'vue-tsc'` 时，额外合并到临时 `tsconfig` 或传递对应编译参数。

## 常见组合

### 保留源码路径

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: ['components/button/index.vue'],
      preservePath: true,
    },
  },
})
```

适合希望 `src/components/button/index.vue` 最终输出到 `dist/components/button/index.*` 的场景。

### 统一输出成 `[name]/index`

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: {
        button: 'components/button/index.vue',
        card: 'components/card/index.vue',
      },
      fileName: ({ name }) => `${name}/index`,
      preservePath: false,
    },
  },
})
```

适合把多个入口整理成更稳定的发布目录结构。

## 注意事项

* lib 模式同样会应用 `weapp.chunks` 配置；多入口共享模块时是否生成 `common.js` 仍受 `sharedMode` 控制。
* 若你同时需要“本地调试 App”和“发布组件库”，推荐拆成两份配置文件：例如 `vite.config.ts` 负责调试，`weapp-vite.lib.config.ts` 负责发布。
* 若入口路径最终映射到同一个输出文件名，构建会报冲突错误；优先检查 `preservePath` 与 `fileName` 的组合。

---

---
url: /guide/plugin.md
description: >-
  Weapp-vite 可以在同一个项目中同时维护主应用与插件，只要开启 pluginRoot
  就能复用现有的热更新、构建、调试能力。本页将介绍适用场景、目录约定和常见问题，帮助你在几分钟内完成插件开发环境的搭建。
---

# 微信小程序插件开发

`weapp-vite` 可以在同一个项目中同时维护主应用与插件，只要开启 `pluginRoot` 就能复用现有的热更新、构建、调试能力。本页将介绍适用场景、目录约定和常见问题，帮助你在几分钟内完成插件开发环境的搭建。

::: tip TL;DR

1. 在 `vite.config.ts` 中设置 `weapp.pluginRoot` 指向插件目录。
2. 将 `plugin.json`、公共组件与页面放在该目录下，结构与官方要求保持一致。
3. 执行 `pnpm dev` / `pnpm build` 后，`dist-plugin/**` 会生成完整插件包，可直接导入微信开发者工具或配合 `weapp-ide-cli` 上传。
   :::

## 适用场景

* 主应用和插件需要共享工具链、依赖、IDE 提示。
* 想在插件中也享受 auto-import、样式预处理、自动构建 npm 等能力。
* 希望统一构建流程，在 CI 中一次产出应用 + 插件。

## 开启插件目录

```ts [vite.config.mts]
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    srcRoot: 'miniprogram',
    pluginRoot: 'plugin', // plugin.json 所在目录
  },
})
```

`pluginRoot` 可以是相对或绝对路径。`weapp-vite` 会：

* 读取该目录下的 `plugin.json`，自动根据 `main`、`publicComponents`、`pages` 等字段构建入口图；
* 监听插件目录中的 JS/WXML/WXSS 及配置文件，配合主应用实现热更新；
* 在构建阶段将插件产物输出到 `dist-plugin/**`，保持与原目录一致的层级。

若未设置 `pluginRoot`，则插件相关流程不会启用。

## 目录约定

以下是示例仓库（`apps/plugin-demo`）的插件目录结构，可作为参考：

```text
plugin
├── plugin.json
├── index.js           # 插件入口(main)
├── pages
│   └── hello-page
│       ├── hello-page.js
│       ├── hello-page.wxml
│       └── hello-page.wxss
└── components
    └── hello-component
        ├── hello-component.js
        ├── hello-component.json
        ├── hello-component.wxml
        └── hello-component.wxss
```

* 目录和文件命名与微信小程序插件规范完全一致；
* WXSS/WXML 会被在构建时复制到 `dist-plugin/**`，不会再污染源目录；
* 插件的静态资源（图片、字体等）建议放在插件目录下，`weapp-vite` 会一并复制。

## 开发流程

### 启动本地开发

```sh
# monorepo 场景下的示例（apps/plugin-demo）
pnpm --filter plugin-demo dev
# 或在独立项目中：
pnpm dev
```

* 主应用与插件会同时监听并增量构建。
* 插件入口产生的页面/组件同样支持热更新，输出目录为 `dist-plugin/**`。
* 可配合 `pnpm dev --open` 自动拉起微信开发者工具，进行真机或模拟器调试。

### 构建与上传

```sh
pnpm --filter plugin-demo build
```

构建完成后会看到类似结构：

```text
dist/
├── app.js
├── app.json
└── pages/…

dist-plugin/
├── plugin.json
├── index.js
├── pages/hello-page/…
└── components/hello-component/…
```

* 将 `dist` 目录作为项目根导入微信开发者工具即可预览；
* 若只需要上传插件，可根据微信官方要求打包 `dist-plugin` 内容；
* 插件产物会自动同步到 `project.config.json` 中配置的 `pluginRoot` 路径，无需额外脚本。
* 也可以搭配 [`weapp-ide-cli`](https://github.com/weapp-vite/weapp-vite/tree/main/packages/weapp-ide-cli) 实现命令行上传/预览。

## 示例项目

仓库内置了完整示例，可直接参考或复制：

* 路径：`apps/plugin-demo`
* 主要文件：`plugin/plugin.json`、`plugin/components/hello-component/*`、`plugin/pages/hello-page/*`
* 封装了常用脚本：
  ```json
  {
    "scripts": {
      "dev": "weapp-vite dev",
      "dev:open": "weapp-vite dev -o",
      "build": "weapp-vite build",
      "open": "weapp-vite open"
    }
  }
  ```

运行 `pnpm --filter plugin-demo dev` 即可复现插件开发体验。

## 常见问题

### 插件 WXSS 没有生成？

* 检查是否升级到最新版本，并确认 `pluginRoot` 指向正确；
* 仅当插件目录存在对应的 `.wxss` 文件或从脚本中引用样式时，才会生成；
* 若文件名出现 `../plugin` 等路径，请升级至包含本修复的版本。

### 附加功能是否生效？

插件编译共享绝大部分能力：

* 自动构建 npm、WXML/WXSS 增强、auto-import 等功能均可在插件内使用；
* 如果某些能力需要额外配置（如自动导入组件），请在 `vite.config.ts` 或插件目录下的模块中参照主应用的写法。

如仍有疑问，可到 [社区交流群](/community/group) 反馈或查看示例仓库的实现，或在 Issue 板块留言寻求帮助。

---

---
url: /wevu/quick-start.md
description: >-
  这一页只做一件事：帮你最快把 Wevu 跑起来。按“装包 -> 写一个页面/组件 ->（可选）接入 Store”走一遍即可。示例以 Weapp-vite +
  Vue SFC 为主；如果你不使用 SFC，也可以直接参考运行时 API 的部分。
---

# 快速上手 Wevu

这一页只做一件事：帮你最快把 Wevu 跑起来。按“装包 -> 写一个页面/组件 ->（可选）接入 Store”走一遍即可。示例以 Weapp-vite + Vue SFC 为主；如果你不使用 SFC，也可以直接参考运行时 API 的部分。

## 1. 安装

::: code-group

```sh [pnpm]
pnpm add -D wevu
```

```sh [yarn]
yarn add -D wevu
```

```sh [npm]
npm i -D wevu
```

```sh [bun]
bun add -D wevu
```

:::

:::warning 版本一致性
如果你同时安装 `weapp-vite` 与 `wevu`，请保持两者版本号一致（例如 `weapp-vite@x.y.z` 与 `wevu@x.y.z`），这样可以避免编译期与运行期组合不一致。
:::

:::warning 安装位置
`wevu` 必须安装在 `devDependencies` 中。上面的 `-D` / `--save-dev` 不是可选项。

原因是 Weapp-vite 会把 `wevu` 作为构建期依赖参与编译与内联；若误装到 `dependencies`，通常会被当成运行时 npm 依赖处理，影响产物结构与依赖落位。
:::

:::tip
运行时 API 均从 `wevu` 主入口导入；`wevu/compiler` 仅供 Weapp-vite 等编译侧工具使用（非稳定用户 API）。
:::

## 2. （可选）启用 Volar 插件

如果你正在使用 Weapp-vite + Vue SFC 开发小程序，可以在 `tsconfig.app.json`（或项目主 `tsconfig.json`）里启用 Weapp-vite 的 Volar 插件，以获得模板侧的更好类型推导：

```json
{
  "vueCompilerOptions": {
    "plugins": ["weapp-vite/volar"],
    "lib": "wevu"
  }
}
```

:::warning 必须设置 lib
`"vueCompilerOptions.lib": "wevu"` 用于告诉 Volar 从 Wevu 的类型声明里解析 `defineProps/withDefaults/defineEmits` 等脚本宏。若不设置，Volar 会按 Vue 默认宏处理，最终只剩 `any` 类型提示。
:::

:::info Wevu@1.2.0 起的 vue 依赖说明
从 Wevu@1.2.0 开始，`wevu` 会依赖 `vue`，但只用于获取其 `dts` 类型定义，不会引入任何 Vue 运行时代码。这样做是为了让 Volar 在 `<script setup>` 下正确解析 `props`、宏类型与 IDE 跳转（此前尝试过多种方案仍无法稳定解决）。业务代码仍应从 `wevu` 导入运行时 API。
:::

## 3. 写一个页面（SFC 示例）

`defineComponent()` 会在运行时通过小程序全局 `Component()` 注册页面/组件；`setup()` 返回的状态会参与快照 diff，并最小化 `setData`。

```vue
<!-- pages/counter/index.vue -->
<script setup lang="ts">
import { computed, onPageScroll, ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '计数器',
}))

const count = ref(0)
const doubled = computed(() => count.value * 2)
const reachedTop = ref(true)

onPageScroll(({ scrollTop }) => {
  reachedTop.value = scrollTop < 40
})

function inc() {
  count.value += 1
}
</script>

<template>
  <view class="page">
    <text>count: {{ count }} / doubled: {{ doubled }}</text>
    <text v-if="!reachedTop">
      正在滚动...
    </text>
    <button @tap="inc">
      +1
    </button>
  </view>
</template>
```

## 4. 引入自定义组件（小程序规则）

推荐使用 Script Setup JSON 宏声明 `usingComponents`；脚本里无需（也不推荐）`import` 子组件：

```vue
<script setup lang="ts">
definePageJson(() => ({
  usingComponents: {
    'my-card': '/components/MyCard/index',
  },
}))
</script>
```

模板中直接 `<my-card />` 使用即可。

## 5. 组件 props / emit（运行时约定）

`setup` 与 Vue 3 对齐，仅支持 `setup(props, ctx)`。
若不需要 `props`，可写 `setup(_, ctx)`；若不需要 `ctx`，可只写 `setup(props)`。

`ctx.props` 来自小程序 `properties`；`ctx.emit(event, ...args)` 会调用小程序 `triggerEvent` 触发自定义事件。

```vue
<!-- components/Stepper/index.vue -->
<script lang="ts">
import { computed, defineComponent } from 'wevu'

export default defineComponent({
  properties: { modelValue: { type: Number, value: 0 } },
  setup(props, ctx) {
    const value = computed({
      get: () => props.modelValue ?? 0,
      set: v => ctx.emit('update:modelValue', v),
    })
    const inc = () => (value.value += 1)
    const dec = () => (value.value -= 1)
    return { value, inc, dec }
  },
})
</script>
```

```vue
<!-- 使用 -->
<template>
  <Stepper v-model="amount" />
</template>
```

## 6. 接入 Store（可选但常用）

```ts
// stores/counter.ts
import { computed, defineStore, ref } from 'wevu'

export const useCounter = defineStore('counter', () => {
  const count = ref(0)
  const doubled = computed(() => count.value * 2)
  const inc = () => count.value++
  return { count, doubled, inc }
})
```

```ts
// pages/counter/index.ts
import { defineComponent, storeToRefs } from 'wevu'
import { useCounter } from '@/stores/counter'

export default defineComponent({
  setup() {
    const counter = useCounter()
    const { count, doubled } = storeToRefs(counter)
    return { count, doubled, inc: counter.inc }
  },
})
```

推荐继续阅读：

* [`defineComponent` / 生命周期 / `bindModel`](/wevu/runtime)
* [Store API](/wevu/store)

---

---
url: /guide.md
description: 执行以下命令，快速创建一个集成了 Weapp-vite 的原生微信小程序项目：
---

# 快速开始 {#getting-started}

> \[!IMPORTANT]
> 使用前请确保安装 **Node.js `^20.19.0 || >=22.12.0`**。建议使用 [Node.js 官网](https://nodejs.org/) 的 LTS，并全局安装 `pnpm`（`npm i -g pnpm`）。

## 0. 准备工作

1. 下载并安装最新版 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)。
2. 启动开发者工具，在「设置 > 安全设置」中勾选 **服务端口**。这是 `pnpm dev --open`、`pnpm open` 等命令能唤起 IDE 的前提。
3. 第一次使用建议先手动打开一次项目，确认开发者工具可用，避免后续命令行提示 *“请先在微信开发者工具中开启服务端口”*。

## 1. 使用内置模板

### 1. 选择模板

执行以下命令，快速创建一个集成了 `weapp-vite` 的原生微信小程序项目：

::: code-group

```sh [pnpm]
pnpm create weapp-vite
```

```sh [yarn]
yarn create weapp-vite
```

```sh [npm]
npm create weapp-vite@latest
```

```sh [bun]
bun create weapp-vite
```

:::

::: details 生成的 `my-app` 项目中，默认包含以下内容:

```sh
.
├── 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
```

:::

### 2. 切换到目录中，执行安装命令

::: code-group

```sh [pnpm]
pnpm i
```

```sh [yarn]
yarn
```

```sh [npm]
npm i
```

```sh [bun]
bun i
```

:::

### 3. 开始开发

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

::: code-group

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

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

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

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

:::

### 4. 开发者工具预览

#### 执行 `open` 命令

::: code-group

```sh [pnpm]
pnpm open
```

```sh [yarn]
yarn open
```

```sh [npm]
npm run open
```

```sh [bun]
bun open
```

:::

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

## 2. 手动集成

### 1. 创建项目

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

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

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

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

![微信开发者工具创建基础项目](../images/create-project.png)

> 如果你创建的是 **TS 模板项目**，请在 `vite.config.ts` 中设置 [`weapp.srcRoot`](../config/paths.md#weapp-srcroot) 为 `'./miniprogram'`。

### 2. 手动接入 Weapp-vite

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

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

::: code-group

```sh [pnpm]
pnpm i
```

```sh [yarn]
yarn
```

```sh [npm]
npm i
```

```sh [bun]
bun i
```

:::

这样微信开发小程序的智能提示(`types`)，也都被安装进来

这样小程序 API 的类型声明（typings）也会一起装好，编辑器里就有补全和校验了。

> 想要一步步把现有项目接入 Weapp-vite：参考[《手动集成》](/guide/manual-integration)。想知道 CLI 初始化做了哪些改动：阅读 [`weapp-vite init 做了什么?`](/deep/init)。

## 预置命令

完整参数与命令别名可查看 [CLI 命令参考](/guide/cli)。

### 开发命令

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

命令会启动文件监听器，保存代码后会自动重新编译并同步到 `dist` 目录，无需手动刷新。

### 构建命令

```sh
pnpm build
pnpm build --open # 打开微信开发者工具，见下方
pnpm build -o # 打开微信开发者工具，见下方
```

此时会启用 `vite` 自带的 `build` 模式，删除整个 `dist` 目录重新生成，并进行代码压缩

### 打开微信开发者工具命令

```sh
pnpm open
```

使用该命令直接打开微信开发者工具（需要先开启服务端口）。

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

```sh
# 直接透传（推荐在脚本中使用）
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 show
```

> \[!WARNING]
> 请在 `微信开发者工具` → `设置` → `安全设置` → 勾选 `服务端口`。

> \[!WARNING]
> Linux 目前没有官方微信开发者工具，请安装社区版：[msojocs/wechat-web-devtools-linux](https://github.com/msojocs/wechat-web-devtools-linux)，并把 `wechat-devtools-cli` 链接到系统 `PATH`，例如：

```sh
sudo ln -s /opt/apps/io.github.msojocs.wechat-devtools-linux/files/bin/bin/wechat-devtools-cli /usr/local/bin/
```

### 生成组件命令

```sh
pnpm g [filename]
```

用于快速生成页面/组件/App 等基础文件，详见 [生成脚手架](/guide/generate)。

## 简易配置项

如果你用微信开发者工具创建的是 **TypeScript 模板**（源码目录为 `miniprogram/`），需要把 `weapp.srcRoot` 指向它；否则按模板默认的 `src/` 即可。

配置项可以与 `vite` 通用，同时加入了 `weapp-vite` 的扩展:

`vite.config.[m]ts`:

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

export default defineConfig({
  weapp: {
    // 让 weapp-vite 知道 app.json / pages/ 在哪个目录下
    srcRoot: './miniprogram',
  },
})
```

你也可以在 `defineConfig` 里继续使用其他 Vite 插件（例如 `weapp-tailwindcss`）。

更多配置见：[/config/](/config/)

---

---
url: /guide/manual-integration.md
description: 已经有运行中的微信小程序？可以按下面步骤在不依赖脚手架的情况下把 Weapp-vite 接进来。整体思路就三步：补齐配置文件 → 安装依赖 → 调整目录。
---

# 手动集成 Weapp-vite

已经有运行中的微信小程序？可以按下面步骤在不依赖脚手架的情况下把 `weapp-vite` 接进来。整体思路就三步：补齐配置文件 → 安装依赖 → 调整目录。

> 以下命令示例使用 `pnpm`，切换为 `npm`/`yarn`/`bun` 时语法相同。

## 1. 安装依赖

在项目根目录执行：

```sh
pnpm add -D weapp-vite vite typescript @types/node sass
```

如果你计划使用 Tailwind、Less、Vue Runtime 等，可以一并安装，但这里保持最小化。

> \[!IMPORTANT]
> 如果项目会同时使用 `weapp-vite` 与 `wevu`（例如启用 Vue SFC），请保持两者版本号一致，避免编译期与运行期组合不一致导致的问题。推荐写法如下：
>
> ```sh
> pnpm add -D weapp-vite@x.y.z wevu@x.y.z
> ```

## 2. 初始化必需文件

### package.json

确认 `package.json` 中存在以下脚本（没有就添加）：

```json
{
  "scripts": {
    "dev": "weapp-vite dev",
    "build": "weapp-vite build",
    "open": "weapp-vite open",
    "analyze": "weapp-vite analyze"
  }
}
```

后续运行时只需执行 `pnpm run dev` / `pnpm run build` 等常规命令。

### tsconfig

如果项目还没有 TS 配置，创建 `tsconfig.json` 与 `tsconfig.node.json`：

```json
// tsconfig.json
{
  "extends": "@tsconfig/recommended/tsconfig.json",
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "allowJs": true,
    "types": ["miniprogram-api-typings"]
  },
  "include": ["src/**/*", "typed-router.d.ts", "typed-components.d.ts"]
}
```

```json
// tsconfig.node.json
{
  "compilerOptions": {
    "composite": true,
    "module": "ESNext",
    "moduleResolution": "Node"
  },
  "include": ["vite.config.ts"]
}
```

### vite.config.ts

在项目根目录创建 `vite.config.ts`：

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

export default defineConfig({
  weapp: {
    srcRoot: 'src', // 若原项目位于 miniprogram，可改为 './miniprogram'
    autoRoutes: true,
    chunks: {
      sharedStrategy: 'duplicate',
    },
  },
})
```

`srcRoot` 指向你存放 `app.*`、`pages/` 的目录；如果想继续在根目录开发，可以把 `srcRoot` 改成 `'.'`。

### 项目配置

确保 `project.config.json` 中的 `miniprogramRoot` 指向打包目录（默认 `dist`）：

```json
{
  "miniprogramRoot": "dist/",
  "compileType": "miniprogram",
  "appid": "tour-app-id",
  "setting": {
    "es6": true,
    "minified": true
  }
}
```

## 3. 调整目录

1. 新建 `src/`（或 `srcRoot` 对应目录），并把原项目的 `app.*`、`pages/`、`packages/` 等文件全部移动到该目录。
2. 如果存在 `sitemap.json`、`theme.json` 等静态文件，可放在 `src/` 或 `public/`，`weapp-vite` 都会自动处理。
3. 若项目包含分包，把每个分包放在 `src/packages/<name>/`，再在 `app.json` 中保持原本定义即可。

建议同步创建以下结构（可参考 [目录结构](/guide/directory-structure/)）：

```text
src/
├─ app.ts / app.json / app.scss
├─ pages/
├─ packages/
├─ components/
├─ config/
└─ utils/
```

## 4. 验证运行

1. 在命令行执行 `pnpm run dev`，等待 `dist/` 生成。
2. 打开微信开发者工具，导入当前项目，勾选「服务端口」后可选用 `pnpm run dev -- --open` 自动唤起 IDE。
3. 构建上传使用 `pnpm run build`，需要分析分包时执行 `pnpm run analyze`。

## 5. 可选增强

* **自动导入组件**：默认扫描 `components/**` 与各分包 `components/**`；如需扩展，配置 [`weapp.autoImportComponents`](/guide/auto-import)。
* **自动路由**：在 `vite.config.ts` 中开启 `weapp.autoRoutes: true` 后，会生成路由清单与类型；如需同步到 `app.json`，请改用 `app.json.ts` 读取 `weapp-vite/auto-routes`。
* **脚手架生成**：可在 `package.json` 中增加 `"g": "weapp-vite generate"`，之后执行 `pnpm run g pages/dashboard` 快速生成页面文件夹。

这样就完成了在现有小程序中的手动集成，无需依赖 `create` 或 `init` 脚本。

---

---
url: /packages/weapi/douyin-compat-matrix.md
description: '@wevu/api 按微信命名调用时的抖音兼容矩阵。'
---

# 抖音兼容矩阵

本页展示 `wpi.<wxMethod>` 在抖音小程序环境下的目标 API、支持状态与映射策略，并按能力域组织。

能力域入口：

* [基础](/packages/weapi/douyin-compat-matrix/base)
* [路由](/packages/weapi/douyin-compat-matrix/route)
* [跳转](/packages/weapi/douyin-compat-matrix/navigate)
* [聊天工具](/packages/weapi/douyin-compat-matrix/chattool)
* [转发](/packages/weapi/douyin-compat-matrix/share)
* [界面](/packages/weapi/douyin-compat-matrix/ui)
* [网络](/packages/weapi/douyin-compat-matrix/network)
* [支付](/packages/weapi/douyin-compat-matrix/payment)
* [数据缓存](/packages/weapi/douyin-compat-matrix/storage)
* [数据分析](/packages/weapi/douyin-compat-matrix/data-analysis)
* [画布](/packages/weapi/douyin-compat-matrix/canvas)
* [媒体](/packages/weapi/douyin-compat-matrix/media)
* [位置](/packages/weapi/douyin-compat-matrix/location)
* [文件](/packages/weapi/douyin-compat-matrix/file)
* [开放接口](/packages/weapi/douyin-compat-matrix/open-api)
* [设备](/packages/weapi/douyin-compat-matrix/device)
* [AI](/packages/weapi/douyin-compat-matrix/ai)
* [Worker](/packages/weapi/douyin-compat-matrix/worker)
* [WXML](/packages/weapi/douyin-compat-matrix/wxml)
* [第三方平台](/packages/weapi/douyin-compat-matrix/ext)
* [广告](/packages/weapi/douyin-compat-matrix/ad)
* [XR-FRAME](/packages/weapi/douyin-compat-matrix/xr-frame)

---

---
url: /packages/weapi/douyin-compat-matrix/ai.md
description: '@wevu/api 抖音兼容矩阵中的 AI 能力。'
---

# 抖音兼容矩阵 · AI

---

---
url: /packages/weapi/douyin-compat-matrix/worker.md
description: '@wevu/api 抖音兼容矩阵中的 Worker 能力。'
---

# 抖音兼容矩阵 · Worker

---

---
url: /packages/weapi/douyin-compat-matrix/wxml.md
description: '@wevu/api 抖音兼容矩阵中的 WXML 能力。'
---

# 抖音兼容矩阵 · WXML

---

---
url: /packages/weapi/douyin-compat-matrix/xr-frame.md
description: '@wevu/api 抖音兼容矩阵中的 XR-FRAME 能力。'
---

# 抖音兼容矩阵 · XR-FRAME

---

---
url: /packages/weapi/douyin-compat-matrix/location.md
description: '@wevu/api 抖音兼容矩阵中的位置能力。'
---

# 抖音兼容矩阵 · 位置

---

---
url: /packages/weapi/douyin-compat-matrix/base.md
description: '@wevu/api 抖音兼容矩阵中的基础能力。'
---

# 抖音兼容矩阵 · 基础

---

---
url: /packages/weapi/douyin-compat-matrix/media.md
description: '@wevu/api 抖音兼容矩阵中的媒体能力。'
---

# 抖音兼容矩阵 · 媒体

---

---
url: /packages/weapi/douyin-compat-matrix/ad.md
description: '@wevu/api 抖音兼容矩阵中的广告能力。'
---

# 抖音兼容矩阵 · 广告

---

---
url: /packages/weapi/douyin-compat-matrix/open-api.md
description: '@wevu/api 抖音兼容矩阵中的开放接口能力。'
---

# 抖音兼容矩阵 · 开放接口

---

---
url: /packages/weapi/douyin-compat-matrix/payment.md
description: '@wevu/api 抖音兼容矩阵中的支付能力。'
---

# 抖音兼容矩阵 · 支付

---

---
url: /packages/weapi/douyin-compat-matrix/data-analysis.md
description: '@wevu/api 抖音兼容矩阵中的数据分析能力。'
---

# 抖音兼容矩阵 · 数据分析

---

---
url: /packages/weapi/douyin-compat-matrix/storage.md
description: '@wevu/api 抖音兼容矩阵中的数据缓存能力。'
---

# 抖音兼容矩阵 · 数据缓存

---

---
url: /packages/weapi/douyin-compat-matrix/file.md
description: '@wevu/api 抖音兼容矩阵中的文件能力。'
---

# 抖音兼容矩阵 · 文件

---

---
url: /packages/weapi/douyin-compat-matrix/canvas.md
description: '@wevu/api 抖音兼容矩阵中的画布能力。'
---

# 抖音兼容矩阵 · 画布

---

---
url: /packages/weapi/douyin-compat-matrix/ui.md
description: '@wevu/api 抖音兼容矩阵中的界面能力。'
---

# 抖音兼容矩阵 · 界面

---

---
url: /packages/weapi/douyin-compat-matrix/ext.md
description: '@wevu/api 抖音兼容矩阵中的第三方平台能力。'
---

# 抖音兼容矩阵 · 第三方平台

---

---
url: /packages/weapi/douyin-compat-matrix/network.md
description: '@wevu/api 抖音兼容矩阵中的网络能力。'
---

# 抖音兼容矩阵 · 网络

---

---
url: /packages/weapi/douyin-compat-matrix/chattool.md
description: '@wevu/api 抖音兼容矩阵中的聊天工具能力。'
---

# 抖音兼容矩阵 · 聊天工具

---

---
url: /packages/weapi/douyin-compat-matrix/device.md
description: '@wevu/api 抖音兼容矩阵中的设备能力。'
---

# 抖音兼容矩阵 · 设备

---

---
url: /packages/weapi/douyin-compat-matrix/route.md
description: '@wevu/api 抖音兼容矩阵中的路由能力。'
---

# 抖音兼容矩阵 · 路由

---

---
url: /packages/weapi/douyin-compat-matrix/navigate.md
description: '@wevu/api 抖音兼容矩阵中的跳转能力。'
---

# 抖音兼容矩阵 · 跳转

---

---
url: /packages/weapi/douyin-compat-matrix/share.md
description: '@wevu/api 抖音兼容矩阵中的转发能力。'
---

# 抖音兼容矩阵 · 转发

---

---
url: /packages/weapi/alipay-compat-matrix.md
description: '@wevu/api 按微信命名调用时的支付宝兼容矩阵。'
---

# 支付宝兼容矩阵

本页展示 `wpi.<wxMethod>` 在支付宝小程序环境下的目标 API、支持状态与映射策略，并按能力域组织。

能力域入口：

* [基础](/packages/weapi/alipay-compat-matrix/base)
* [路由](/packages/weapi/alipay-compat-matrix/route)
* [跳转](/packages/weapi/alipay-compat-matrix/navigate)
* [聊天工具](/packages/weapi/alipay-compat-matrix/chattool)
* [转发](/packages/weapi/alipay-compat-matrix/share)
* [界面](/packages/weapi/alipay-compat-matrix/ui)
* [网络](/packages/weapi/alipay-compat-matrix/network)
* [支付](/packages/weapi/alipay-compat-matrix/payment)
* [数据缓存](/packages/weapi/alipay-compat-matrix/storage)
* [数据分析](/packages/weapi/alipay-compat-matrix/data-analysis)
* [画布](/packages/weapi/alipay-compat-matrix/canvas)
* [媒体](/packages/weapi/alipay-compat-matrix/media)
* [位置](/packages/weapi/alipay-compat-matrix/location)
* [文件](/packages/weapi/alipay-compat-matrix/file)
* [开放接口](/packages/weapi/alipay-compat-matrix/open-api)
* [设备](/packages/weapi/alipay-compat-matrix/device)
* [AI](/packages/weapi/alipay-compat-matrix/ai)
* [Worker](/packages/weapi/alipay-compat-matrix/worker)
* [WXML](/packages/weapi/alipay-compat-matrix/wxml)
* [第三方平台](/packages/weapi/alipay-compat-matrix/ext)
* [广告](/packages/weapi/alipay-compat-matrix/ad)
* [XR-FRAME](/packages/weapi/alipay-compat-matrix/xr-frame)

---

---
url: /packages/weapi/alipay-compat-matrix/ai.md
description: '@wevu/api 支付宝兼容矩阵中的 AI 能力。'
---

# 支付宝兼容矩阵 · AI

---

---
url: /packages/weapi/alipay-compat-matrix/worker.md
description: '@wevu/api 支付宝兼容矩阵中的 Worker 能力。'
---

# 支付宝兼容矩阵 · Worker

---

---
url: /packages/weapi/alipay-compat-matrix/wxml.md
description: '@wevu/api 支付宝兼容矩阵中的 WXML 能力。'
---

# 支付宝兼容矩阵 · WXML

---

---
url: /packages/weapi/alipay-compat-matrix/xr-frame.md
description: '@wevu/api 支付宝兼容矩阵中的 XR-FRAME 能力。'
---

# 支付宝兼容矩阵 · XR-FRAME

---

---
url: /packages/weapi/alipay-compat-matrix/location.md
description: '@wevu/api 支付宝兼容矩阵中的位置能力。'
---

# 支付宝兼容矩阵 · 位置

---

---
url: /packages/weapi/alipay-compat-matrix/base.md
description: '@wevu/api 支付宝兼容矩阵中的基础能力。'
---

# 支付宝兼容矩阵 · 基础

---

---
url: /packages/weapi/alipay-compat-matrix/media.md
description: '@wevu/api 支付宝兼容矩阵中的媒体能力。'
---

# 支付宝兼容矩阵 · 媒体

---

---
url: /packages/weapi/alipay-compat-matrix/ad.md
description: '@wevu/api 支付宝兼容矩阵中的广告能力。'
---

# 支付宝兼容矩阵 · 广告

---

---
url: /packages/weapi/alipay-compat-matrix/open-api.md
description: '@wevu/api 支付宝兼容矩阵中的开放接口能力。'
---

# 支付宝兼容矩阵 · 开放接口

---

---
url: /packages/weapi/alipay-compat-matrix/payment.md
description: '@wevu/api 支付宝兼容矩阵中的支付能力。'
---

# 支付宝兼容矩阵 · 支付

---

---
url: /packages/weapi/alipay-compat-matrix/data-analysis.md
description: '@wevu/api 支付宝兼容矩阵中的数据分析能力。'
---

# 支付宝兼容矩阵 · 数据分析

---

---
url: /packages/weapi/alipay-compat-matrix/storage.md
description: '@wevu/api 支付宝兼容矩阵中的数据缓存能力。'
---

# 支付宝兼容矩阵 · 数据缓存

---

---
url: /packages/weapi/alipay-compat-matrix/file.md
description: '@wevu/api 支付宝兼容矩阵中的文件能力。'
---

# 支付宝兼容矩阵 · 文件

---

---
url: /packages/weapi/alipay-compat-matrix/canvas.md
description: '@wevu/api 支付宝兼容矩阵中的画布能力。'
---

# 支付宝兼容矩阵 · 画布

---

---
url: /packages/weapi/alipay-compat-matrix/ui.md
description: '@wevu/api 支付宝兼容矩阵中的界面能力。'
---

# 支付宝兼容矩阵 · 界面

---

---
url: /packages/weapi/alipay-compat-matrix/ext.md
description: '@wevu/api 支付宝兼容矩阵中的第三方平台能力。'
---

# 支付宝兼容矩阵 · 第三方平台

---

---
url: /packages/weapi/alipay-compat-matrix/network.md
description: '@wevu/api 支付宝兼容矩阵中的网络能力。'
---

# 支付宝兼容矩阵 · 网络

---

---
url: /packages/weapi/alipay-compat-matrix/chattool.md
description: '@wevu/api 支付宝兼容矩阵中的聊天工具能力。'
---

# 支付宝兼容矩阵 · 聊天工具

---

---
url: /packages/weapi/alipay-compat-matrix/device.md
description: '@wevu/api 支付宝兼容矩阵中的设备能力。'
---

# 支付宝兼容矩阵 · 设备

---

---
url: /packages/weapi/alipay-compat-matrix/route.md
description: '@wevu/api 支付宝兼容矩阵中的路由能力。'
---

# 支付宝兼容矩阵 · 路由

---

---
url: /packages/weapi/alipay-compat-matrix/navigate.md
description: '@wevu/api 支付宝兼容矩阵中的跳转能力。'
---

# 支付宝兼容矩阵 · 跳转

---

---
url: /packages/weapi/alipay-compat-matrix/share.md
description: '@wevu/api 支付宝兼容矩阵中的转发能力。'
---

# 支付宝兼容矩阵 · 转发

---

---
url: /config/build-and-output.md
description: 解释 Weapp-vite 的产物输出目录、JS 输出格式与兼容策略，以及这些配置对包体积和运行稳定性的影响。
---

# 构建输出与兼容 {#build-and-output}

本页说明 **产物输出目录** 与 **JS 输出格式/兼容策略**。它们直接决定：

* `dist/` 的目录结构
* 是否输出 CommonJS 或 ESM
* 是否启用 ES5 兼容降级
* 是否启用多平台 `project.config` 解析
* 是否压缩代码、是否生成 sourcemap

\[\[toc]]

## 输出目录来源

`weapp-vite` 的输出目录默认由 `project.config.json`（或多端配置）中的 **miniprogramRoot** 决定：

* 若 `build.outDir` **未显式配置**，`weapp-vite` 会将 `build.outDir` 设置为 `miniprogramRoot`。
* 若 `build.outDir` **已配置**，则以你的配置为准。

> \[!NOTE]
> 当启用 `weapp.multiPlatform` 且 `miniprogramRoot` 为相对路径 `dist` 时，输出会自动调整为 `dist/<platform>/dist`，以避免不同平台互相覆盖。

## `weapp.multiPlatform` {#weapp-multiplatform}

* **类型**：`boolean | { enabled?: boolean; projectConfigRoot?: string }`
* **默认值**：`false`
* **作用**：启用按平台读取 `project.config` 的模式，常用于同一仓库输出微信、支付宝、抖音等不同小程序平台。

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

export default defineConfig({
  weapp: {
    multiPlatform: {
      enabled: true,
      projectConfigRoot: 'config',
    },
  },
})
```

行为说明：

* `true` 等价于 `{ enabled: true, projectConfigRoot: 'config' }`。
* 启用后会按 `${projectConfigRoot}/${platform}/<platform-config-file>` 解析平台配置。
* 需要配合 CLI `--platform` 指定目标平台，例如 `weapp-vite build --platform alipay`。
* 若你的多端项目都使用相对 `miniprogramRoot`，建议显式检查最终输出目录，避免多个平台互相覆盖。

## `weapp.jsFormat` {#weapp-jsformat}

* **类型**：`'cjs' | 'esm'`
* **默认值**：`'cjs'`
* **作用**：控制 Rolldown/Rollup 的输出格式。

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

export default defineConfig({
  weapp: {
    jsFormat: 'esm',
  },
})
```

行为说明：

* `cjs`（默认）：输出 CommonJS，兼容性最好。
* `esm`：输出 ESM；在微信开发者工具中建议开启「ES6 转 ES5」以降低预览差异。

> \[!WARNING]
> 如果你手动把 `build.target` 设为 **ES2015 以下**，会直接报错；历史上的 `weapp.es5` 兼容方案已废弃，不建议继续依赖。

## `weapp.es5` {#weapp-es5}

* **类型**：`boolean`
* **默认值**：`false`
* **状态**：**已废弃**
* **历史作用**：在输出 CommonJS 的基础上，用 `@swc/core` 进行 **ES5 降级**。

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

export default defineConfig({
  weapp: {
    jsFormat: 'cjs',
    es5: true,
  },
})
```

使用须知：

* 不建议在新项目中继续开启。
* 仅支持 `jsFormat: 'cjs'`，与 `esm` 同用会直接报错。
* 需要安装 `@swc/core`：`pnpm add -D @swc/core`。
* 开启后，`build.target` 会被强制收敛到 `es2015`，再由 SWC 降级到 ES5。

迁移建议：

* 默认保持 `build.target >= es2020`，让 `?.` / `??` 不再进入 Rolldown 的降级分支。
* 在微信开发者工具中开启「将 JS 编译成 ES5」功能。
* 如果必须兼容极旧环境，再评估是否继续保留 `weapp.es5`。

## `build.minify` 与 `build.sourcemap` {#build-minify-sourcemap}

`weapp-vite` 直接复用 Vite 的 `build` 配置：

* `build.minify`：是否压缩代码（默认生产环境开启）。
* `build.sourcemap`：是否输出 sourcemap（可为 `true | false | 'inline' | 'hidden'`）。

如果你希望 **打包产物不压缩且生成 sourcemap**，可以这样配置：

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

export default defineConfig({
  build: {
    minify: false,
    sourcemap: true,
  },
})
```

也可以通过 CLI 临时覆盖：

```bash
weapp-vite build --minify false --sourcemap
```

> \[!TIP]
> 以上配置作用于你的项目产物（页面/组件/公共 chunk）。\
> 若还需要控制 `miniprogram_npm` 中依赖包的压缩与 sourcemap，请看下方 npm 配置页说明。

***

完成配置后建议重新执行 `pnpm build`，并在开发者工具内验证预览与上传流程。

---

---
url: /guide/module.md
description: >-
  Weapp-vite 基于 ESM（ECMAScript Modules）进行构建。建议在业务代码里尽量统一使用 import /
  export，这样类型推导、Tree Shaking、热更新都会更稳定。
---

# 模块化风格

`weapp-vite` 基于 ESM（ECMAScript Modules）进行构建。建议在业务代码里尽量统一使用 `import` / `export`，这样类型推导、Tree Shaking、热更新都会更稳定。

本页总结了小程序项目里常见的模块写法问题，以及对应的更稳妥写法。

## 统一改用 ESM

推荐在业务代码中全部采用 ESM，而不是混用 CommonJS (`require` / `module.exports`)。

```ts
// ✅ 推荐写法
import foo from '@/utils/foo'
import './register-global-components'

export default foo
export const bar = 'bar'

// ❌ 不推荐
const foo = require('@/utils/foo')
module.exports = foo
```

ESM 具备静态依赖图，打包器可以在构建期分析模块边界、自动移除未使用的导出，性能和可维护性都会更好。

## 处理路径差异

原生小程序里经常能见到 `import x from 'a/b/c'` 或 `import x from '/x/y/z'` 这种写法，但在标准 ESM 中它们并不总是合法（尤其是以 `/` 开头时会被当作 URL/根路径语义）。建议遵循以下约定：

* 使用 `./` 或 `../` 引入同目录、上级目录代码。
* 使用别名（如 `@/`）指向 `src` 根目录，避免 `/foo/bar` 这种会被当作 URL 解析的写法。

```ts
// 推荐
import util from './utils'
import config from '@/config'

// 可能导致路径解析错误
import util from 'utils'
import config from '/config'
```

别名配置请参考 [路径别名指南](/guide/alias)。

## 混合 ESM 与 CJS 时的注意事项

如果引用的第三方包仍然使用 CommonJS，请避免直接解构导入。标准的方式是使用命名空间导入，然后再手动解构：

```js
// apple.js (CommonJS)
module.exports = {
  a,
  b,
  c,
}

// ESM 中引用
import * as apple from './apple'
const { a, b, c } = apple
```

或者使用默认导入：

```js
import apple from './apple'
const { a, b, c } = apple
```

> \[!TIP]
> 如果第三方库同时提供 `module` 字段，Weapp-vite 会优先使用其 ESM 版本。仍然遇到导入问题时，可以考虑通过 [`optimizeDeps.include`](/config/npm.md#weapp-npm) 或转换插件提前处理。

## 其他最佳实践

* **保持文件后缀明确**：在导入本地文件时保留 `.ts`/`.js` 后缀可以减少构建器的解析工作，但不是必需；保持团队一致即可。
* **避免动态 `require`**：这会导致打包时无法静态分析依赖，推荐改用 `import()` 动态导入或显式列出需要的模块。
* **导出命名更清晰**：优先使用命名导出（`export const foo = ...`），默认导出保留给“文件只提供一个核心实体”的场景。

---

---
url: /guide/generate.md
description: >-
  Weapp-vite 自带一个生成器，用来一键生成页面/组件/App 的基础文件（页面/组件包含 js/ts、wxml、wxss、json；App 不生成
  wxml）。它适合两类情况：
---

# 生成脚手架

`weapp-vite` 自带一个生成器，用来一键生成页面/组件/App 的基础文件（页面/组件包含 `js/ts`、`wxml`、`wxss`、`json`；App 不生成 `wxml`）。它适合两类情况：

* 你不想每次都手动建目录、复制四件套模板
* 团队希望统一目录和文件后缀，减少“每个人生成出来都不一样”

## 快速上手

命令形式为 `weapp-vite generate [outDir]`，别名 `weapp-vite g [outDir]`。在执行 `weapp-vite init` 后，`package.json` 中会新增脚本 `pnpm g`，方便在项目中调用。

示例：在项目根目录执行：

```sh
pnpm g components/avatar
# 或直接调用二进制
pnpm weapp-vite g components/avatar
```

默认会创建如下结构：

```text
.
└── components
    └── avatar
        ├── avatar.json
        ├── avatar.js
        ├── avatar.wxss
        └── avatar.wxml
```

> \[!TIP]
> `weapp-vite init` 会自动把脚本添加到 `package.json`。如果你在现有项目中手动安装了 Weapp-vite，也可以自行补上 `"g": "weapp-vite generate"`。

## 自定义文件后缀与目录

很多团队会使用 TypeScript + Sass/SCSS 等组合。可以在 [`weapp.generate.extensions`](/config/generate.md#weapp-generate) 中指定默认后缀：

```ts
import type { UserConfig } from 'weapp-vite/config'

export default <UserConfig>{
  weapp: {
    generate: {
      extensions: {
        js: 'ts',
        wxss: 'scss',
        json: 'jsonc',
      },
    },
  },
}
```

此时再次执行 `pnpm g components/avatar`，生成的文件会自动变成 `.ts`、`.scss`、`.jsonc`。

> \[!TIP]
> 当 `extensions.json` 设为 `js/ts` 时，会生成 `*.json.js` / `*.json.ts`，便于配合脚本化 JSON 配置。

## 自定义模板内容

除了后缀，你还可以自定义“生成出来的默认内容”。`weapp.generate.templates` 支持四种写法：

* 字符串：视为模板文件路径（相对路径基于 CLI 当前工作目录）；
* `content`: 直接写入字符串；
* `path`: 指定已有模板文件（相对路径基于 CLI 当前工作目录）；
* 工厂函数：接收生成上下文，返回字符串（返回 `undefined` 时回退到默认模板）。

```ts
import { defineConfig } from 'weapp-vite'

export default defineConfig({
  weapp: {
    generate: {
      templates: {
        shared: {
          wxss: () => '.root { color: red; }',
          json: { content: '{ "component": true }' },
        },
        component: {
          js: { content: 'Component({})' },
          wxml: { path: './templates/component.wxml' },
        },
        page: {
          js: async ({ fileName }) => `Page({ pageName: '${fileName}' })`,
          wxml: ({ outDir, fileName, defaultCode }) =>
            `<!-- ${outDir}/${fileName}.wxml -->\n${defaultCode ?? ''}`,
        },
      },
    },
  },
})
```

生成器会优先查找 `type` 对应的模板（`component`、`page`、`app`），找不到时回退到 `shared`。模板上下文包含 `type`、`fileType`、`fileName`、`outDir`、`extension` 以及默认代码 `defaultCode`，方便你按不同目录/文件类型做差异化输出。

## 调整生成文件名

默认情况下文件名与目录名一致。例如 `pnpm g components/avatar` 会生成 `avatar.ts / avatar.wxml`。若想生成目录和文件名不同的结构，可以使用 `-n` / `--name`：

```sh
pnpm g components/avatar -n index
```

输出：

```text
└── components
    └── avatar
        ├── index.jsonc
        ├── index.scss
        ├── index.ts
        └── index.wxml
```

## 生成不同类型的模板

* 生成 **组件**（默认）：`pnpm g components/avatar`
* 生成 **页面**：`pnpm g pages/home -p`（或 `--page`）
* 生成 **app 入口**：`pnpm g src/app -a`（或 `--app`，仅生成 `js/ts`、`wxss`、`json` 三类文件）

你可以自由组合 `--page` / `--app` 与自定义模板，实现差异化的初始化内容。

## CLI 参数速查

| 参数         | 类型     | 说明                                                  |
| ------------ | -------- | ----------------------------------------------------- |
| `[outDir]`   | `string` | 目标目录，支持多级路径，例如 `pages/profile/settings` |
| `-a, --app`  | `bool`   | 生成 `app` 类型，仅创建脚本、样式、配置文件           |
| `-p, --page` | `bool`   | 生成 `page` 类型模板                                  |
| `-n, --name` | `string` | 指定生成文件名，默认为 `outDir` 最末级目录            |

想深入了解更多字段（例如 `dirs`、`filenames`、`templates`），请查看 [配置文档 · 生成脚手架配置](/config/generate.md)。

---

---
url: /config/generate.md
description: >-
  Weapp-vite generate 用于快速生成页面、组件和 App 基础文件。本页列出 weapp.generate
  的字段，方便你把生成目录、文件名、后缀和模板内容对齐到团队习惯。**这些配置仅影响 CLI 生成器，不影响构建流程…
---

# 生成脚手架配置 {#generate-config}

`weapp-vite generate` 用于快速生成页面、组件和 App 基础文件。本页列出 `weapp.generate` 的字段，方便你把生成目录、文件名、后缀和模板内容对齐到团队习惯。**这些配置仅影响 CLI 生成器，不影响构建流程。**

\[\[toc]]

## `weapp.generate` {#weapp-generate}

* **类型**：
  ```ts
  {
    extensions?: Partial<{ js: string; json: string; wxml: string; wxss: string }>
    dirs?: Partial<{ app: string; page: string; component: string }>
    filenames?: Partial<{ app: string; page: string; component: string }>
    templates?: TemplatesConfig
  }

  type TemplatesConfig = Partial<Record<'shared' | 'component' | 'page' | 'app', GenerateTemplateEntry>>

  type GenerateTemplateEntry = Partial<Record<'js' | 'json' | 'wxml' | 'wxss', TemplateSource>>

  type TemplateSource =
    | string
    | { path: string }
    | { content: string }
    | ((ctx: TemplateContext) => string | undefined | Promise<string | undefined>)

  interface TemplateContext {
    type: 'component' | 'page' | 'app'
    fileType: 'js' | 'json' | 'wxml' | 'wxss'
    fileName: string
    outDir: string
    extension: string
    cwd: string
    defaultCode?: string
  }
  ```
* **默认值**：`undefined`
* **适用场景**：
  * 用命令行创建页面/组件时，希望生成结果符合团队目录结构（而不是每次手动挪文件）。
  * 想在生成时就带上团队常用的模板内容（例如通用样式、占位配置、国际化骨架等）。

### 配置示例

```ts
export default defineConfig({
  weapp: {
    generate: {
      extensions: {
        js: 'ts',
        json: 'jsonc',
        wxss: 'scss',
      },
      dirs: {
        page: 'src/pages',
        component: 'src/components',
      },
      filenames: {
        app: 'app',
        page: 'index',
      },
      templates: {
        shared: {
          wxss: () => '.root { color: red; }',
        },
        component: {
          js: { content: 'Component({ custom: true })' },
        },
      },
    },
  },
})
```

### 字段说明

* `extensions`: 覆写生成文件的默认后缀，例如将 JS 切换为 TS、将 WXSS 改为 SCSS。`json` 允许设置为 `js/ts`，生成的文件名会变成 `*.json.js` / `*.json.ts`。
* `dirs`: 定义生成文件的默认目录。支持分别指定 `app`、`page`、`component` 的输出路径。未配置时以命令行传入的 `filepath` 为准。
* `filenames`: 定制生成文件的默认文件名。未显式传入 `--name` 时会优先使用该配置，否则回退到 `filepath` 的最后一段。
* `templates`: 为不同类型生成自定义文件内容。支持字符串、文件路径或工厂函数：
  * `string`: 视为模板文件路径（相对 `cwd`）。
  * `{ path: './template.wxml' }`: 从指定文件读取。
  * `{ content: '...' }`: 直接提供内容对象。
  * 函数：根据 `TemplateContext` 运行时返回字符串或 `undefined`，可结合条件逻辑灵活生成。

### CLI 说明与常见问题

生成器默认创建 **组件**，`-p/--page` 切换为页面，`-a/--app` 生成 app 入口（仅包含 `js/json/wxss`，不生成 `wxml`）：

```bash
pnpm weapp-vite g src/components/Avatar
pnpm weapp-vite g src/pages/home -p
pnpm weapp-vite g src -a
```

* **CLI 会覆盖已有文件吗？** 不会，生成命令只对全新文件生效，若目标文件已存在会提示冲突。
* **如何生成带注释的 JSON？** 把 `extensions.json` 设为 `jsonc` 即可，然后在模板里写注释/占位内容。
* **模板如何复用？** 用 `templates.shared` 提供全局基础模板，再在 `component`、`page`、`app` 里按需覆写。

***

接下来，可结合 [基础目录与资源收集](./paths.md#paths-config) 调整生成目标目录，或阅读 [共享配置](/config/shared.md) 在生成后自动注册组件与路由。

---

---
url: /guide/directory-structure.md
description: Weapp-vite 的目录结构总览页，按 Nuxt 式目录索引组织，左侧目录项为独立路由，右侧为每个目录或文件的详细说明。
---

# 目录结构

这一组文档按“目录即能力边界”的方式组织，交互形态参考 Nuxt 的 directory structure 页面。

* 左侧每一个目录或文件项，都是单独的文档路由
* 右侧页面只解释当前项的职责、默认行为和触发的能力
* 如果你只想先看全局，再决定点进哪个目录，从这页开始就够了

## 一个典型项目

```text
.
├─ vite.config.ts
├─ project.config.json
├─ package.json
├─ public/
└─ <srcRoot>/
   ├─ app.(js|ts)
   ├─ app.vue
   ├─ app.json(.js|.ts)?
   ├─ app.(css|scss|wxss|...)
   ├─ custom-tab-bar/
   ├─ app-bar/
   ├─ pages/
   ├─ components/
   ├─ <subPackageRoot>/
   │  ├─ pages/
   │  └─ components/
   ├─ shared/
   ├─ utils/
   ├─ workers/
   ├─ typed-router.d.ts
   ├─ typed-components.d.ts
   └─ components.d.ts
```

## 先记住三条

1. `weapp-vite` 真正依赖的是 `srcRoot`，不是硬编码的 `src/`
2. 页面自动扫描默认只看 `srcRoot/pages/**` 和已声明分包 root 下的 `pages/**`
3. `custom-tab-bar`、`app-bar`、类型声明文件这些都属于带固定语义的保留位置

> \[!TIP]
> 这一组文档里的 `<srcRoot>`、`<subPackageRoot>` 都是变量占位，不是固定目录名。它们分别代表你在 `vite.config.ts` 中声明的源码根目录和分包 root。

## 从哪里开始看

* 想先建立全局认知：看 [📄 vite.config.ts](/guide/directory-structure/vite-config)、[📁 `<srcRoot>/`](/guide/directory-structure/src-root)
* 想搞清楚页面与分包：看 [📁 `<srcRoot>/pages/`](/guide/directory-structure/pages)、[📁 `<srcRoot>/<subPackageRoot>/`](/guide/directory-structure/subpackages)
* 想搞清楚自动生成产物：看 [类型声明文件](/guide/directory-structure/generated-files)

## 默认能力速查

| 位置                                                              | 作用                                               |
| ----------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------- | ----- | ------------------------------------------- |
| `vite.config.ts`                                                  | 定义 `srcRoot`、自动路由、分包、自动导入组件等能力 |
| `project.config.json`                                             | 微信开发者工具配置                                 |
| `public/`                                                         | 构建时原样复制的静态资源                           |
| `app.(js                                                          | ts)`                                               | 应用脚本入口，承载生命周期和全局初始化          |
| `app.vue`                                                         | Vue SFC 形式的应用入口，可组合脚本、JSON 宏与样式  |
| `app.json(.js                                                     | .ts)?`                                             | 应用配置入口，既支持原生 JSON，也支持脚本化生成 |
| `app.(css                                                         | scss                                               | wxss                                            | ...)` | 全局样式入口，支持 CSS、WXSS 与常见预处理器 |
| `pages/`                                                          | 主包页面目录                                       |
| `components/`                                                     | 主包组件目录，默认参与自动导入扫描                 |
| `<subPackageRoot>/pages/`                                         | 已声明分包 root 下的页面目录                       |
| `custom-tab-bar/`                                                 | `tabBar.custom === true` 时的固定入口              |
| `app-bar/`                                                        | `appBar` 开启时的固定入口                          |
| `typed-router.d.ts` / `typed-components.d.ts` / `components.d.ts` | 自动生成的类型声明文件                             |

## 相关文档

* [自动路由](/guide/auto-routes)
* [自动导入组件](/guide/auto-import)
* [分包指南](/guide/subpackage)
* [手动集成](/guide/manual-integration)

---

---
url: /guide/directory-structure/generated-files.md
description: 自动路由和自动导入组件生成的类型声明文件，默认输出到 srcRoot 下。
---

# 类型声明文件

这一组文件默认都生成到 `srcRoot` 下，方便直接被项目的 `tsconfig` 覆盖到。

## 包含哪些文件

* `typed-router.d.ts`
* `typed-components.d.ts`
* `components.d.ts`

## `typed-router.d.ts`

这是 `weapp.autoRoutes` 生成的类型文件。

* 提供页面路径联合类型
* 增强 `weapp-vite/auto-routes` 的类型补全
* 增强 `wevu/router` 的路径约束

当自动路由开启，并且 `typedRouter` 没被关闭时，它会出现。

## `typed-components.d.ts`

这是自动导入组件生成的组件 props 类型文件。

* 负责组件 props 类型推断
* 增强自动导入组件相关的类型补全

当 `weapp.autoImportComponents.typedComponents` 开启时，它会出现。

## `components.d.ts`

这是 Vue 全局组件类型声明文件。

* 负责模板中的全局组件类型提示
* 配合自动导入组件一起工作

当 `weapp.autoImportComponents.vueComponents` 开启时，它会出现。

## 默认位置

```text
<srcRoot>/typed-router.d.ts
<srcRoot>/typed-components.d.ts
<srcRoot>/components.d.ts
```

## 相关文档

* [自动路由](/guide/auto-routes)
* [自动导入组件](/guide/auto-import)

---

---
url: /guide/lib-mode.md
description: Weapp-vite 的 **lib 模式** 用于打包小程序组件库或业务模块。它和应用模式的最大区别是：
---

# 组件库构建（lib 模式）

`weapp-vite` 的 **lib 模式** 用于打包小程序组件库或业务模块。它和应用模式的最大区别是：

* 只构建你声明的入口（组件/模块），不会生成 `app.json` 与页面路由。
* 输出目录默认保持源码相对路径，方便复用现有结构。
* 可以自动补全组件 JSON，适合批量产出可直接引用的组件库产物。

## 适用场景

* 组件库/模块库（希望被多个小程序复用）
* 多个业务包共享的 UI 或逻辑模块
* 希望把源码路径直接映射到产物路径的输出方式

## 快速开始（官方模板）

1. 生成项目（选择 **组件库模板 (lib 模式)**）：

```sh
pnpm create weapp-vite
```

2. 安装依赖：

```sh
pnpm i
```

3. 本地调试组件（会自动打开微信开发者工具）：

```sh
pnpm dev
```

4. 输出组件库产物：

```sh
pnpm build:lib
```

> \[!TIP]
> 模板会提供 `vite.config.ts`（用于本地调试）与 `weapp-vite.lib.config.ts`（用于库构建）。
> 你可以将应用调试与库构建拆成两个配置文件，互不影响。

## 基础配置

在 `weapp.lib` 中声明入口，即会进入 lib 模式：

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

export default defineConfig({
  weapp: {
    srcRoot: 'src',
    lib: {
      root: 'src',
      outDir: 'dist-lib',
      entry: [
        'components/HelloWorld/HelloWorld.ts',
        'components/sfc-script/index.vue',
        'components/sfc-setup/index.vue',
      ],
      preservePath: true,
      componentJson: 'auto',
    },
  },
})
```

### 核心字段说明

* `entry`：入口配置，支持 `string | string[] | Record<string, string>`。
* `root`：库源码根目录，默认沿用 `weapp.srcRoot`。
* `outDir`：lib 产物输出目录，默认沿用 `build.outDir`。
* `preservePath`：是否保持输出路径与源码路径一致（默认 `true`）。
* `fileName`：自定义 JS 产物路径（不含扩展名）。多入口时必须包含 `[name]`。
* `componentJson`：自动生成组件 JSON 配置（`true | 'auto' | (ctx) => object`）。

### 自定义输出路径

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: {
        button: 'components/button/index.vue',
        card: 'components/card/index.vue',
      },
      fileName: '[name]/index',
      outDir: 'dist-lib',
    },
  },
})
```

### 自动生成组件 JSON

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: ['components/button/index.vue'],
      componentJson: ctx => ({
        component: true,
        styleIsolation: 'shared',
        usingComponents: {},
      }),
    },
  },
})
```

`componentJson: 'auto'` 会在入口存在模板/样式但缺少 JSON 时自动生成 `{"component": true}`。

## 产物结构示例

假设入口为 `src/components/button/index.vue`，默认 `preservePath: true`：

```text
dist-lib/
  components/button/index.js
  components/button/index.wxml
  components/button/index.wxss
  components/button/index.json
```

如果入口只是纯 JS/TS 文件，则只会输出 `*.js`。

## 与 `weapp.chunks` 联动

lib 模式同样会应用 `weapp.chunks` 配置。若多个入口复用同一模块：

* `sharedMode: 'common'`（默认）会生成 `common.js`
* `sharedMode: 'path'` 会按源码路径输出共享模块（无 `common.js`）
* `sharedMode: 'inline'` 会直接内联到引用方

详见：[共享 Chunk 策略](/guide/chunks)。

## 常见问题

### 为什么没有 `app.json` 与页面产物？

lib 模式只输出你声明的入口及其依赖，不会生成应用页面与路由。

### 输出路径冲突怎么办？

当多个入口计算出同一路径时会报错。检查：

* 是否开启了 `preservePath` 并使用相同的入口目录
* `fileName` 是否在多入口模式下缺少 `[name]`

### 既要调试又要发组件库怎么办？

推荐使用 **两份配置**：

* `vite.config.ts`：本地调试（`pnpm dev`）
* `weapp-vite.lib.config.ts`：组件库构建（`pnpm build:lib`）

这样不会互相影响，也更容易维护。

---

---
url: /config/auto-import-components.md
description: >-
  Weapp-vite 会在构建阶段扫描 WXML 组件标签并自动补齐 usingComponents，免去手写 JSON 的负担。支持本地组件与第三方库
  Resolver（如 Vant/TDesign）。
---

# 自动导入组件配置 {#auto-import-components}

`weapp-vite` 会在构建阶段扫描 WXML 组件标签并自动补齐 `usingComponents`，免去手写 JSON 的负担。支持本地组件与第三方库 Resolver（如 Vant/TDesign）。

\[\[toc]]

## `weapp.autoImportComponents` {#weapp-autoimportcomponents}

* **类型**：
  ```ts
  {
    globs?: string[]
    resolvers?: Resolver[]
    output?: string | boolean
    typedComponents?: boolean | string
    htmlCustomData?: boolean | string
    vueComponents?: boolean | string
    vueComponentsModule?: string
  } | boolean
  ```
* **默认值**：启用（自动生成默认 `globs`）。

默认扫描规则：

* 主包：`components/**/*.wxml`
* 分包：`<root>/components/**/*.wxml`（若该分包未显式禁用）

如果你直接写 `autoImportComponents: true`，Weapp-vite 会在默认扫描规则之外，额外帮你启用：

* `typedComponents: true`
* `vueComponents: true`
* 当项目检测到 `wevu` 依赖时，自动补 `vueComponentsModule: 'wevu'`

### 示例

```ts
import { defineConfig } from 'weapp-vite/config'
import { TDesignResolver, VantResolver } from 'weapp-vite/auto-import-components/resolvers'

export default defineConfig({
  weapp: {
    autoImportComponents: true,
  },
})
```

如果你还需要第三方组件库 resolver、定制输出路径或额外扫描目录，再改回对象形式：

```ts
export default defineConfig({
  weapp: {
    autoImportComponents: {
      resolvers: [VantResolver(), TDesignResolver()],
      htmlCustomData: 'dist/mini-program.html-data.json',
      globs: ['components/**/*.wxml'],
    },
  },
})
```

### 字段说明

* `globs`：组件模板扫描范围（glob）。通常要求同目录下存在 `.wxml + .js/ts + .json`，且 JSON 内 `component: true`。
* `resolvers`：第三方组件库解析器，把标签映射到 npm 包路径（如 `<van-button>` → `@vant/weapp/button`）。
* `output`：生成 `auto-import-components.json` 清单。
  * `true` / 未设置：输出到 `vite.config.ts` 同级目录；
  * 字符串：自定义路径；
  * `false`：不生成清单。
* `typedComponents`：生成 `typed-components.d.ts`（WXML props 类型）。
* `htmlCustomData`：生成 `mini-program.html-data.json`（VS Code/DevTools 提示）。
* `vueComponents`：生成 `components.d.ts`（Vue SFC 模板补全）。
* `vueComponentsModule`：`components.d.ts` 的 `declare module 'xxx'` 模块名。使用 Wevu 时建议填 `wevu`。

### 禁用与分包覆盖

* 全局禁用：`autoImportComponents: false`
* 单独禁用分包：`weapp.subPackages.<root>.autoImportComponents = false`

> \[!TIP]
> 如需排除额外标签（例如占位标签），可以在 `weapp.wxml.excludeComponent` 中过滤。

更多实践示例请参考 [自动引入组件](/guide/auto-import)。

---

---
url: /guide/auto-import.md
description: Weapp-vite 可以在构建阶段自动扫描并注册组件，让你在 WXML 里直接写组件标签，而不需要手动维护 usingComponents。
---

# 自动引入组件

`weapp-vite` 可以在构建阶段自动扫描并注册组件，让你在 WXML 里直接写组件标签，而不需要手动维护 `usingComponents`。

你只需要告诉它两件事：

* 组件放在哪些目录（`globs`）
* 是否要接入第三方 UI 库（`resolvers`）

更细粒度的字段说明可参考 [配置文档 · 自动导入组件配置](/config/auto-import-components.md#weapp-autoimportcomponents)。

> \[!NOTE]
> 自动导入默认开启：主包 `components/**/*.wxml` 与每个 `subPackages.<root>` 下的 `components/**/*.wxml` 都会被自动扫描。仅当你需要：
>
> * 额外扩展扫描目录；
> * 关闭自动导入（例如 `autoImportComponents: false` 或 `autoImportComponents: { globs: [] }`）；或
> * 引入第三方 UI Resolver / 生成自定义输出
>
> 时才需要手动配置 `autoImportComponents`。

## 适用场景

* 在模板里直接写 `<HelloWorld />`，而不是每次都去 JSON 里登记一次。
* 组件数量多、目录复杂，希望构建器帮忙维护 `usingComponents`。
* 同时使用 Vant、TDesign 等 UI 库，希望和本地组件一样开箱即用。

## 快速上手：扫描项目组件

虽然无需额外配置即可生效，但你仍可以通过 [`weapp.autoImportComponents.globs`](/config/auto-import-components.md#weapp-autoimportcomponents) 表达更复杂的目录结构。满足“存在 `.wxml` + `.js/ts` + `.json` 且 `json.component === true`”的文件夹就会被自动注册：

::: code-group

```ts [vite.config.ts]
export default <UserConfig>{
  weapp: {
    autoImportComponents: {
      globs: [
        'components/**/*.wxml',
        'shared/design-system/**/*.wxml',
      ],
    },
  },
}
```

:::

默认规则如下：

* 组件名取决于文件名，且大小写敏感。`HelloWorld.{wxml,ts,json}` 会注册为 `HelloWorld`。
* 如果组件命名为 `index.*`，则使用父级目录名（`HelloWorld/index.wxml → HelloWorld`）。
* 当同一目录下既有 `index.*` 又有同名文件（如 `HelloWorld/index.ts` 与 `HelloWorld/HelloWorld.ts`）时，会优先选用 `index.*` 以保证产物路径稳定。

::: warning
内置组件（`view`、`text`、[`navigation-bar`](https://developers.weixin.qq.com/miniprogram/dev/component/navigation-bar.html) 等）会被自动忽略，避免重复注册。请避免把自定义组件命名成内置组件的名字；忽略列表可在 [`builtin.auto.ts`](https://github.com/weapp-vite/weapp-vite/blob/main/packages/weapp-vite/src/auto-import-components/builtin.auto.ts) 查看。
:::

## 第三方 UI 库自动引入

若项目使用 Vant、TDesign 等 UI 组件库，可以通过 **Resolver** 声明“标签名 → npm 包”之间的映射。`weapp-vite` 默认内置常见解析器，也支持自定义：

::: code-group

```ts [vite.config.ts]
import { TDesignResolver, VantResolver } from 'weapp-vite/auto-import-components/resolvers'

export default <UserConfig>{
  weapp: {
    autoImportComponents: {
      globs: ['components/**/*.wxml'],
      resolvers: [
        VantResolver(),
        TDesignResolver(),
      ],
    },
  },
}
```

:::

配置完成后，就能直接在 `wxml` 中书写 `<van-button>`、`<t-tabs>` 等标签，构建器会自动补全 `usingComponents`。

如果你希望接入自己的组件库（或对第三方库做二次封装），可以参考：[自定义 Resolver（自动导入组件）](/guide/auto-import-resolver)。

## 自动生成的辅助文件

除了运行时的自动注册，`weapp-vite` 还会生成一些辅助产物，帮助你在 IDE 内掌控组件列表。

### 组件清单

默认会在配置文件同级目录输出 `auto-import-components.json`，列出所有自动注册的组件：

```json
{
  "HelloWorld": "/components/HelloWorld/index",
  "Navbar": "/components/Navbar/Navbar",
  "van-button": "@vant/weapp/button"
}
```

你可以通过 `autoImportComponents.output` 自定义保存位置，或传入 `false` 关闭输出：

```ts
export default <UserConfig>{
  weapp: {
    autoImportComponents: {
      globs: ['components/**/*.wxml'],
      output: 'dist/auto-import-components.json',
    },
  },
}
```

### 类型声明与 HTML 自定义数据

* `typedComponents`: 生成 `typed-components.d.ts`，提供 `componentProps`、`ComponentProp` 等类型，方便在脚本中推断组件属性。
* `htmlCustomData`: 生成 `mini-program.html-data.json`，供 VS Code、微信开发者工具读取，实现标签/属性智能提示。

```ts
export default <UserConfig>{
  weapp: {
    autoImportComponents: {
      globs: ['components/**/*.wxml'],
      typedComponents: true, // 或 'types/typed-components.d.ts'
      htmlCustomData: 'dist/mini-program.html-data.json',
    },
  },
}
```

构建器会在组件扫描、resolver 匹配的同一流程中自动刷新这些文件，无需手动触发。

## 常见疑问

* **为什么没自动注册？** 先检查组件 `json` 是否包含 `"component": true`，再确认路径是否命中了 `globs`。修改 `globs` 或新增组件后记得重启 `pnpm dev` 以刷新缓存。
* **Resolver 报错怎么办？** 请确认对应 UI 库的 npm 包已安装，并与 resolver 支持的版本匹配。只想扫描本地组件时，可以临时移除 `resolvers`。
* **如何禁用部分组件？** 结合 `include` / `exclude` 或自定义 resolver 即可实现选择性注册，详见 [自动导入组件配置](/config/auto-import-components.md#weapp-autoimportcomponents)。

---

---
url: /guide/auto-routes.md
description: >-
  Weapp-vite 提供了一个可选的“自动路由”能力：扫描主包/分包的页面目录，自动生成路由清单，并通过虚拟模块
  weapp-vite/auto-routes 导出。
---

# 自动路由（`weapp-vite/auto-routes`）

`weapp-vite` 提供了一个可选的“自动路由”能力：扫描主包/分包的页面目录，自动生成路由清单，并通过虚拟模块 `weapp-vite/auto-routes` 导出。

它解决的核心问题是：**生成一份随目录变化的路由清单**，供 `app.json.ts` 或业务代码消费，同时在 TypeScript 里还能拿到“页面路径”的类型提示，避免字符串写错。

## 适用场景

* 团队遵循约定式目录结构，希望“新增页面 = 自动进清单”，再由 `app.json.ts` 自动组装。
* 希望在 TypeScript 里拿到页面路径的类型提示（少写错、少返工）。
* 想区分主包/分包入口，用于生成导航菜单、埋点清单等数据。

## 快速开启

自动路由默认关闭；如果想启用或做细粒度控制，可以在 `vite.config.ts` 中配置：

```ts
import { defineConfig } from 'weapp-vite'

export default defineConfig({
  weapp: {
    autoRoutes: {
      enabled: true,
      typedRouter: true,
      include: ['pages/**'],
      persistentCache: false,
      watch: true,
    },
  },
})
```

启用后会自动完成以下工作：

* 生成 `typed-router.d.ts`（与配置文件同级），里面包含 `AutoRoutes` 等类型；
* 暴露虚拟模块 `weapp-vite/auto-routes`，默认导出完整路由对象，并额外提供 `entries`、`pages`、`subPackages` 等数组；
* 在开发与构建过程中持续监听页面相关文件，增删改都会立刻刷新清单并触发热更新。

## 默认扫描规则

不传 `include` 时，自动路由不会做“全局 `**/pages/**` 扫描”。

默认行为只有两条：

* 主包：扫描 `srcRoot/pages/**`
* 分包：扫描 **已声明在 `weapp.subPackages` 中的每个 root** 下的 `pages/**`

例如：

```ts
export default defineConfig({
  weapp: {
    srcRoot: 'src',
    autoRoutes: true,
    subPackages: {
      'subpackages/marketing': {},
      'packageA': {},
    },
  },
})
```

这时默认会扫描：

* `src/pages/**`
* `src/subpackages/marketing/pages/**`
* `src/packageA/pages/**`

但不会把下面这些目录误当成页面：

* `src/components/pages/**`
* `src/features/foo/pages/**`，除非你显式把 `features/foo` 声明为分包 root，或通过 `include` 手动放开

这样做的目的是避免把“只是名字里带 `pages` 的目录”误识别成真实页面目录。

> \[!TIP]
> 扫描的“根目录”受 `weapp.srcRoot` 影响：如果你的源码在 `miniprogram/` 或 `src/`，先把 `weapp.srcRoot` 配对（参考 `/config/paths`），再开启自动路由会更顺滑。

如果你只想快速开关，仍然可以继续使用：

```ts
export default defineConfig({
  weapp: {
    autoRoutes: true,
  },
})
```

如果你的目录不是传统的 `pages/**`，也可以手动指定多个 glob / 正则规则：

```ts
export default defineConfig({
  weapp: {
    autoRoutes: {
      enabled: true,
      include: [
        'views/**',
        'pkgA/screens/**',
        /^features\/[^/]+\/screens\/.+$/,
      ],
    },
    subPackages: {
      pkgA: {},
    },
  },
})
```

这里有两个关键点：

* `include` 是按“路由基础路径”匹配的，不需要带文件扩展名；
* 如果分包目录不再沿用 `root/pages/**` 约定，建议同时声明 `weapp.subPackages`，这样自动路由才能把它稳定归入 `subPackages`，而不是主包 `pages`。

## 分包扫描规则

自动路由里的“分包扫描”和“分包归属”是两件事，但它们最好一起配置：

1. 扫描入口：
   `weapp.subPackages` 会告诉自动路由“哪些 root 应该按分包目录处理”。
2. 归属输出：
   命中的页面会被写入 `routes.subPackages`，最终可直接喂给 `defineAppJson({ subPackages })`。

推荐写法：

```ts
export default defineConfig({
  weapp: {
    autoRoutes: true,
    subPackages: {
      'subpackages/marketing': {},
      'subpackages/lab': {
        independent: true,
      },
    },
  },
})
```

对应目录：

* `src/subpackages/marketing/pages/**`
* `src/subpackages/lab/pages/**`

如果你只写了目录、没有声明 `weapp.subPackages`，那在默认规则下这些页面不会自动进入 `routes.subPackages`。这也是为什么现在文档更推荐把“分包 root”显式写到配置里，而不是依赖宽泛目录猜测。

## 监听范围

当自动路由开启后，以下文件会纳入监听：

* 页面脚本：`.js` / `.jsx` / `.ts` / `.tsx` / `.vue`
* 页面模板：`.wxml` 以及 `.vue`
* 页面样式：`.wxss`、`.css`、`.scss`、`.less`、`.sass`、`.styl(us)` 等
* 页面/应用配置：`app.json`、页面 `json`，以及通过 `configExtensions` 声明的扩展后缀

新增或删除这些文件（例如 `pages/foo/index.wxss`、`pages/foo/index.ts`）都会同步更新路由清单。

路由识别规则：

* 默认扫描主包 `pages/**`，以及已声明分包 root 下的 `pages/**`，不会把任意 `**/pages/**` 都视为页面目录；也可以通过 `include` 改成任意 glob / 正则；
* 同一路径下 **只要存在脚本 / 模板 / 配置之一** 即可作为页面；但若 `json.component === true` 会被排除（视为组件）；
* 分包归属优先参考 `weapp.subPackages` 的 root；如果未声明，则回退到传统的 `root/pages/**` 目录约定自动推断。

## 在代码中使用

自动路由模块默认导出 `routes` 对象，包含主包与分包的完整信息，同时提供若干辅助数组方便按需使用：

```ts
import routes, { entries, pages, subPackages, wxRouter } from 'weapp-vite/auto-routes'

console.log(routes.pages) // 主包页面清单
console.log(routes.entries) // 所有入口（主包 + 分包）
console.log(routes.subPackages) // 分包 root 与页面列表
wxRouter.navigateTo({ url: '/pages/index/index' }) // 带路由联合类型提示
```

在 TypeScript 项目中，可以直接引用 `typed-router.d.ts` 生成的类型，获得枚举式的路径提示，例如：

```ts
import type { AutoRoutes } from 'weapp-vite/auto-routes'

function jump(route: AutoRoutes['entries'][number]) {
  wx.navigateTo({ url: route })
}
```

随着文件结构变化，类型声明也会自动刷新，无需手动维护。

`persistentCache` 默认关闭；如果你希望缓存落到自定义位置，也可以直接传字符串路径：

```ts
export default defineConfig({
  weapp: {
    autoRoutes: {
      enabled: true,
      persistentCache: '.cache/auto-routes.json',
    },
  },
})
```

相对路径会基于 `vite.config.*` 所在目录解析；如果没有配置文件路径，则退回到当前工作目录。

如果你在项目里使用 `wevu` 的 `useRouter()/usePageRouter()`，`typed-router.d.ts` 还会自动注入模块增强，让 Router 的 `url` 参数继承自动路由联合类型（同时保留 `./detail`、`../detail` 这类相对路径写法）。

如果你还想让 `switchTab` 类型更严格（只允许 tabBar 页面），可在业务项目里声明合并 `WevuTypedRouterRouteMap.tabBarEntries` 来进一步收窄。

> \[!TIP]
> 如果你的项目需要兼容较低基础库（`Router` 原生对象可能不存在），`wevu` 会回退到全局路由方法（`wx/my/tt`）。这时为保持跨版本一致性，建议在关键跳转优先使用绝对路径（例如 `AutoRoutes['entries'][number]`）。

## 写入 `app.json` 的方式

自动路由不会直接改写纯 JSON 文件。若希望 `app.json` 自动更新，推荐改为脚本配置：

```ts
// app.json.ts
import routes from 'weapp-vite/auto-routes'
import { defineAppJson } from 'weapp-vite/json'

export default defineAppJson({
  pages: routes.pages,
  subPackages: routes.subPackages,
})
```

## 常见问题

* **为什么没有生成路由？**
  * 确认页面文件命中了 `autoRoutes.include` 规则；默认是 `srcRoot/pages/**`，以及已声明分包 root 下的 `pages/**`。
  * 如果页面位于分包目录下，确认对应 root 已经声明在 `weapp.subPackages` 中。
  * 确认页面目录下至少存在脚本 / 模板 / `json` 文件之一，且 `json.component !== true`。
  * 确认 `autoRoutes: true` 已开启。
  * 首次开启后如果没看到变化，重启一次 `pnpm dev`，让监听器重新初始化。
* **如何支持自定义目录结构？** 直接通过 `autoRoutes.include` 配置 glob / 正则即可；如果这些页面属于分包，同时补上 `weapp.subPackages` root，会比依赖目录约定更稳定。
* **`typed-router.d.ts` 要不要提交到仓库？** 它会随构建自动更新，通常建议加入 `.gitignore`；只有在你确实想把类型“固定下来”时再提交。

---

---
url: /guide/auto-import-resolver.md
description: >-
  weapp.autoImportComponents.resolvers 用来把 WXML 里的组件标签（例如 ）解析成小程序
  usingComponents 需要的 from 路径（例如 @vant/weapp/button）。
---

# 自定义 autoImportComponents Resolver

`weapp.autoImportComponents.resolvers` 用来把 WXML 里的组件标签（例如 `<van-button>`）解析成小程序 `usingComponents` 需要的 `from` 路径（例如 `@vant/weapp/button`）。

本文提供一个可直接落地的 Resolver 模板，并说明它会影响哪些能力：

* 自动写入 `usingComponents`
* 生成 `auto-import-components.json`
* 生成 `typed-components.d.ts` / `mini-program.html-data.json`

## Resolver 是什么

Resolver 支持两种写法（推荐对象写法）：

```ts
// 函数写法：返回 { name, from } 或 void
type ResolverFn = (componentName: string, baseName: string) => { name: string, from: string } | void

// 对象写法：提供 components 映射表，或提供 resolve() 方法
interface ResolverObject {
  components?: Record<string, string>
  resolve?: (componentName: string, baseName: string) => { name: string, from: string } | void
  resolveExternalMetadataCandidates?: (from: string) => {
    packageName: string
    dts: string[]
    js: string[]
  } | undefined
}
```

> \[!TIP]
> Weapp-vite 内置的 `VantResolver` / `TDesignResolver` / `WeuiResolver` 也是对象 resolver。自定义 resolver 推荐优先用对象写法：结构更清晰，也更方便提供 `components` / metadata 信息。

* `componentName`: 模板中的标签名（如 `van-button`、`t-tabs`、`HelloWorld`）
* `baseName`: 当前处理的文件名（用于进阶场景：按页面/组件上下文做差异化映射）
* 返回值：告诉 Weapp-vite 把该标签注册到哪个 `from`

## 推荐：对象写法（静态映射）

如果你已经有一份“标签名 → from”的静态表，推荐直接用对象写法（无需写函数逻辑）：

```ts
import type { Resolver } from 'weapp-vite/auto-import-components/resolvers'
import { defineConfig } from 'weapp-vite/config'

const resolver: Resolver = {
  components: {
    'x-button': 'my-ui/button/button',
    'x-dialog': 'my-ui/dialog/dialog',
  },
}

export default defineConfig({
  weapp: {
    autoImportComponents: {
      resolvers: [resolver],
    },
  },
})
```

> \[!TIP]
> 这个实现已经足够让 Weapp-vite 在构建时自动补全 `usingComponents`，并且便于参与 `auto-import-components.json` / `typed-components.d.ts` 等产物生成。

## 建议增强 1：暴露 `resolver.components`（用于“全量生成”）

当你开启 `typedComponents` / `htmlCustomData` 或希望输出的 `auto-import-components.json` 里包含第三方库组件时，建议维护 `resolver.components`：

```ts
import type { Resolver } from 'weapp-vite/auto-import-components/resolvers'

const components = ['button', 'tabs', 'dialog'] as const

const map = Object.fromEntries(
  components.map(name => [`x-${name}`, `my-ui/${name}/${name}`]),
)

export const MyUiResolver: Resolver = {
  components: Object.freeze({ ...map }),
  resolve(componentName) {
    const from = map[componentName]
    if (!from) {
      return
    }
    return { name: componentName, from }
  },
}
```

* `resolver.components` 会被 Weapp-vite 用来收集“该 resolver 支持哪些组件”。
* 如果你只写了动态解析逻辑但没有 `components` 映射，通常仍能自动注册 `usingComponents`，但“全量类型/补全文件”可能无法覆盖到这些组件。

## 建议增强 2：支持第三方组件库 props 类型解析

如果你的 `from` 指向 npm 包（例如 `@vant/weapp/button`），并且希望 Weapp-vite 在生成 `typed-components.d.ts` 时能从第三方库读取 `.d.ts` / `.js` 里的 props 信息，可以实现：

```ts
resolver.resolveExternalMetadataCandidates = (from) => {
  // 命中该 resolver 管理的包时返回候选路径
  return {
    packageName: 'my-ui',
    dts: ['dist/button/index.d.ts'],
    js: ['dist/button/index.js'],
  }
}
```

完整示例（简化版）：

```ts
import type { Resolver } from 'weapp-vite/auto-import-components/resolvers'

const resolver: Resolver = {
  components: {
    'x-button': 'my-ui/button',
  },
  resolve(componentName) {
    const from = componentName === 'x-button' ? 'my-ui/button' : undefined
    if (!from) {
      return
    }
    return { name: componentName, from }
  },
  resolveExternalMetadataCandidates(from) {
    if (!from.startsWith('my-ui/')) {
      return
    }
    const component = from.slice('my-ui/'.length)
    if (!component) {
      return
    }
    return {
      packageName: 'my-ui',
      dts: [`dist/${component}/index.d.ts`],
      js: [`dist/${component}/index.js`],
    }
  },
}
```

> \[!NOTE]
> `resolveExternalMetadataCandidates` 的目标不是“让组件能被解析”，而是“告诉 Weapp-vite 到第三方依赖包里去哪里找 metadata 文件”，用于类型与补全产物。

## 进阶：函数写法（按需动态解析）

如果你需要按上下文动态解析（例如同一个标签在不同页面映射不同 `from`），可以使用函数写法：

```ts
import type { Resolver } from 'weapp-vite/auto-import-components/resolvers'

export function DynamicResolver(): Resolver {
  return (componentName, baseName) => {
    if (componentName !== 'x-button') {
      return
    }
    const from = baseName.includes('admin')
      ? 'my-ui-admin/button/button'
      : 'my-ui/button/button'
    return { name: componentName, from }
  }
}
```

## 参考实现

* `weapp-vite` 内置 Resolver：`VantResolver`、`TDesignResolver`、`WeuiResolver`
* 配置入口：[`weapp.autoImportComponents`](/config/auto-import-components.md#weapp-autoimportcomponents)

---

---
url: /llms.md
description: 兼容入口（/llms），与 /ai 共享同一套 AI 学习页面（含 MCP 接入指引）。
---


---

---
url: /guide/debug.md
description: 这份指南面向想要参与 Weapp-vite 开发或排查源码问题的伙伴。按照下面的步骤准备环境，就可以在本地命中断点、验证修改，并把贡献发送到社区。
---

# 调试与贡献

这份指南面向想要参与 `weapp-vite` 开发或排查源码问题的伙伴。按照下面的步骤准备环境，就可以在本地命中断点、验证修改，并把贡献发送到社区。

## 1. Fork 与克隆仓库

1. 登录 GitHub，访问 [`weapp-vite`](https://github.com/weapp-vite/weapp-vite) 仓库。
2. 点击右上角 **Fork**（或直接访问 [快捷链接](https://github.com/weapp-vite/weapp-vite/fork)），选择目标账号并命名仓库。
3. 完成后，在本机克隆你自己的 Fork：

```sh
git clone https://github.com/<your-name>/weapp-vite.git
cd weapp-vite
```

> \[!TIP]
> 首次 Fork 后建议添加上游仓库，后续可以方便地同步最新改动：
>
> ```sh
> git remote add upstream https://github.com/weapp-vite/weapp-vite.git
> ```

## 2. 安装依赖并准备调试

1. `package.json` 中记录了推荐的包管理器版本，例如：
   ```json
   {
     "packageManager": "pnpm@9.7.1"
   }
   ```
   建议执行 `corepack enable`，确保使用与仓库一致的工具链。
2. 在仓库根目录安装依赖：
   ```sh
   pnpm install
   ```
3. 仓库内的 `apps/` 目录准备了多个演示项目（`vite-native`、`vite-native-skyline` 等），可以任选一个作为调试入口。
4. VS Code 用户可以直接使用仓库内置的 `.vscode/launch.json`，也可以在“调试和运行”面板选择需要的配置，一键启动并命中 TypeScript 源码断点。

![VS Code 调试配置示例](../images/vscode-debug.png)

> \[!NOTE]
> 如果你更喜欢终端调试，也可以运行 `pnpm --filter apps/vite-native dev` 再配合浏览器/IDE 附加调试，会同样命中源码断点。

## 3. 提交贡献

1. 在本地创建分支并完成改动，写好测试或文档：
   ```sh
   git checkout -b fix/my-change
   pnpm lint --filter ...
   pnpm test --filter ...
   ```
2. 提交后推送到自己的 Fork：
   ```sh
   git push origin fix/my-change
   ```
3. 打开仓库的 **Pull requests** 页面，点击 **New pull request**，选择你的分支 → 上游 `main`。
4. 在 PR 模板中说明动机、做了哪些验证，并附上截图或日志（如果适用）。

提交后维护者会安排 Review，并和你沟通改进建议。PR 合并后，你的改动就会进入 Weapp-vite 的主线版本。

> \[!TIP]
> 想持续参与社区？欢迎在 Issue 区挑选 `good first issue`、`help wanted` 标签的任务，也可以加入讨论区提出想法。

---

---
url: /migration.md
description: 迁移，聚焦 migration / index 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 迁移

1. [从原生小程序迁移到 Weapp-vite / Wevu](../wevu/migration/from-native-to-vue-sfc.md)
2. [从 v5 升级到 v6](./v6.md)
3. [从 v4 升级到 v5](./v5.md)
4. [从 v3 升级到 v4](./v4.md)
5. [从 v2 升级到 v3](./v3.md)

---

---
url: /wevu/runtime.md
description: 介绍 Wevu 运行时的桥接机制、生命周期映射与 setData 更新策略，并给出定位“未触发/未更新”问题的实操方法。
---

# 运行时与生命周期

本页主要说明 Wevu 运行时做了什么、哪些生命周期可用，以及常见的“为什么没触发/为什么没更新”的定位思路。

Wevu 运行时的核心职责是：

* 把 `data/computed/methods/setup/watch` 等选项桥接到小程序 `Component() / App()`；
* 将 state + computed 生成快照（plain object），diff 后只下发变化路径到 `setData()`；
* 提供生命周期钩子与 `bindModel()` 等小程序友好能力。

:::tip 导入约定
所有 API 都从 `wevu` 主入口导入。
:::

## 更新链路：为什么 Wevu 不需要 Virtual DOM

Wevu 的渲染心智模型更接近“小程序原生”：

1. 你在 `setup()` 中创建响应式 state（`ref/reactive`）与 `computed`
2. 运行时把 **state + computed** 转成 **plain snapshot**（可序列化的普通对象）
3. 每次调度时对比“上一次 snapshot vs 新 snapshot”
4. 只把变化路径组装成 `setData({ 'a.b.c': next })` 的形式下发

这也是为什么你会看到一些“小程序语义”对行为有硬性影响：

* 小程序 `created` 阶段不能调用 `setData`：Wevu 会缓冲由响应式更新产生的 `setData`，并在首次安全时机（组件 `attached` / 页面 `onLoad`）统一 flush（细节见 `/wevu/component`）。
* 小程序模板只能消费 JSON 友好的数据：`undefined` 会被归一化（通常变成 `null`），不要依赖“模板里区分 undefined 与缺失字段”的行为（见 `/wevu/compatibility`）。

## defineComponent：注册页面/组件

`defineComponent(options)` 会直接调用全局 `Component()` 完成注册（页面和组件都走 `Component()`，这是 Wevu 的统一模型）。

```ts
import { defineComponent, onShow, ref } from 'wevu'

export default defineComponent({
  // 原生小程序字段保持原样（properties、options、lifetimes、pageLifetimes...）
  properties: { initial: { type: Number, value: 0 } },

  setup(props) {
    const count = ref(props.initial ?? 0)
    onShow(() => console.log('show'))
    return { count, inc: () => count.value++ }
  },
})
```

`defineComponent` 的 `data` 必须是函数（与 Vue 3 一致，和小程序原生对象写法不同）。原生小程序会在实例化时拷贝 `data` 对象以隔离实例；Wevu 需要为每个实例创建独立的响应式 state/代理与快照 diff，因此要求返回新对象。

:::warning 运行环境
`defineComponent()` 依赖小程序运行时提供的全局 `Component()`；在 Node/Vitest 等环境运行时请自行 stub。
:::

### props / properties

Wevu 同时支持两种 props 定义方式：

* 小程序原生 `properties`：完全按小程序规范书写，`setup(props, ctx)` 通过 `props`/`ctx.props` 读取。
* Vue 风格 `props`：会被转换为小程序 `properties`（支持 `type`、`optionalTypes`、`observer` 与 `default` / `value`）。

如果你使用 Weapp-vite 的 SFC 编译产物，通常会走 `createWevuComponent(options)`（见下节），并直接携带小程序 `properties`。

#### defineProps 泛型到 properties 的映射

`<script setup>` 的 `defineProps<T>()` 会先被 Vue 编译器推导成 runtime `props`，再由 Wevu 归一化为小程序 `properties`。

归一化规则（对齐小程序 `properties` 约束）：

* `type` 只保留一个主类型（`String/Number/Boolean/Object/Array` 或 `null`）
* 若存在多个可用类型，其余类型写入 `optionalTypes: []`
* 非小程序原生类型（如 `Date/Map/Set`）会被过滤；若全部不可用则降级为 `type: null`
* `required` 仅存在于 Vue runtime `props`，不会出现在小程序 `properties`

常见映射示例：

| defineProps 泛型             | Vue runtime props（编译后）               | Wevu 归一化后 `properties`              |
| ---------------------------- | ----------------------------------------- | --------------------------------------- |
| `mixed: string \| number`    | `type: [String, Number], required: true`  | `type: String, optionalTypes: [Number]` |
| `opt?: 'a' \| 'b'`           | `type: String, required: false`           | `type: String`                          |
| `opt?: 'a' \| 'b' \| number` | `type: [String, Number], required: false` | `type: String, optionalTypes: [Number]` |
| `opt?: Date \| string`       | `type: [Date, String], required: false`   | `type: String`（`Date` 被过滤）         |
| `opt?: Date`                 | `type: Date, required: false`             | `type: null`                            |

> 注意：`'a' \| 'b'` 这类字面量联合在 runtime 层会被收敛为 `String`，不会保留枚举约束。

### createWevuComponent（供编译产物调用）

`createWevuComponent(options)` 是 `defineComponent()` 的兼容入口，主要用于 Weapp-vite 生成的组件代码调用；它会保留小程序 `properties` 定义并完成组件注册。

## 全局默认值（setWevuDefaults / resetWevuDefaults） {#wevu-defaults}

当你希望统一控制 `createApp`/`defineComponent` 的默认行为时，可以设置全局默认值：

```ts
import { resetWevuDefaults, setWevuDefaults } from 'wevu'

setWevuDefaults({
  app: {
    setData: {
      includeComputed: false,
    },
  },
  component: {
    options: {
      addGlobalClass: true,
    },
  },
})

// 测试或热更新时可重置
resetWevuDefaults()
```

规则说明：

* `app` 影响 `createApp()`；`component` 影响 `defineComponent()`/`createWevuComponent()`。
* 运行时会合并默认值与局部选项：`setData`/`options` 会做浅合并，其余字段按对象顶层覆盖。
* 必须在 `createApp()`/`defineComponent()` 之前调用；不会 retroactive 影响已创建的实例。

### `setData.highFrequencyWarning`（开发态高频告警）

* 默认关闭（`undefined` 不启用）。
* 当启用 `weapp.wevu.preset: 'performance'` 时，会自动注入 `highFrequencyWarning: { enabled: true, devOnly: true }`。
* 开启后会额外检测 `onPageScroll` 回调中的 `setData` 调用，并输出专项告警（默认 `warnOnPageScroll: true`），引导你改用 `IntersectionObserver` 或节流。
* 你也可以手动开启并调整阈值：

```ts
import { setWevuDefaults } from 'wevu'

setWevuDefaults({
  component: {
    setData: {
      highFrequencyWarning: {
        enabled: true,
        devOnly: true,
        sampleWindowMs: 1000,
        maxCalls: 30,
        coolDownMs: 5000,
        warnOnPageScroll: true,
        pageScrollCoolDownMs: 2000,
      },
    },
  },
})
```

### 收到内存告警时的清理建议

`wevu` 支持在 `App setup` 中通过 `onMemoryWarning()` 监听系统内存告警（底层基于 `wx.onMemoryWarning`）：

```ts
import { onMemoryWarning } from 'wevu'

onMemoryWarning(() => {
  // 释放大缓存 / 取消不必要订阅 / 回收临时对象
})
```

建议把“大对象缓存回收”放到该回调中统一处理，避免页面切换后仍长期占用内存。

### 在 app.vue 顶层手动调用

如果你不使用 `weapp.wevu.defaults`，可以在 `app.vue` 顶层直接调用：

```vue
<script setup lang="ts">
import { setWevuDefaults } from 'wevu'

setWevuDefaults({
  component: {
    options: {
      addGlobalClass: true,
    },
  },
})
</script>
```

> 关键点：必须是**顶层语句**（不要放进 `setup()`/hook 里），这样才能早于 `createApp()` 执行。

> \[!TIP]
> 使用 Weapp-vite 时，可以通过 `weapp.wevu.defaults` 在编译期自动注入 `setWevuDefaults()`（见 `/config/shared#weapp-wevu-defaults`）。

## setup：签名与上下文

`setup` 与 Vue 3 对齐，仅支持 `setup(props, ctx)` 签名。
若不需要 `props`，可使用 `setup(_, ctx)`；若不需要 `ctx`，可只写 `setup(props)`。

其中 `props` / `ctx.props` 来自小程序实例的 `properties`（页面通常为空对象）。

`ctx`（关键字段）：

* `ctx.runtime`：运行时实例（暴露 `bindModel` / `watch` / `snapshot` / `unmount` 等）
* `ctx.state`：响应式 state（包含 `data()` 与 `setup()` 返回的非函数值）
* `ctx.proxy`：公开实例代理（也是 `methods/computed` 的 `this`）
* `ctx.emit(event, ...args)`：触发自定义事件（内部调用 `triggerEvent`）
* `ctx.bindModel(path, options?)`：创建模型绑定（见下文）
* `ctx.watch(source, cb, options?)`：等价于 `ctx.runtime.watch`
* `ctx.instance`：小程序原生实例（高级/调试用途）

:::warning 同步调用约束
生命周期钩子必须在 `setup()` **同步执行阶段**调用，否则会抛错。
:::

## 生命周期钩子

### 通用钩子（页面/组件）

* `onShow` / `onHide` / `onReady` / `onUnload`

### 组件钩子（来自 lifetimes/pageLifetimes）

* `onMoved`（`lifetimes.moved`）
* `onError`（`lifetimes.error`）
* `onResize`（`pageLifetimes.resize`，组件场景）

### 页面钩子（Page 事件）

* `onPullDownRefresh`
* `onReachBottom`
* `onPageScroll`
* `onRouteDone`
* `onTabItemTap`
* `onResize`（页面场景）
* `onShareAppMessage`
* `onShareTimeline`
* `onAddToFavorites`

注意：分享/朋友圈/收藏是否触发由微信官方机制决定（例如右上角菜单/`open-type="share"`；朋友圈通常需配合 `wx.showShareMenu()` 开启菜单项）。
此外，小程序会对部分页面事件做“按需派发”：只有定义了对应页面方法，事件才会从渲染层派发到逻辑层；Wevu 也仅在你定义了这些页面方法时才桥接 `setup()` 中注册的同名 hooks。
如果你使用 Weapp-vite 构建，默认会在编译阶段根据你是否调用 `onPageScroll/onShareAppMessage/...` 自动补齐对应 `features.enableOnXxx = true`，以降低手动配置成本。

### 返回值型钩子（单实例）

以下钩子按“单实例”注册（后注册覆盖先注册），并允许返回值：

* `onSaveExitState`
* `onShareAppMessage`
* `onShareTimeline`
* `onAddToFavorites`

### Vue 风格别名（语义对齐为主）

* `onMounted` → `onReady`
* `onUnmounted` → `onUnload`
* `onActivated` → `onShow`
* `onDeactivated` → `onHide`
* `onErrorCaptured` → `onError`
* `onBeforeMount` / `onBeforeUnmount`：在 `setup()` 同步阶段立即执行（小程序无精确对应时机）
* `onBeforeUpdate` / `onUpdated`：在每次 `setData` 前/后触发（小程序没有“更新生命周期”，Wevu 通过在更新链路里补齐语义）

## bindModel：模型绑定

`ctx.bindModel(path, options?)` 返回一个 `ModelBinding`：

* `binding.value` / `binding.update(value)`：读取或更新目标路径
* `binding.model(modelOptions?)`：生成事件 handler / value 字段（默认 `value` + `onInput`）

```ts
// setup(props, ctx) 内
const { model } = ctx.bindModel('form.price', {
  event: 'blur',
  formatter: v => Number(v) || 0,
})
const onPriceBlur = model().onBlur
```

```vue
<input :value="form.price" @blur="onPriceBlur" />
```

在 `<script setup>` 里可以用 `useBindModel()` 获取同一个能力，避免直接访问内部实例：

```ts
import { useBindModel } from 'wevu'

const bindModel = useBindModel()
const onPriceChange = bindModel<number>('form.price').model({ event: 'change' }).onChange
```

```vue
<t-input :value="form.price" @change="onPriceChange" />
```

默认解析器会优先取 `event.detail.value`，其次取 `event.target.value`；你也可以通过 `parser` 自定义解析逻辑。

> 注意：Weapp-vite 模板编译目前不支持 `v-bind="object"` 的对象展开语法（不会生成任何属性），建议使用显式 `:value` + `@change/@input` 绑定。

## watch：组合式与选项式

### 组合式 watch

`watch()` / `watchEffect()` 与 Vue 3 类似，调度使用微任务队列；`deep` 默认采用“版本信号”策略（只订阅根版本号，不做深层遍历）：

```ts
import { setDeepWatchStrategy } from 'wevu'

setDeepWatchStrategy('traverse')
```

watch 返回的 stop handle 兼容旧写法，同时支持 `pause / resume` 暂停与恢复监听：

```ts
const { pause, resume, stop } = watch(() => state.form, () => {
  // handle changes
})

pause() // 暂停监听（避免同步循环）
resume() // 恢复监听
stop() // 停止监听
```

## 批处理：batch / startBatch / endBatch

当你需要在一次交互中同步修改很多字段（尤其是大列表、复杂表单）时，可以显式批处理以减少调度与 diff 次数：

```ts
import { batch, endBatch, ref, startBatch } from 'wevu'

const a = ref(0)
const b = ref(0)

batch(() => {
  a.value += 1
  b.value += 1
})

startBatch()
a.value += 1
b.value += 1
endBatch()
```

一般情况下不需要手动 batch：Wevu 默认会在微任务中批量调度，但“同一 tick 内修改非常多字段”的场景，显式批处理更稳定。

### 选项式 watch（defineComponent/watch）

`defineComponent({ watch: { 'a.b': descriptor } })` 支持点路径表达式与三种描述符：

* 函数：`watch: { count(n, o) {} }`
* 方法名：`watch: { count: 'onCountChange' }`
* 对象：`watch: { count: { handler: 'onCountChange', immediate: true, deep: true } }`

## Provide / Inject

* `provide(key, value)` / `inject(key, defaultValue?)`：优先读写“当前实例”的 provide 域，找不到会回落到全局存储
* `provideGlobal` / `injectGlobal`：显式的全局读写（组件外调用场景）

:::warning 重要限制
当前版本没有组件树父子指针，`inject()` 不会向上查找“祖先组件”；组件内注入只能命中“当前实例提供的值”，否则回落到全局存储。
:::

## createApp：应用运行时与插件

`createApp(options)` 创建运行时，并在检测到全局 `App()` 时自动完成应用注册；插件通过 `app.use()` 安装：

```ts
import { createApp } from 'wevu'

const app = createApp({ data: () => ({}) })
app.use((runtime) => {
  runtime.config.globalProperties.$log = (...args: any[]) => console.log(...args)
})
```

`app.config.globalProperties` 会注入到公开实例 `proxy`，可通过 `this.$log`（或 `ctx.proxy.$log`）访问。

## 在测试环境使用（Vitest/Node）

Wevu 的 `defineComponent()` 依赖全局 `Component()`（以及部分小程序实例方法）。在 Vitest/Node 环境测试时，通常有两条路：

* 把业务逻辑下沉到纯函数/composable/service，避免直接依赖小程序构造器（最推荐）
* 对测试用例 stub 全局 `Component` 并断言注册参数（只测“桥接层”）

示例（只展示思路）：

```ts
import { expect, test, vi } from 'vitest'
import { defineComponent } from 'wevu'

test('defineComponent registers Component()', () => {
  const Component = vi.fn()
  // @ts-expect-error test stub
  globalThis.Component = Component

  defineComponent({ setup: () => ({}) })
  expect(Component).toHaveBeenCalledTimes(1)
})
```

---

---
url: /blog/release1_7.md
description: >-
  这段时间 Weapp-vite 的功能更新与优化，聚焦 blog / release1_7 相关场景，覆盖 Weapp-vite 与 Wevu
  的能力、配置和实践要点。
---

![bg](/1.7.x-release.png)

# 这段时间 `weapp-vite` 的功能更新与优化

自从上次宣布 `weapp-vite` 的发布，已经过去三个月；`weapp-vite` 也逐渐迭代至 `1.7.6` 版本。

在此期间，我对其进行了多项功能的增强和优化，接下来我将为大家详细介绍近期的阶段性成果。

> 下面列出的功能皆为增强特性，开发者可自由选择启用或关闭，不影响原生小程序的兼容性。

## 核心功能更新

### 1. 自动构建 `npm`

在项目启动时，`weapp-vite` 会自动构建 `npm` 依赖，无需再手动点击微信开发者工具中的 构建 `npm`，提升了一定程度的开发体验。

详细信息请参考：[自动构建 npm 文档](https://vite.icebreaker.top/guide/npm.html)。

### 2. 语法增强

#### 2.1 `JSON` 文件增强

##### 1. 支持注释

`weapp-vite` 支持在项目中的 `JSON` 文件中添加注释。例如：

```jsonc
{
  /* 这是一个组件 */
  "component": true,
  "styleIsolation": "apply-shared",
  "usingComponents": {
    // 导航栏组件
    "navigation-bar": "@/navigation-bar/navigation-bar"
  }
}
```

这些注释会在最终产物内被去除。

> **注意：** `project.config.json` 和 `project.private.config.json` 不支持注释，因为这些文件直接由微信开发者工具读取。

##### 2. 智能提示

我生成了许多小程序的 `$schema` 文件，部署在 `vite.icebreaker.top` 上。

通过指定 `JSON` 的 `$schema` 字段，实现了配置文件的智能提示功能，优化了一点点开发体验。

![vscode-json-intel](/vscode-json-intel.png)

详见：[JSON 配置文件的智能提示](https://vite.icebreaker.top/guide/json-intelli-sense.html)。

##### 3. 别名支持

可以在 `vite.config.ts` 中配置 `jsonAlias.entries` 字段, 在 `usingComponents` 中使用别名定义路径，这些在构建时会自动转化为相对路径。

例如:

```ts
import type { UserConfig } from 'weapp-vite/config'
import path from 'node:path'

export default <UserConfig>{
  weapp: {
    jsonAlias: {
      entries: [
        {
          find: '@',
          replacement: path.resolve(import.meta.dirname, 'components'),
        },
      ],
    },
  },
}
```

那么就可以在 `json` 中这样编写:

```json
{
  "usingComponents": {
    "navigation-bar": "@/navigation-bar/navigation-bar",
    "ice-avatar": "@/avatar/avatar"
  }
}
```

构建结果：

```json
{
  "usingComponents": {
    "navigation-bar": "../../components/navigation-bar/navigation-bar",
    "ice-avatar": "../../components/avatar/avatar"
  }
}
```

##### 4. 编程支持

`weapp-vite` 支持使用 `JS/TS` 文件来编写 `JSON`，你需要将 `component.json` 更改为 `component.json.ts`：

> 智能提示定义 `API` 都在 `weapp-vite/json` 中导出

比如普通写法:

```ts
import { defineComponentJson } from 'weapp-vite/json'

export default defineComponentJson({
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
})
```

还支持引入异步数据、编译时变量或其他文件：

```ts
import type { Page } from 'weapp-vite/json'
import fs from 'node:fs/promises'
import path from 'node:path'
import shared0 from '@/assets/share'
import shared1 from './shared.json'

console.log('import.meta.env: ', import.meta.env)
console.log('import.meta.dirname: ', import.meta.dirname)
console.log('PLATFORM: ', import.meta.env.PLATFORM)
console.log(import.meta.env.DEV, import.meta.env.MODE, import.meta.env.PROD)
const key = await fs.readFile(
  path.resolve(import.meta.dirname, 'x.txt'),
  'utf8'
)

export default <Page>{
  usingComponents: {
    't-button': 'tdesign-miniprogram/button/button',
    't-divider': 'tdesign-miniprogram/divider/divider',
    'ice-avatar': '@/avatar/avatar',
  },
  ...shared0,
  ...shared1,
  key,
}
```

#### 2.2 `WXML` 文件增强

##### 事件绑定语法糖

`weapp-vite` 借鉴了 `Vue` 的事件绑定风格，为 `WXML` 增加了事件绑定语法糖：

这里我们以最常用的 `tap` 事件为例:

```html
<!-- 原始代码 -->
<view @tap="onTap"></view>
<!-- 编译后 -->
<view bind:tap="onTap"></view>
```

支持的事件绑定增强规则如下：

| 源代码                                      | 编译结果            |
| ------------------------------------------- | ------------------- |
| `@tap`                                      | `bind:tap`          |
| `@tap.catch`                                | `catch:tap`         |
| `@tap.mut`                                  | `mut-bind:tap`      |
| `@tap.capture`                              | `capture-bind:tap`  |
| `@tap.capture.catch` / `@tap.catch.capture` | `capture-catch:tap` |

详见：[事件绑定增强文档](https://vite.icebreaker.top/guide/wxml.html)。

这部分还能做的更多，欢迎与我进行讨论！

#### 2.3 `WXS` 增强

##### 编程支持（实验性）

`weapp-vite` 为 `WXS` 提供了 `JS/TS` 编程支持，支持通过更改 `wxs` 后缀为 `wxs.js` 或 `wxs.ts` 文件定义逻辑：

比如 `index.wxs.ts`:

```ts
export const foo = '\'hello world\' from hello.wxs.ts'

export const bar = function (d: string) {
  return d
}
```

另外内联 `WXS` 也支持使用 `lang="js"` 或 `lang="ts"` 直接启用编译功能:

```html
<view>{{test.foo}}</view>
<view @tap="{{test.tigger}}">{{test.abc}}</view>

<wxs module="test" lang="ts">
const { bar, foo } = require('./index.wxs.js')
const bbc = require('./bbc.wxs')
export const abc = 'abc'

export function tigger(value:string){
  console.log(abc)
}

export {
  foo,
  bar,
  bbc
}
</wxs>
```

详情请参考：[Wxs 增强](https://vite.icebreaker.top/guide/wxs.html)。

### 3. 生成脚手架

`weapp-vite` 内置了生成脚手架工具，可快速生成一系列文件（如 `js`、`wxml`、`wxss` 和 `json`），用于提升开发效率。

最基础的用法只需要 `weapp-vite g [outDir]`

详情请参考：[生成脚手架文档](https://vite.icebreaker.top/guide/generate.html)。

### 4. 分包支持

针对普通分包和独立分包的加载需求进行了优化，用户几乎无需额外配置即可实现分包加载。

尤其是独立分包的场景，创建了独立的编译上下文。

详情请参考：[分包指南](https://vite.icebreaker.top/guide/subpackage.html)。

## 不忘初心，持续改进

`weapp-vite` 的初衷是实现对原生小程序的增强，现有原生小程序几乎可以零成本地迁移过来，并享受更高效的开发体验。

在此，希望各位开发者试用，欢迎反馈与参与。

如果您对文中的任何功能或增强有疑问、建议，欢迎到  [Github Discussions](https://github.com/weapp-vite/weapp-vite/discussions) 提出讨论！

---

---
url: /deep/config-service.md
description: >-
  想在 Weapp-vite 中扩展配置加载或贡献新能力？这一页梳理了配置服务的核心文件，帮助你快速定位到对应模块。即便不准备修改源码，也能借此了解
  defineConfig 背后的执行流程。
---

# 配置服务内部结构

想在 Weapp-vite 中扩展配置加载或贡献新能力？这一页梳理了配置服务的核心文件，帮助你快速定位到对应模块。即便不准备修改源码，也能借此了解 `defineConfig` 背后的执行流程。

## createConfigService.ts

* 位置：`packages/weapp-vite/src/runtime/config/createConfigService.ts`
* 负责初始化配置状态、导出 `ConfigService` 对外 API，并将内部工具组合在一起。
* 统一维护 `defineEnv`、包管理器信息以及路径相关的辅助方法。

## internal/alias.ts

* 负责维护与注入内置别名，保证 `@oxc-project/runtime` 与内置依赖能被正确解析。
* 提供 `createAliasManager`，供配置加载与合并阶段复用。

## internal/loadConfig.ts

* 专注从用户工程、weapp 配置文件与默认设置中生成最终的 `InlineConfig`。
* 同时处理增强迁移、`rolldown` 插件注入以及输出后缀推导等逻辑。

## internal/merge.ts

* 抽离运行时合并逻辑，包含 `mergeWorkers`、`merge`、`mergeWeb` 与 `mergeInlineConfig`。
* 对运行平台做统一的环境标记，并复用别名处理能力。

通过以上拆分，`createConfigService.ts` 体积控制在 300 行以内，同时文档化了各模块职责，方便在需要扩展配置时快速定位到对应实现。想进一步了解实际代码，可直接浏览仓库中的实现并结合调试能力（`weapp.debug.inspect`）验证行为。

---

---
url: /config.md
description: >-
  Weapp-vite 使用 **Vite 配置模型**：在 vite.config.ts 中增加一个 weapp 字段即可。你也可以把小程序专属配置拆到
  weapp-vite.config.*，两者会合并。
---

# 配置概览 {#config-overview}

`weapp-vite` 使用 **Vite 配置模型**：在 `vite.config.ts` 中增加一个 `weapp` 字段即可。你也可以把小程序专属配置拆到 `weapp-vite.config.*`，两者会合并。

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

export default defineConfig({
  // 这里依然可以写任意 Vite 配置
  weapp: {
    // 小程序专属配置写在这里
  },
})
```

> \[!NOTE]
> 配置文件以 **ESM** 方式执行。若需要绝对路径，推荐使用 `import.meta.dirname`（本仓库与脚手架默认提供）或 `fileURLToPath(import.meta.url)`。

> \[!TIP]
> 你可以额外创建 `weapp-vite.config.ts`（或 `.mts/.cts/.js/.mjs/.cjs/.json`）。`weapp-vite` 会先读取其中的 `weapp` 配置，再与 `vite.config.*` 合并，便于把「小程序配置」与「通用 Vite 配置」分开维护。

\[\[toc]]

## 你最可能先要改的 3 项

1. **源码目录**：`app.json` 不在根目录时，先配 [`weapp.srcRoot`](./paths.md#weapp-srcroot)。
2. **输出目录**：由 `project.config.json` 的 `miniprogramRoot` 决定，详见 [构建输出与兼容](./build-and-output.md)。
3. **自动导入组件**：默认已开启（扫描 `components/**/*.wxml`），详见 [自动导入组件配置](./auto-import-components.md)。

## 配置索引

| 主题 | 内容概览 |
| --- | --- |
| [基础目录与资源收集](./paths.md) | `srcRoot` / `pluginRoot` / 静态资源拷贝 / 预留字段 |
| [构建输出与兼容](./build-and-output.md) | `jsFormat` / `es5` / `multiPlatform` / 输出目录推导 |
| [JSON 配置](./json.md) | `jsonAlias` / JSON 默认值 / 合并策略 |
| [JS 配置](./js.md) | `tsconfigPaths`（vite-tsconfig-paths） |
| [Vue SFC 配置](./vue.md) | `weapp.vue.template` 模板编译与 class/style 运行时 |
| [分包配置](./subpackages.md) | 独立/普通分包、`inlineConfig`、共享样式 |
| [Worker 配置](./worker.md) | Worker 入口与构建输出 |
| [库模式配置](./lib.md) | `weapp.lib` 入口、路径保持、组件 JSON 与 DTS |
| [生成脚手架配置](./generate.md) | `weapp.generate` 目录结构、后缀与模板定制 |
| [npm 配置](./npm.md) | 自动/手动构建、主包/分包依赖落位、缓存与优化 |
| [WXML 配置](./wxml.md) | WXML 扫描与模板处理行为 |
| [WXS 配置](./wxs.md) experimental | WXS 处理与调试建议 |
| [自动导入组件配置](./auto-import-components.md) | `weapp.autoImportComponents` 字段与产物输出 |
| [共享配置](./shared.md) | 自动路由、Wevu 默认值、`injectWeapi`、日志、HMR 与 chunk |
| [Web 运行时配置](./web.md) experimental | `weapp.web` 浏览器端预览与调试 |

> 仍在寻找 Vite 原生配置？可直接参考 [Vite 官方配置文档](https://cn.vitejs.dev/config/)。

***

如果你不确定从哪里开始，建议先看 **基础目录与资源收集** 和 **构建输出与兼容** 两页。

---

---
url: /blog/release6-principles.md
description: 这篇文档不是功能清单，而是 Weapp-vite@6 在实现 Vue SFC 支持时的一份技术复盘，重点记录编译链路、运行时更新路径和关键取舍。
---

![Weapp-vite 6 顶部海报](/6/bg.jpg)

# 重走 Vue 长征路 Weapp-vite：编译链路与 Wevu 运行时原理拆解

书接上篇

我当时在团队里做[《Vue 编译本质论》](https://deep-in-vue.icebreaker.top/)分享，正好把一些判断过程也整理了下来：为什么这么做，没选什么，以及这些取舍在小程序里到底值不值。

如果你更关心怎么上手，先看发布文会更顺：[`Weapp-vite：原生模式之外，多一种 Vue SFC 选择`](/blog/release6)。

## 先把边界说清：Wevu 不是 Vue 3 的搬运工

Wevu 用起来确实很像 Vue 3，但骨子里不是一回事。

| 对比维度   | Vue 3                      | Wevu                      |
| :--------- | :------------------------- | :------------------------ |
| 运行环境   | Web 浏览器                 | 微信小程序                |
| 响应式系统 | Proxy + effect             | Proxy + effect（同源）    |
| 渲染目标   | DOM 节点                   | 小程序页面/组件实例       |
| 渲染方式   | Virtual DOM Diff → DOM API | Snapshot Diff → `setData` |
| 数据模型   | VNode 树                   | 纯 JS 对象快照            |
| 更新机制   | 异步调度 + DOM 操作        | 异步调度 + `setData`      |
| 生命周期   | onMounted/onUpdated 等     | 映射到小程序生命周期      |
| 事件系统   | DOM 事件                   | 小程序 bind/catch 事件    |
| SFC 编译   | @vitejs/plugin-vue         | Weapp-vite 内置           |

说白了就一件事：**响应式 API 长得一样，但最后数据往哪送、怎么送，完全不同**。

## API 为什么能"几乎同写法"

`ref`、`computed`、`watch` 这些在 wevu 里跟 Vue 3 写法一模一样，没必要再造一套 DSL 出来。

```ts
import { computed, ref, watch } from 'wevu'

const count = ref(0)
const doubled = computed(() => count.value * 2)

watch(count, (val) => {
  console.log('count changed:', val)
})
```

很多团队迁过来之后第一反应不是"又要学新东西"，而是"这不就是我平时写的吗，换了个宿主而已"。

## 渲染链路才是真正不一样的地方

Vue 3 走的是这条路：

```text
状态变化 -> effect 触发 -> 组件更新 -> VNode Diff -> DOM 操作
```

Wevu 走的是这条：

```text
状态变化 -> effect 触发 -> 快照 Diff -> setData -> 小程序渲染
```

Wevu 干的事情说穿了就是把"算出哪些东西变了"这一步尽量提前做完，等到真正调 `setData` 的时候，payload 已经被压到最小了。这在小程序里特别关键——大家踩过坑的都知道，`setData` 传多了，页面就卡，尤其是列表页。

## `.vue` 到四件套：编译阶段干了啥

一个 `MyComponent.vue` 最终会变成小程序四件套：

```text
MyComponent.vue
  ├─> MyComponent.js
  ├─> MyComponent.wxml
  ├─> MyComponent.wxss
  └─> MyComponent.json
```

中间的流程大概是这样：先把 SFC 拆成四块——`<script>`、`<template>`、`<style>`、`<json>`，各自按小程序的规矩做转换，最后拼成产物。

其中 `<json>` 块用来声明页面或组件的配置（比如 `usingComponents`、`navigationBarTitleText` 之类的），不过我更推荐用 `definePageJson` / `defineComponentJson` / `defineAppJson` 这几个编译宏来代替它——有类型提示，能跟 `<script setup>` 共享上下文，IDE 重构的时候也不容易漏改。`<json>` 块当兼容手段用没问题，但不太适合当主力。

```text
.vue 文件
  ↓
vue/compiler-sfc 解析
  ↓
┌─────────┬──────────┬─────────┬────────┐
│ <script>│<template>│ <style> │ <json> │
└────┬────┴────┬─────┴────┬────┴───┬────┘
     │         │          │        │
     ↓         ↓          ↓        ↓
  处理宏    指令映射     样式转换  配置提取
     │         │          │        │
     └─────────┴──────────┴────────┘
               ↓
         生成 .js/.wxml/.wxss/.json
```

增量构建的时候只处理改过的文件，HMR 能跑得比较稳也是靠这个缓存策略撑着。

## `defineXxxJson` 宏的用法

上面提到推荐用编译宏来代替 `<json>` 块，这里展开说一下。`defineAppJson`、`definePageJson`、`defineComponentJson` 都是编译期宏，构建时提取合并到对应的 `.json` 文件里，运行时零开销。写起来大概是这样：

```html
<script setup lang="ts">
  definePageJson({
    navigationBarTitleText: '首页',
    usingComponents: {},
  })
</script>
```

好处就是直接写在 `<script setup>` 里，有完整的类型推导，改字段名的时候 IDE 能帮你检查，不会出现"json 里改了但别的地方没跟上"的情况。

## 原生组件与插槽

在 `.vue` 里 import 原生组件之后，构建阶段会看模板里到底用没用到，用到了才往 `usingComponents` 里补。这样就不用手动维护那堆路径配置了，少写少错。

插槽也是类似的思路。你写的是 Vue 的 slot 语法，但输出的时候会按小程序的 slot 语义来生成。作用域插槽稍微复杂一点，背后走的是一套语义映射加代码生成，不是简单的字符串替换能搞定的。

## Rolldown：收益主要体现在日常开发体感

v6 切到 Rolldown 不是为了赶时髦，就是想把开发时的等待再缩短一点。

日常能感受到的主要是三个地方：冷启动快了、改完代码后增量构建更灵敏、项目依赖多的时候不容易抽风。不是那种"跑分暴涨 300%"的故事，更像是每次都省个几百毫秒，积少成多，一天下来体感差挺多的。

## 为什么没走 `createRenderer` 这条路

这个问题被问了太多次了，干脆在这里好好聊聊。

做 Wevu 之前我肯定研究过 `@vue/runtime-core` 的 `createRenderer`，毕竟 Vue 官方就是拿这个来做自定义渲染器的。技术上能不能跑通？能。但我最后没选这条路，不是因为它不好，是因为拿来做小程序，越想越觉得别扭。

`createRenderer` 要你提供一整套节点操作——`patchProp`、`insert`、`remove`、`createElement`、`createText`、`parentNode`、`nextSibling`……这套东西天然就是给"我有一棵节点树，我要增删改查"这种场景设计的。DOM 是这样，Canvas 是这样，Native UI 也是这样。

但小程序不是这样。

小程序的更新通道就一个：`setData(payload)`。你没法去"插入一个节点"或者"删除一个子元素"，你只能告诉它"这些数据变了，你自己去渲染"。这跟 `createRenderer` 假设的那套能力模型，根本就是两个世界的东西。

如果硬要用 `createRenderer`，你就得在小程序上面再模拟一层虚拟的节点树出来，把 renderer 的那些节点操作接进去，最后再把这棵树的变化折叠成 `setData` 调用。等于你凭空多了一层抽象，而这层抽象解决的不是你的问题——你的问题是怎么让 `setData` 的 payload 尽量小、调用尽量少，不是怎么维护一棵节点树。

而且还有个很实际的问题：Wevu 的页面和组件注册直接走的是小程序的 `App()` / `Component()`，生命周期也是围绕这些来的。实例边界天然就是小程序实例，不是 renderer 那套"容器 + vnode root"。编译产物也是"小程序模板 + 运行时桥接代码"，不是给 renderer 跑的 vnode render 函数。要是主架构迁过去，编译器和运行时得一起重写，这个成本太高了。

有人可能会说，Taro 不就是类似的思路吗？一个比较大的 `base.wxml` 加运行时驱动节点树。确实，技术上可行，Wevu 也不是绝对做不了。但在小程序里实际跑下来，运行时要额外维护节点映射和协调过程，`base.wxml` 越通用体积越大、模板解析越重，而且到最后还是得落到 `setData`——上面那层抽象并不能帮你绕开这个桥接成本。大部分业务场景下，性能大概率不如直接做快照 diff + 最小 setData。

所以 Wevu 的策略很明确：主线就走"编译到 WXML + 运行时快照 diff + 最小 setData"。`createRenderer` 如果后面想验证，会开个实验分支单独跑，看功能覆盖、更新性能、payload 体积这几个指标。在没跑出明显收益之前，不会动现有链路。

说到底，`createRenderer` 是个很优秀的通用能力，但 Wevu 要解决的是小程序 `setData` 语义下的具体工程问题，这俩不在一个频道上。

更详细的技术分析我单独写了一篇，感兴趣可以看：[为什么没有使用 @vue/runtime-core 的 createRenderer 来实现](/wevu/why-not-runtime-core-create-renderer)

## 当前能力范围（截至 release6）

日常开发用到的东西基本都覆盖了：`v-if` / `v-for` / `v-model` 这些核心指令，事件和属性绑定，SCSS/Less 和 CSS Modules，props/emits/slots/provide/inject，生命周期，常用的响应式 API，还有 TypeScript 类型推导和泛型组件。

如果你是从 Vue 3 过来的，写法上基本不用重新学，主要就是记住最后跑的不是浏览器而是小程序。

## 最后

感谢每一位提建议、报 bug、提 PR 的同学。

***

如果 Weapp-vite 帮到了你，欢迎给项目点个 [Star](https://github.com/weapp-vite/weapp-vite)！

Happy Coding! 🚀

---

---
url: /guide/image-optimize.md
description: >-
  Weapp-vite 在静态资源方面沿用了 Vite 的约定：import 语句、public
  目录、插件生态都可以直接使用。本页聚焦最常见的资源场景，并给出优化建议。
---

# 静态资源的处理与优化

`weapp-vite` 在静态资源方面沿用了 Vite 的约定：`import` 语句、`public` 目录、插件生态都可以直接使用。本页聚焦最常见的资源场景，并给出优化建议。

## 何时放入 `public`

* 放在 `public/` 的文件会原样复制到产物目录（默认同级的 `dist/`），不会参与打包。
* 适合体积较大、无需通过模块系统处理的资源，例如应用图标、`tabbar` 图标、`sitemap.json`。
* 引用方式使用根路径：`/icon.png`、`/static/logo.svg`。对于 `app.json` 中的字段（例如 `tabBar.iconPath`），可按官方要求使用相对或绝对路径。

> \[!TIP]
> 可以通过 Vite 的 [`publicDir`](https://cn.vite.dev/config/shared-options#publicdir) 调整目录位置，也可以完全禁用该行为。

## 通过 `import` 引用的资源

当在脚本、样式中使用 `import img from './logo.png'` 或 `background: url('./banner.png')` 时，会由 Rolldown 负责拷贝并生成哈希文件名。这类资源会自动记录在依赖图中，适合页面局部使用的图片。

若需要在运行时根据条件加载，可结合 `new URL('./foo.png', import.meta.url)` 等方式。不过仍建议把静态文件纳入仓库管理，确保构建可重复、可回滚。

## 图片压缩与 CDN

针对图片体积，可从两方面入手：

1. **构建时压缩**：使用 Vite 插件在打包阶段压缩图片。
2. **发布到 CDN/OSS**：将图片上传到静态资源服务，代码中只保留 URL。

### 使用 `vite-plugin-image-optimizer`

该插件会在打包时使用 `sharp`、`svgo` 等工具对图片做无损/有损压缩。示例：

```sh
pnpm add -D vite-plugin-image-optimizer sharp svgo
```

```ts
import { ViteImageOptimizer } from 'vite-plugin-image-optimizer'
import { defineConfig } from 'weapp-vite'

export default defineConfig({
  plugins: [
    ViteImageOptimizer({
      // 按需定制压缩选项，例如：
      png: { quality: 80 },
      jpg: { quality: 80 },
    }),
  ],
})
```

> \[!NOTE]
> `sharp` 需要 Node.js 原生依赖，安装失败时可参考插件文档或切换到 `wasm` 方案。

### 与 CDN/OSS 协同

* 在构建脚本中上传资源后，可使用环境变量或配置文件将 URL 注入到页面。
* 保持仓库内仍有源文件，便于回滚与重新构建。
* 若启用自动上传，注意处理好缓存与失效时间，避免小程序端长时间引用旧资源。

## 常见问题

* **开发环境访问不到 `public` 资源？** 请确保以 `/` 开头引用。如果仍然 404，检查资源是否位于 `public/` 根目录而非 `src/public/`。
* **编译后图片路径错乱？** 对于通过 `import` 引入的资源，请避免手动编写相对路径字符串，改用 `import` 或 `new URL`，让构建器接管路径计算。
* **需要自动生成多尺寸图标？** 可以结合 Vite 插件或自定义脚本（如 `sharp`）在构建阶段批量生成。

---

---
url: /guide/multi-platform.md
description: Weapp-vite 内置了多端适配能力：在开发/构建命令后追加 --platform （或短写 -p ），即可输出目标平台所需的文件后缀与目录结构。
---

# 面向多平台构建 {#multi-platform}

`weapp-vite` 内置了多端适配能力：在开发/构建命令后追加 `--platform <id>`（或短写 `-p <id>`），即可输出目标平台所需的文件后缀与目录结构。

下面示例假设你在 `package.json` 脚本里使用的是 `weapp-vite dev` / `weapp-vite build`：

> \[!WARNING]
> 执行命令前请先安装对应平台的 IDE；如果你需要用命令行唤起 IDE，请在 IDE 里开启“服务端口”。

## 支付宝小程序 {#platform-alipay}

```sh
pnpm dev -- --platform alipay
pnpm build -- --platform alipay
pnpm open -- --platform alipay
# 也可以直接调用 CLI，省去额外的 --
pnpm exec weapp-vite dev --platform alipay
pnpm exec weapp-vite build --platform alipay
pnpm exec weapp-vite open --platform alipay
```

* 产物扩展名自动变更为 `axml` / `acss` / `sjs`。
* 在支付宝 IDE 中导入 `dist/` 目录即可预览。
* `open --platform alipay` 会自动通过 `minidev ide` 打开支付宝开发者工具（需先安装 `minidev`）。

## 字节系（抖音 / 今日头条）小程序 {#platform-tt}

```sh
pnpm dev -- --platform tt
pnpm build -- --platform tt
pnpm exec weapp-vite dev --platform tt
pnpm exec weapp-vite build --platform tt
```

* 支持字节全家桶（抖音 / 今日头条 / 番茄小说等）所需的 `ttml` / `ttss` 扩展名。
* 推荐使用字节小程序开发者工具导入构建产物。

## 百度智能小程序 {#platform-swan}

```sh
pnpm dev -- --platform swan
pnpm build -- --platform swan
pnpm exec weapp-vite dev --platform swan
pnpm exec weapp-vite build --platform swan
```

* 输出 `swan` / `css` / `sjs` 等百度专用格式。
* 在百度智能小程序开发者工具中选择 `dist/` 目录。

## 京东小程序 {#platform-jd}

```sh
pnpm dev -- --platform jd
pnpm build -- --platform jd
pnpm exec weapp-vite dev --platform jd
pnpm exec weapp-vite build --platform jd
```

* 自动转换为 `jxml` / `jxss` 等京东特有的扩展名。
* 构建完成后可直接导入京东小程序 IDE。

## 小红书小程序 {#platform-xhs}

```sh
pnpm dev -- --platform xhs
pnpm build -- --platform xhs
pnpm exec weapp-vite dev --platform xhs
pnpm exec weapp-vite build --platform xhs
```

* 生成 `xhsml` / `css` 等小红书小程序所需格式。
* 结合小红书开发者中心提供的工具进行预览 / 上传。

> \[!TIP]
> 需要同时输出 Web 版本时，可以在另一个终端运行 `pnpm dev -- --platform h5` 或 `pnpm exec weapp-vite dev --platform h5`。
> 也可以在 `package.json` 里写专用脚本（例如 `"dev:alipay": "weapp-vite dev --platform alipay"`），之后直接运行 `pnpm dev:alipay`，避免每次手动输入 `-- --platform ...`。