---
url: /guide/directory-structure.md
description: Weapp-vite 的目录结构总览页，按 Nuxt 式目录索引组织，左侧目录项为独立路由，右侧为每个目录或文件的详细说明。
---

# 目录结构

这一组文档按“目录即能力边界”的方式组织，交互形态参考 Nuxt 的 directory structure 页面。

* 左侧每一个目录或文件项，都是单独的文档路由
* 右侧页面只解释当前项的职责、默认行为和触发的能力
* 如果你只想先看全局，再决定点进哪个目录，从这页开始就够了

## 一个典型项目

```text
.
├─ vite.config.ts / weapp-vite.config.ts
├─ project.config.json
├─ package.json
├─ public/
├─ .weapp-vite/
│  ├─ typed-router.d.ts
│  ├─ typed-components.d.ts
│  └─ components.d.ts
└─ <srcRoot>/
   ├─ app.(js|ts)
   ├─ app.vue
   ├─ app.json(.js|.ts)?
   ├─ app.(css|scss|wxss|...)
   ├─ layouts/
   ├─ custom-tab-bar/
   ├─ app-bar/
   ├─ pages/
   ├─ components/
   ├─ <subPackageRoot>/
   │  ├─ pages/
   │  └─ components/
   ├─ shared/
   ├─ utils/
   ├─ workers/
```

## 先记住三条

1. `weapp-vite` 真正依赖的是 `srcRoot`，不是硬编码的 `src/`
2. 页面自动扫描默认只看 `srcRoot/pages/**` 和已声明分包 root 下的 `pages/**`
3. `layouts`、`custom-tab-bar`、`app-bar`、类型声明文件这些都属于带固定语义的保留位置

> \[!TIP]
> 这一组文档里的 `<srcRoot>`、`<subPackageRoot>` 都是变量占位，不是固定目录名。它们分别代表你在 `vite.config.ts` / `weapp-vite.config.ts` 中声明的源码根目录和分包 root。

## 从哪里开始看

* 想先建立全局认知：看 [📄 配置入口文件](/guide/directory-structure/vite-config)、[📁 `<srcRoot>/`](/guide/directory-structure/src-root)
* 想搞清楚页面 layout 放哪里：看 [📁 `<srcRoot>/layouts/`](/guide/directory-structure/layouts)
* 想搞清楚页面与分包：看 [📁 `<srcRoot>/pages/`](/guide/directory-structure/pages)、[📁 `<srcRoot>/<subPackageRoot>/`](/guide/directory-structure/subpackages)
* 想搞清楚自动生成产物：看 [类型声明文件](/guide/directory-structure/generated-files)

## 默认能力速查

| 位置                                                                                                  | 作用                                               |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------- | ----- | ------------------------------------------- |
| `vite.config.ts` / `weapp-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 与常见预处理器 |
| `layouts/`                                                                                            | 页面 layout 约定目录，承载默认布局和命名布局       |
| `pages/`                                                                                              | 主包页面目录                                       |
| `components/`                                                                                         | 主包组件目录，默认参与自动导入扫描                 |
| `<subPackageRoot>/pages/`                                                                             | 已声明分包 root 下的页面目录                       |
| `custom-tab-bar/`                                                                                     | `tabBar.custom === true` 时的固定入口              |
| `app-bar/`                                                                                            | `appBar` 开启时的固定入口                          |
| `.weapp-vite/typed-router.d.ts` / `.weapp-vite/typed-components.d.ts` / `.weapp-vite/components.d.ts` | 自动生成的类型声明文件                             |

## 相关文档

* [自动路由](/guide/auto-routes)
* [页面 Layout 使用指南](/guide/layouts)
* [自动导入组件](/guide/auto-import)
* [分包指南](/guide/subpackage)
* [手动集成](/guide/manual-integration)

---

---
url: /guide/directory-structure/vite-config.md
description: Weapp-vite 配置入口文件，负责定义 srcRoot、自动路由、分包、自动导入组件等行为。
---

# `vite.config.ts` / `weapp-vite.config.ts`

`vite.config.ts` 或 `weapp-vite.config.ts` 是这组目录约定的真正入口。很多“目录为什么会生效”的答案，最终都在这里。

如果两个文件同时存在，`weapp-vite` 会优先读取并合并 `weapp-vite.config.*` 中的 `weapp` 配置；如果项目只保留其中一个，也可以正常工作。

## 它决定什么

* `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: /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/package-json.md
description: 项目脚本与依赖入口，通常承载 dev、build、open 等 weapp-vite 命令。
---

# `package.json`

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

## 通常会放什么

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

```json
{
  "scripts": {
    "dev": "wv dev",
    "build": "wv build",
    "open": "wv open"
  }
}
```

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

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

---

---
url: /guide/directory-structure/public.md
description: 构建时原样复制到产物目录的静态资源目录，适合放无需参与模块分析和编译转换的文件。
---

# `public/`

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

## 适合放这里的内容

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

## 不适合放这里的内容

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

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

---

---
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/` 的扫描根目录
* `layouts/` 的扫描根目录
* `custom-tab-bar/`、`app-bar/` 的固定位置
* `.weapp-vite/typed-router.d.ts`、`.weapp-vite/typed-components.d.ts`、`.weapp-vite/components.d.ts` 的生成时机与引用方式

## 一个简单判断

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

`<srcRoot>/pages/**`

---

---
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-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: /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-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/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: /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/layouts.md
description: >-
  说明 srcRoot/layouts 目录的职责、命名规则，以及它如何与 definePageMeta、routeRules、setPageLayout
  协同工作。
---

# `<srcRoot>/layouts/`

`<srcRoot>/layouts/` 是 `weapp-vite` 页面 layout 的约定目录。它的职责不是放普通业务组件，而是放“页面外壳”。

## 1. 这个目录解决什么问题

如果很多页面都要重复包一层：

* 统一头部
* 统一底部
* 统一侧边栏
* 统一内容容器

那这些结构更适合放在 `layouts/`，而不是在每个页面里手动重复引用。

| 放在这里的内容                             | 不建议放在这里的内容          |
| ------------------------------------------ | ----------------------------- |
| 页面级外壳组件                             | 普通业务组件                  |
| 后台壳、营销页壳、沉浸式壳                 | 单个页面独享的小组件          |
| 供 `definePageMeta({ layout })` 命中的布局 | 按钮、卡片、列表项一类通用 UI |

## 2. 一个典型目录长什么样

```txt
src/
├─ layouts/
│  ├─ default.vue
│  ├─ admin.vue
│  └─ native-shell/
│     ├─ index.json
│     ├─ index.wxml
│     ├─ index.wxss
│     └─ index.ts
└─ pages/
```

## 3. 名称是怎么推导的

layout 名称由相对 `layouts/` 的路径推导：

| 文件位置                       | layout 名      |
| ------------------------------ | -------------- |
| `layouts/default.vue`          | `default`      |
| `layouts/admin.vue`            | `admin`        |
| `layouts/native-shell/index.*` | `native-shell` |

> **注意**：`default` 是默认布局名。只要它存在，页面在没有显式声明 layout 时，就会优先尝试命中它。

## 4. 支持哪些实现形式

### 4.1 Vue layout

适合已经全面使用 Vue SFC 的项目：

```vue
<template>
  <view class="layout-default">
    <slot />
  </view>
</template>
```

### 4.2 原生 layout

适合原生小程序页面或渐进迁移项目：

```txt
layouts/native-shell/
├─ index.json
├─ index.wxml
├─ index.wxss
└─ index.ts
```

其中 `index.json` 需要声明为组件：

```json
{
  "component": true
}
```

## 5. 它会和哪些能力协同工作

| 能力                         | 作用                          |
| ---------------------------- | ----------------------------- |
| `definePageMeta({ layout })` | 页面显式指定 layout           |
| `weapp.routeRules`           | 批量声明默认 layout           |
| `setPageLayout()`            | 运行时显式切换当前页面 layout |
| `usePageLayout()`            | 读取当前页面 layout 状态      |

## 6. 使用时最容易踩的坑

### 6.1 把普通组件放进 `layouts/`

不推荐：

```txt
src/layouts/ProductCard.vue
```

更推荐：

```txt
src/components/ProductCard.vue
```

因为 `layouts/` 的语义是页面壳，不是普通 UI 组件目录。

### 6.2 以为 `layout` 可以写成动态表达式

不推荐：

```ts
definePageMeta({
  layout: currentLayout.value,
})
```

推荐：

```ts
setPageLayout('admin')
```

因为 `definePageMeta({ layout })` 是编译期静态分析，动态切换要交给运行时 API。

## 7. 总结

`<srcRoot>/layouts/` 的重点不在“多一个目录”，而在于把页面外壳从页面内容里抽出来，形成稳定的复用层。

如果你的项目准备启用 layout，建议最少先准备这两类：

1. `default`
2. 一个命名 layout，例如 `admin`

## 8. 参考资源

| 主题                  | 推荐入口                                                            |
| --------------------- | ------------------------------------------------------------------- |
| 页面 Layout 使用指南  | [guide/layouts](/guide/layouts)                                     |
| Route Rules 与 Layout | [config/route-rules](/config/route-rules)                           |
| `<srcRoot>/`          | [directory-structure/src-root](/guide/directory-structure/src-root) |

---

---
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/components.md
description: 主包组件目录，默认参与自动导入组件扫描，并作为 `usingComponents` 自动补全的重要来源。
---

# `components/`

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

## 默认扫描范围

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

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

## 它解决什么问题

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

## 适合放什么

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

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

---

---
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/directory-structure/shared.md
description: 跨主包与分包共享模块的推荐目录，用来沉淀复用逻辑、常量、样式与跨包共享能力。
---

# `shared/`

`shared/` 不是框架保留目录，但它是很推荐的共享层位置。

## 适合放什么

* 共享样式
* 常量
* 类型
* 请求层封装
* 跨包复用的 composable / helper

## 为什么它常见

因为页面、组件、分包都容易不断增长，提前给共享代码一个稳定位置，长期维护成本会更低。

---

---
url: /guide/directory-structure/utils.md
description: 通用工具函数的推荐目录，适合放业务无关、可复用且能在主包与分包之间共享的辅助模块。
---

# `utils/`

`utils/` 是通用工具函数目录。

它没有框架保留语义，但非常适合作为纯函数和轻量工具层的落点。

## 常见内容

* 格式化函数
* URL/路径辅助函数
* 时间、数字、字符串处理
* 与业务无关的通用 helper

如果这里的模块同时被主包和多个分包引用，最终代码落盘位置还会受到 chunk 策略影响。

---

---
url: /guide/directory-structure/workers.md
description: Worker 入口的推荐目录，可与 app.json 和 worker 配置联动。
---

# `workers/`

`workers/` 适合放小程序 Worker 入口。

它不是自动路由目录，也不是自动导入组件目录，但如果项目启用了 Worker，这里通常是一个清晰的落点。

相关能力见：[Worker 配置](/config/worker)

---

---
url: /guide/directory-structure/generated-files.md
description: weapp-vite 自动生成的类型与支持文件，默认输出到 .weapp-vite 目录。
---

# 类型声明文件

这一组文件默认都生成到 `.weapp-vite/` 下，配合 `weapp-vite` 托管的 TypeScript 支持文件一起接入编辑器与类型检查。

## 包含哪些文件

* `typed-router.d.ts`
* `typed-components.d.ts`
* `components.d.ts`
* `wevu-layouts.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 全局组件类型声明文件。

* 负责模板中的全局组件类型提示
* 配合自动导入组件一起工作
* 会在可推断场景下合并小程序组件通用基础属性（如 `class`、`style`、`id`）

当 `weapp.autoImportComponents.vueComponents` 开启时，它会出现。

## `wevu-layouts.d.ts`

这是 layout 扫描生成的类型增强文件。

* 为 `wevu` 的 `WevuPageLayoutMap` 注入 layout 名称与 props 类型
* 让 `setPageLayout()`、`usePageLayout()` 拿到更严格的类型提示

当项目里存在 `srcRoot/layouts/**` 且自动导入组件相关输出开启时，它会自动刷新。

## 默认位置

```text
.weapp-vite/typed-router.d.ts
.weapp-vite/typed-components.d.ts
.weapp-vite/components.d.ts
.weapp-vite/wevu-layouts.d.ts
```

## 相关文档

* [自动路由](/guide/auto-routes)
* [自动导入组件](/guide/auto-import)
* [TypeScript 支持文件](/config/typescript)
* [Route Rules 与 Layout](/config/route-rules)

---

---
url: /guide.md
description: 从零创建或接入 weapp-vite 项目，快速跑通开发、构建、IDE 打开、CLI 透传与后续能力扩展。
---

# 快速开始 {#getting-started}

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

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

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

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

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

## 0. 准备工作

1. 下载并安装最新版 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)。
2. 启动开发者工具，并先确认当前账号已登录。`weapp-ide-cli` / `weapp-vite` 现在会在调用前自动尝试预热 DevTools 安全设置，但首次仍建议手动确认开发者工具可正常工作。
3. 如果你希望命令行默认自动信任项目，可执行：
   ```sh
   weapp config set autoBootstrapDevtools true
   weapp config set autoTrustProject true
   ```
4. 如果你使用 VS Code，建议安装扩展市场里的 `weapp-vite` 扩展，获得命令入口、页面树、生成器、配置提示和 WXML 编辑器增强。详见 [VS Code 扩展](/guide/vscode-extension)。

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

:::

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

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

```sh
npx skills add sonofmagic/skills
```

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

### 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 # 已开启服务端口时自动打开微信开发者工具
```

:::

> \[!TIP]
> 如果你当前是在 Codex、Claude Code、Cursor CLI 这类 AI 终端里工作，且配置保持默认 `weapp.forwardConsole.enabled = 'auto'`，那么 `pnpm dev --open` 在打开微信开发者工具后还会自动尝试把小程序 `console` 日志桥接回当前终端。
>
> 想手动进入持续监听模式时，可直接执行：
>
> ```sh
> wv ide logs --open
> # 或
> wv ide logs --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-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
```

:::

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

> 想要一步步把现有项目接入 Weapp-vite：参考[《手动集成》](/guide/manual-integration)。想知道 CLI 初始化做了哪些改动：阅读 [`wv init 做了什么?`](/deep/init)。

## 常用命令

完整参数、透传规则与更多示例可查看 [CLI 命令参考](/guide/cli)。

### 开发命令

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

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

### 构建命令

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

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

### 打开微信开发者工具命令

```sh
pnpm open
wv ide setup .
```

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

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

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

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

> \[!WARNING]
> `weapp-vite` 会优先执行自己的原生命令；只有未命中时，才会回退透传到 `weapp-ide-cli`。因此 `build/dev/open/analyze/generate/mcp/prepare` 这些命令不会被官方 IDE CLI 覆盖。

## 下一步建议

* 想了解命令行能力边界：看 [CLI 命令参考](/guide/cli)。
* 想开始使用 Vue 单文件组件：看 [Vue SFC 开发](/guide/vue-sfc/) 和 [Wevu 概览](/wevu/)。
* 想减少手写 `app.json.pages` 与 `usingComponents`：看 [自动路由](/guide/auto-routes) 与 [自动导入组件](/guide/auto-import)。
* 想做 AI 协作或本地 MCP：看 [AI 协作](/guide/ai) 与 [@weapp-vite/mcp](/packages/mcp)。
  > 默认情况下 CLI 会自动尝试预热 DevTools 服务端口配置；如果你不希望自动处理，可执行 `weapp config set autoBootstrapDevtools false`。

> \[!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` 或 `weapp-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/)

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

---

---
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` 钩子帮助排查路径解析、产物归属等问题。
* **AI 协作内建**：内置 `wv mcp`、`wv ide logs`、运行时截图与截图对比，并通过 `create-weapp-vite` 默认生成 `AGENTS.md`。

## 现在不只是构建器

在当前版本里，`weapp-vite` 更像一整条“小程序研发工具链”，常见能力可以按这几层理解：

* **项目创建**：`create-weapp-vite` 负责模板、依赖版本对齐、`AGENTS.md`、推荐 AI skills 安装。
* **开发与构建**：`wv dev/build/prepare/analyze/open` 负责工程主链路。
* **IDE 自动化**：通过 `weapp-ide-cli` 透传 `preview/upload/config/screenshot/compare` 等命令。
* **AI 协作**：通过 `wv mcp`、`take_weapp_screenshot`、`compare_weapp_screenshot`、`wv ide logs --open` 把真实项目能力暴露给 AI。
* **运行时**：`wevu` 负责响应式、生命周期、store 与最小化 `setData` 更新。

如果你把它只理解成“把原生小程序改成 Vite 构建”，就会错过当前版本很大一部分能力面。

## 什么时候适合选择 Weapp-vite

* 你想坚持原生小程序写法，同时想要现代前端工具链（TS、模块化、热更新等）。
* 团队有存量项目，想尽量不动业务代码就升级构建流程。
* 你需要深入用微信提供的底层能力（如 Skyline、Donut），对运行时兼容层比较谨慎。

## 什么时候可以考虑其他方案

* 项目需要“一套代码多端运行”，或想直接用 `Vue`/`React` 写界面：可以优先评估 `uni-app`、`taro` 等跨端框架。
* 如果你只需要很基础的构建能力，并且已经投入了其他脚手架：可以先沿用现有方案，合适的时候再迁移。

## 迁移与生态

* `wv init` 支持在现有原生项目上直接生成配置，沿用原目录结构即可。
* 构建产物完全兼容微信开发者工具，分包、插件、Worker 等官方能力都可以继续使用。
* 通过 Vite 插件体系可以快速接入 Tailwind CSS、UnoCSS、自动化测试、Rollup 插件等生态资源。

## 对 AI 更友好的地方

如果项目是通过 `create-weapp-vite` 创建的，根目录通常会附带：

* `AGENTS.md`
* `node_modules/weapp-vite/dist/docs/*.md`

这两者会告诉 AI：

* 先读当前安装版本的本地文档，而不是依赖过时网站或模型记忆
* 提到截图时优先使用 `wv screenshot`
* 提到截图对比时优先使用 `wv compare`
* 提到 DevTools 日志时优先使用 `wv ide logs --open`

这也是为什么当前文档里会反复强调 AI 工作流、MCP 与 DevTools 日志桥接。

想要快速验证效果？前往 [快速开始](/guide/) 章节，十分钟内完成首个项目的创建、运行与调试。

---

---
url: /guide/cli.md
description: >-
  weapp-vite CLI 命令参考，覆盖 dev、build、analyze、prepare、mcp、ide logs、generate，以及
  screenshot/compare 等 weapp-ide-cli 透传规则。
---

# CLI 命令参考

本文汇总 `weapp-vite` 在当前版本可用的命令与参数，优先覆盖日常开发、构建、支持文件预生成、AI 协作与 IDE 自动化场景。

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

> `wv` 是 `weapp-vite` 的简写。下文统一使用 `wv` 作为命令示例。

## 命令格式

```bash
wv [全局参数] <command> [command options]
```

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

```bash
wv
```

等价于：

```bash
wv 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
wv dev [root]
wv serve [root]
wv [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`                 | 启动分包分析仪表盘（实验特性，小程序场景） |
| `--scope <scope>`           | 局部构建范围，例如 `main,packages/order`   |

补充说明：

* 当目标平台为 `weapp` 且启用了 `weapp.forwardConsole` 时，`wv dev --open` 会在打开微信开发者工具后，自动尝试把小程序 `console` 日志桥接到当前终端。
* 默认配置是 `enabled: 'auto'`，也就是仅在检测到 AI 终端时自动启用。
* `--scope` 会只保留主包和指定分包进入开发构建，适合日常只调试某几个业务分包。产物 `app.json.subPackages` 也只包含参与 scope 的分包。

### 2) `build`

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

```bash
wv 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`                 | 输出分包分析仪表盘（小程序场景）               |
| `--scope <scope>`           | 局部构建范围，例如 `main,packages/order`       |

局部构建示例：

```bash
wv dev --scope main,packages/order
wv build --scope packages/order
wv build --scope main,packages/order --analyze
```

语义说明：

* `main` 表示主包。
* `packages/order` 这类值匹配 `app.json.subPackages[].root` / `subpackages[].root`。
* CLI `--scope` 的优先级高于配置文件中的 `weapp.buildScope`。
* 不传 `--scope` 时保持完整构建行为。
* 传入 `--scope packages/order` 时默认仍包含主包，因此最终产物会包含主包页面和 `packages/order` 分包。
* 生成的 `app.json` 会同步裁剪 `subPackages` 与 `preloadRule`，未参与 scope 的分包不会被注册到本次产物。

### 3) `analyze`

分析小程序分包产物映射、组件依赖链路、预算与增量归因，或输出 Web 静态分析结果。

```bash
wv analyze [root]
```

参数：

| 参数                        | 说明                                                                               |
| --------------------------- | ---------------------------------------------------------------------------------- |
| `--hmr-profile [file]`      | 分析 HMR JSONL profile，省略值时优先读取 `weapp.hmr.profileJson`，否则回退默认路径 |
| `--json`                    | 输出 JSON 结果（stdout）                                                           |
| `--markdown`                | 输出完整 Markdown 报告                                                             |
| `--report <type>`           | 输出指定报告类型，当前支持 `pr`                                                    |
| `--budget-check`            | 检查 analyze 预算，超限时返回非 0 退出码                                           |
| `--output <file>`           | 将分析结果写入文件，格式随 `--json` / `--markdown` / `--report pr` 决定            |
| `-p, --platform <platform>` | 目标平台（`weapp` | `h5`）                                                        |
| `--project-config <path>`   | 小程序 `project.config.json` 路径                                                  |

小程序模式下，JSON 结果会包含 `components` 字段，用于展示组件被哪些页面递归引用、组件所属主包/分包、总使用次数，以及主包组件跨分包使用时的优化建议。默认终端摘要会展示组件建议数量和前几条高优先级建议，完整列表可通过 `--json` 或 `--output` 查看。

`weapp.analyze.budgets` 可覆盖默认总包、主包、普通分包、独立分包预算与预警比例。配合 `--budget-check` 时，预算超限会让命令返回非 0 退出码，适合 CI 阻断。`weapp.analyze.history` 默认会写入 `.weapp-vite/analyze-history`，Markdown / PR 报告会基于上一份快照输出增量归因。

常用示例：

```bash
wv analyze --json --output reports/analyze.json
wv analyze --markdown --output reports/analyze.md
wv analyze --report pr --output reports/analyze-pr.md
wv analyze --budget-check
wv analyze --hmr-profile .tmp/weapp-vite-hmr-profile.jsonl --json
wv analyze --platform h5 --json
```

> \[!TIP]
> HMR profile 需要先在 `weapp.hmr.profileJson` 中开启，或通过 `--hmr-profile <file>` 指向已有 JSONL 文件。Web 平台当前只做 `weapp.web` 与 `executionMode` 静态分析，不提供小程序分包体积和 dashboard。

### 4) `open`

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

```bash
wv open [root]
```

参数：

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

说明：

* 当目标平台为 `weapp` 时，`wv open` 会先复用 `weapp-ide-cli` 的底层能力，自动尝试预热微信开发者工具安全设置。
* 若你通过 `weapp config set autoTrustProject true` 开启了默认项目信任，未显式传 `--trust-project` 时也会按该策略执行。

### 5) `close`

关闭微信开发者工具。

```bash
wv close
```

说明：

* 这是 `weapp-vite` 原生命令，不会透传到 `weapp-ide-cli`。
* 适合在自动化或本地排障后清理 DevTools 会话。

### 6) `ide logs`

持续监听微信开发者工具里的小程序日志，并转发到当前终端。

```bash
wv ide logs [root]
```

参数：

| 参数                        | 说明                               |
| --------------------------- | ---------------------------------- |
| `-o, --open`                | 先打开微信开发者工具，再附加日志桥 |
| `-p, --platform <platform>` | 目标平台（当前仅支持 `weapp`）     |
| `--project-config <path>`   | 小程序 `project.config.json` 路径  |

说明：

* 该命令是常驻进程，按 `Ctrl+C` 退出。
* 当前仅支持微信小程序平台，不支持 `alipay` / `h5`。
* 若你只想在开发时自动附加，而不是手动执行此命令，可直接使用 `wv dev --open` 并配合 `weapp.forwardConsole`。

示例：

```bash
wv ide logs
wv ide logs --open
wv ide logs ./dist/dev -p weapp
```

### 7) `ide setup`

只预热微信开发者工具本地配置，不立即打开 IDE。

```bash
wv ide setup [root]
```

适用场景：

* 想先把 DevTools 安全设置和项目信任状态写好，再手动打开 IDE
* 在自动化脚本里提前准备环境，但不希望立即拉起窗口

示例：

```bash
wv ide setup .
wv ide setup ./dist/dev
```

### 8) `ide info` / `ide test-accounts` / `ide ticket*`

读取当前已打开 DevTools 会话的信息，优先复用已打开的 automator 会话。

```bash
wv ide info [root]
wv ide test-accounts [root]
wv ide ticket [root]
wv ide ticket:set [root] --ticket <value>
wv ide ticket:refresh [root]
```

参数：

| 参数                        | 说明                                               |
| --------------------------- | -------------------------------------------------- |
| `-o, --open`                | 先打开微信开发者工具，再执行信息查询或 ticket 操作 |
| `-p, --platform <platform>` | 目标平台（当前仅支持 `weapp`）                     |
| `--project-config <path>`   | 小程序 `project.config.json` 路径                  |
| `--ticket <value>`          | `ide ticket:set` 需要设置的新 ticket               |

说明：

* `ide info` 返回当前 DevTools `Tool.getInfo` 的结果。
* `ide test-accounts` 返回当前 DevTools 可用的测试账号列表。
* `ide ticket` / `ide ticket:set` / `ide ticket:refresh` 会直接操作当前 DevTools 会话里的 ticket。
* 这些命令不是日志桥接常驻进程，执行完成后会直接退出。

示例：

```bash
wv ide info
wv ide test-accounts --open
wv ide ticket
wv ide ticket:set --ticket your-ticket
wv ide ticket:refresh
```

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

调用 IDE 的 npm 构建能力。

```bash
wv npm
wv build:npm
wv build-npm
```

### 10) `generate` / `g`

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

```bash
wv generate [filepath]
wv g [filepath]
```

参数：

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

### 11) `init`

初始化项目配置。

```bash
wv init
```

### 12) `prepare`

预生成 `.weapp-vite` 下的支持文件，包括托管 `tsconfig`、自动路由类型、自动导入组件清单与类型等。

```bash
wv prepare [root]
```

适用场景：

* CI 或编辑器启动前，想先把 `.weapp-vite` 支持文件生成出来；
* 老项目尚未跑过 `dev/build`，但希望编辑器先拿到类型文件；
* 团队希望把自动路由、自动导入组件相关产物纳入显式预热流程。

### 13) `mcp`

启动 `weapp-vite` MCP 服务，或管理 AI 客户端的 MCP 配置。

```bash
wv mcp
wv mcp init codex
wv mcp print claude-code
wv mcp doctor cursor
```

参数：

| 参数                      | 说明                                                                               |
| ------------------------- | ---------------------------------------------------------------------------------- |
| `--transport <type>`      | 服务端支持 `stdio` / `streamable-http`；客户端配置支持 `command` / `http` 语义别名 |
| `--host <host>`           | HTTP 模式监听地址                                                                  |
| `--port <port>`           | HTTP 模式端口                                                                      |
| `--endpoint <path>`       | HTTP 模式 endpoint（默认 `/mcp`）                                                  |
| `--unref`                 | HTTP 模式下 `unref` server（不阻塞进程退出）                                       |
| `--url <url>`             | 为 `mcp init/print --transport http` 显式指定 HTTP MCP 地址                        |
| `--workspace-root <path>` | 指定 workspace 根目录（默认当前工作目录）                                          |
| `-y, --yes`               | `mcp init` 写入配置时跳过确认                                                      |

示例：

```bash
wv mcp
wv mcp --transport streamable-http --host 127.0.0.1 --port 3088 --endpoint /mcp
wv mcp print codex
wv mcp init codex -y
wv mcp init codex --transport http --url http://127.0.0.1:3088/mcp
wv mcp doctor codex
```

子命令说明：

* `mcp init <codex|claude-code|cursor>`：生成并写入客户端配置。
* `mcp print <codex|claude-code|cursor>`：只打印配置预览，不写入。
* `mcp doctor <codex|claude-code|cursor>`：检查客户端配置是否可用。

不在仓库目录执行时，可选追加 `--workspace-root <repo-root>`。

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

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

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

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

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

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

但 `weapp-vite` 自己保留了 `wv ide logs` 这个原生命令，不会透传到 `weapp-ide-cli`。

完整 IDE 命令列表请参考：

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

常见透传示例：

```bash
wv preview --project ./dist -q terminal
wv upload --project ./dist -v 1.0.0 -d "ci upload"
wv cache --clean compile
wv screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
wv compare --project ./dist/build/mp-weixin --page pages/index/index --baseline .screenshots/baseline/index.png --diff-output .tmp/index.diff.png --max-diff-pixels 100 --json
wv cache --clean all
wv config set autoBootstrapDevtools true
wv config set autoTrustProject true
```

和 DevTools 自动预热相关的高频配置：

```bash
wv config show
wv config doctor
wv config get autoBootstrapDevtools
wv config get autoTrustProject
wv config set autoBootstrapDevtools true
wv config set autoTrustProject true
```

默认生效值：

* `autoBootstrapDevtools`: `true`
* `autoTrustProject`: `false`

高频透传命令里，和 AI 验收最相关的是下面两类：

### `wv screenshot`

```bash
wv screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
```

关键参数：

| 参数               | 说明                          |
| ------------------ | ----------------------------- |
| `--project <path>` | 小程序项目目录                |
| `--page <path>`    | 截图前先跳转页面              |
| `--output <path>`  | 截图输出路径                  |
| `--timeout <ms>`   | automator 连接超时            |
| `--json`           | JSON 输出，适合 AI / 脚本解析 |

### `wv compare`

```bash
wv compare --project ./dist/build/mp-weixin --page pages/index/index --baseline .screenshots/baseline/index.png --current-output .tmp/current.png --diff-output .tmp/index.diff.png --max-diff-pixels 100 --json
```

关键参数：

| 参数                        | 说明                             |
| --------------------------- | -------------------------------- |
| `--project <path>`          | 小程序项目目录                   |
| `--baseline <path>`         | baseline 图片，必填              |
| `--page <path>`             | 对比前先跳转页面                 |
| `--current-output <path>`   | 保存当前截图                     |
| `--diff-output <path>`      | 保存 diff 图                     |
| `--threshold <number>`      | pixelmatch threshold，默认 `0.1` |
| `--max-diff-pixels <count>` | 最大允许差异像素数               |
| `--max-diff-ratio <number>` | 最大允许差异占比                 |
| `--json`                    | JSON 输出                        |

使用约束：

* `compare` 必须提供 `--baseline`
* `compare` 至少提供 `--max-diff-pixels` 或 `--max-diff-ratio` 之一
* 对比失败时命令会返回非 `0`，适合直接接 CI 或 AI 验收流程

## 常用示例

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

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

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

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

# 预生成 .weapp-vite 支持文件
wv prepare

# 持续监听 DevTools console
wv ide logs --open

# 小程序截图采集
wv screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json

# 小程序截图对比
wv compare --project ./dist/build/mp-weixin --page pages/index/index --baseline .screenshots/baseline/index.png --diff-output .tmp/index.diff.png --max-diff-pixels 100 --json

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

# 清理微信开发者工具缓存
wv cache --clean compile
wv cache --clean all
```

---

---
url: /guide/vscode-extension.md
description: 为 weapp-vite 项目安装官方 VS Code 扩展，获得命令入口、页面树、生成器、路由维护、配置提示与多端模板增强。
---

# VS Code 扩展

如果你使用 VS Code 开发 `weapp-vite` 项目，建议同时安装扩展市场里的 `weapp-vite` 扩展。它把常用 CLI、页面维护、配置提示和多端模板增强直接放进编辑器里，减少在终端、资源管理器、`app.json` 和页面文件之间来回切换。

## 安装

1. 打开 VS Code 扩展市场，搜索 `weapp-vite` 并安装。
2. 用 VS Code 打开你的 `weapp-vite` 项目。
3. 等工作区识别完成后，打开命令面板并执行 `weapp-vite: Run Action`，确认扩展已经生效。

> \[!TIP]
> 如果你使用 Vue SFC，建议同时安装 `Vue - Official (Volar)`，并结合 [@weapp-vite/volar](/packages/volar) 或 [Vue SFC 开发](/guide/vue-sfc/) 文档配置 `weapp-vite/volar`。`weapp-vite` 扩展负责编辑器入口与轻量增强，Volar 负责更完整的 Vue 类型与模板语言服务。

## 主要能力

| 能力                   | 说明                                                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 项目命令入口           | 在状态栏和命令面板中直接执行 `Dev`、`Build`、`Generate`、`Open DevTools`、`Doctor / Info`、`Show Output` 等常用动作。                             |
| 页面与组件生成         | 支持直接生成页面或组件骨架，也支持从资源管理器右键目录快速创建。                                                                                  |
| `app.json` 页面维护    | 支持把当前页面加入 `app.json`、从 route 直接打开页面、根据 route 创建缺失页面、同步未注册页面。                                                   |
| Pages 侧边栏           | 提供 `weapp-vite Pages` 视图，按顶层页面、分包页面、未声明页面分组查看，并支持过滤当前页面或问题页面。                                            |
| Route 导航与定位       | 支持复制当前页面 route、在 `app.json` 中定位当前页面声明、在页面树中高亮当前页面。                                                                |
| 配置补全与提示         | 为 `package.json`、`app.json`、`vite.config.*` / `weapp-vite.config.*`、页面 `definePageJson(...)` 与 `.vue` 中的配置块提供补全、悬浮和轻量诊断。 |
| 多端模板编辑器增强     | 在 `.vue <template>`、HTML、WXML、AXML、TTML、Swan、JXML、QML、KSML、XHSML 与 TyML 中提供补全、悬浮、跳转、引用和重命名。                         |
| 样式 class 智能提示    | 为 CSS、SCSS、Sass、Less、Stylus 嵌套选择器提供 class 补全、定义跳转与主题感知语义着色。                                                          |
| `usingComponents` 治理 | 支持本地组件路径校验、缺失组件提示、跳转到组件定义，以及按需生成缺失组件。                                                                        |
| 语法高亮与片段         | 提供 `.vue` 里的 `<json>` 自定义块高亮、多端小程序模板语法、常用代码片段与可选文件图标主题。                                                      |

## 常用场景

### 新建页面

1. 执行 `weapp-vite: Generate`。
2. 选择创建页面。
3. 选择目标目录。
4. 按提示决定是否同步加入 `app.json`。

### 修复页面声明缺失

1. 打开页面文件。
2. 执行 `weapp-vite: Add Current Page To app.json`。
3. 或者在 `weapp-vite Pages` 视图中对未声明页面执行修复动作。

### 从 route 跳回源码

1. 在 `app.json` 中把光标放到页面 route 上。
2. 使用 `Cmd/Ctrl + Click`，或执行 `weapp-vite: Open Page From Route`。
3. 扩展会直接跳转到对应页面文件。

## 常见说明

* `weapp-vite` 扩展主要负责编辑器工作流、轻量提示和页面治理；如果你需要更完整的 Vue SFC 类型与模板能力，请配合 `Vue - Official (Volar)` 使用。
* 如果没有识别到项目，请先确认工作区里存在 `package.json`、`vite.config.*` / `weapp-vite.config.*`，以及 `app.json` 或 `src/app.json`。
* 如果你更习惯完整命令名，可以关闭配置项 `weapp-vite.preferWvAlias`，让扩展优先生成 `weapp-vite dev` 这类命令，而不是 `wv dev`。

## 相关文档

* [快速开始](/guide/)
* [CLI](/guide/cli)
* [JSON 智能提示](/guide/json-intelli-sense)
* [Vue SFC 开发](/guide/vue-sfc/)
* [@weapp-vite/volar](/packages/volar)

---

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

# AI 协作指南

## Skills

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

直接使用公开技能仓库时，安装推荐 skills：

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

如果项目是通过 `create-weapp-vite` 初始化的，交互模式默认会直接询问你是否安装推荐的 AI skills；即使你当时跳过，也可以后续手动执行同一条命令。

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

```text
$weapp-vite-best-practices
$docs-and-website-sync
$release-and-changeset-best-practices
$weapp-devtools-e2e-best-practices
$weapp-vite-vue-sfc-best-practices
$wevu-best-practices
$native-to-weapp-vite-wevu-migration
```

如果你需要按任务快速选择 skill，可以直接看 [AI Skills 使用指南](/guide/skills)。如果你希望把 issue 修复、文档同步、DevTools e2e、SFC 排障和原生迁移串成可验收流程，可以看 [AI 任务工作流](/guide/ai-workflows)。

建议：

1. 面向用户公开分发的流程优先沉淀到 `skills/*`。
2. 项目架构、分包、构建编排问题优先用 `weapp-vite-best-practices`。
3. 根据现有代码同步 `website`、`skills`、AI 指南时优先用 `docs-and-website-sync`。
4. GitHub issue 修复、`e2e-apps/github-issues` 复现、changeset、PR 闭环优先用 `release-and-changeset-best-practices`。
5. WeChat DevTools runtime e2e、automator 复用、`reLaunch` 方案优先用 `weapp-devtools-e2e-best-practices`。
6. `.vue` 宏、模板兼容、`v-model`/`usingComponents` 问题优先用 `weapp-vite-vue-sfc-best-practices`。
7. `wevu` 生命周期、状态、事件、store，以及卡顿、掉帧、白屏、内存告警这类运行时治理优先用 `wevu-best-practices`。
8. 原生小程序迁移到 `weapp-vite + 原生`，或继续迁移到 `weapp-vite + wevu + Vue SFC`，优先用 `native-to-weapp-vite-wevu-migration`。
9. DevTools 自动化、`preview/upload/automator/config` 命令治理优先用 `weapp-vite-best-practices`。
10. 先让 AI 明确使用哪个 Skill，再开始具体任务。

## MCP

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

如果你是在其他仓库里使用 `weapp-vite`，而不是在这个 monorepo 里直接开发，推荐先让 AI 读取依赖包里随版本发布的本地文档：

* `node_modules/weapp-vite/dist/docs/index.md`
* `node_modules/weapp-vite/dist/docs/README.md`
* `node_modules/weapp-vite/dist/docs/mcp.md`

这样 AI 会先基于你当前安装版本的本地说明工作，再去执行 `wv screenshot`、`wv compare`、`wv ide logs --open` 或其他 CLI 命令。

如果项目本身就是通过 `create-weapp-vite` 创建的，还应优先读取项目根目录的 `AGENTS.md`。这个文件由脚手架自动生成，里面会把截图、截图对比、日志桥接等 AI 意图路由预先写好。

### AI 意图路由

如果你希望 AI 在自然语言里稳定命中 mini-program runtime 能力，建议把下面这组映射写进项目级 `AGENTS.md`：

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

除非目标明确是 Web runtime，否则不要退化成普通浏览器截图工具。

默认行为：

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

推荐先走客户端接入命令，而不是先手动研究 MCP 地址：

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

如果你只想打印配置，不直接写入文件：

```bash
wv mcp print codex
```

写入后建议立刻做一次检查：

```bash
wv mcp doctor codex
```

如果你已经通过 `pnpm dev`、`wv dev` 或 `wv mcp --transport streamable-http` 起好了 HTTP MCP 服务，也可以直接生成 HTTP 配置：

```bash
wv mcp init codex --transport http
wv mcp init claude-code --transport http
wv mcp init cursor --transport http
wv mcp init codex --transport http --url http://127.0.0.1:3088/mcp
```

如果你的 AI 客户端支持显式工具命名，建议优先直接调用：

1. `take_weapp_screenshot`
2. `compare_weapp_screenshot`

它们分别对应 `wv screenshot --json` 与 `wv compare --json`，比泛化的“browser screenshot”类工具更稳定。

手动启动（推荐）：

```bash
wv mcp
```

需要手动显式启动 HTTP 服务时：

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

可选：不在仓库目录执行时，再加 `--workspace-root <repo-root>`。

### 示例：驱动 wv screenshot 做验收

前置条件：

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

可直接复制的提示词：

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

期望结果：

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

### 示例：驱动 wv compare 做验收

可直接复制的提示词：

```text
你现在连接的是 weapp-vite MCP。请帮我完成一次小程序截图对比验收：
1. 先阅读 node_modules/weapp-vite/dist/docs/index.md、node_modules/weapp-vite/dist/docs/ai-workflows.md 和 node_modules/weapp-vite/dist/docs/mcp.md。
2. 构建 e2e-apps/auto-routes-define-app-json（platform=weapp）。
3. 如果 MCP 提供 `compare_weapp_screenshot` 工具，优先使用它；否则执行 `wv compare`，参数如下：
   - projectPath: e2e-apps/auto-routes-define-app-json/dist/build/mp-weixin
   - page: pages/home/index
   - baselinePath: .screenshots/baseline/home.png
   - diffOutputPath: .tmp/mcp-home.diff.png
   - maxDiffPixels: 100
   - 使用 JSON 结果
4. 如果对比通过，输出 compare-ok；否则输出 compare-failed。
5. 最后汇总：执行命令、关键输出、最终结论。
```

## AI 终端里的 DevTools 日志桥接

除了 MCP，`weapp-vite` 现在也支持把微信开发者工具里的小程序 `console` 日志直接桥接回 AI 终端。

这对下面几类场景特别有用：

1. 你让 AI 帮你改了一个页面或组件，想立刻看运行时日志。
2. 你在做 DevTools automator / 截图验收，希望终端里同时看到页面报错。
3. 你不想在「代码编辑器 / AI 终端 / DevTools 控制台」之间反复切换。

### 最小工作流

前置条件：

1. 微信开发者工具已登录。
2. 已开启「设置 -> 安全设置 -> 服务端口」。
3. 项目使用 `weapp-vite` 默认配置，或显式开启了 `weapp.forwardConsole`。

如果你当前就在 AI 终端里工作，推荐直接执行：

```bash
pnpm dev --open
```

默认配置下，`weapp.forwardConsole.enabled = 'auto'`。这意味着：

* 在普通人类终端里，默认不会自动附加日志桥。
* 在 Codex、Claude Code、Cursor CLI 等 AI 终端里，会自动尝试把小程序日志桥接回当前终端。

如果你希望手动进入持续监听模式，而不依赖自动检测，可执行：

```bash
wv ide logs --open
```

这个命令会：

1. 打开微信开发者工具。
2. 连接小程序 automator 会话。
3. 持续输出 `console.log / info / warn / error` 与未捕获异常。
4. 一直保持运行，直到你按 `Ctrl+C` 主动退出。

## 推荐的 AI 工具优先级

为了减少 AI 误用普通浏览器工具，建议统一约定以下优先级：

| 用户意图                                  | 默认工具                                  |
| ----------------------------------------- | ----------------------------------------- |
| 截图、页面快照、runtime screenshot        | `wv screenshot` / `take_weapp_screenshot` |
| 截图对比、baseline、diff、视觉回归        | `wv compare` / `compare_weapp_screenshot` |
| DevTools 日志、运行时日志、小程序 console | `wv ide logs --open`                      |
| 读取当前安装版本的本地说明                | `node_modules/weapp-vite/dist/docs/*.md`  |

只有当目标明确是 Web runtime，而不是微信开发者工具里的小程序运行时，才改用浏览器自动化、网页截图或 Playwright 一类 Web 工具。

### 推荐给 AI 的提示词

下面这段提示词适合直接发给接入终端能力的 AI：

```text
请在当前 weapp-vite 项目里帮我做一次 DevTools 终端联调：
1. 用 weapp 平台启动开发命令，并打开微信开发者工具。
2. 如果当前终端没有自动看到小程序 console，请改用 `wv ide logs --open` 进入持续监听。
3. 复现页面操作后，汇总终端里看到的 console 输出、warn、error 和未捕获异常。
4. 最后给出结论：问题是否已经复现、最关键的日志是哪一条、下一步建议改哪里。
```

### 相关配置

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

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

更多字段说明见：[共享配置：weapp.forwardConsole](/config/shared#weapp-forwardconsole)

## 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. [AI Skills 使用指南](/guide/skills)
3. [AI 任务工作流](/guide/ai-workflows)
4. [共享配置：weapp.forwardConsole](/config/shared#weapp-forwardconsole)
5. [共享配置：weapp.mcp](/config/shared#weapp-mcp)
6. [调试与贡献](/guide/debug)
7. [@weapp-vite/mcp 包说明](/packages/mcp)
8. [AI 学习入口](/ai)

---

---
url: /guide/skills.md
description: 按任务场景选择 Weapp-vite 公开 Skills，说明安装方式、触发边界、关联文档和最小验证命令。
---

# AI Skills 使用指南

`Skills` 用来把仓库里的工程约束、验证路径和交付规则注入给 AI。它解决的不是“让 AI 多知道一个名词”，而是让 AI 在具体任务里按稳定流程工作。

## 什么时候需要安装

| 场景                                | 推荐动作                                    |
| ----------------------------------- | ------------------------------------------- |
| 新项目通过 `create-weapp-vite` 创建 | 在脚手架交互提示里选择安装推荐 skills       |
| 已有项目接入 `weapp-vite`           | 手动执行 `npx skills add sonofmagic/skills` |

```sh
npx skills add sonofmagic/skills
```

## 公开 Skills 速查

当前公开分发的 skill 以仓库 `skills/*/SKILL.md` 为准：

| Skill                                   | 适用任务                                                                            | 优先读取                                                                    |
| --------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `$weapp-vite-best-practices`            | `vite.config.ts`、分包、chunk、自动路由、CLI、MCP、DevTools 命令归属                | 根 `AGENTS.md`、`node_modules/weapp-vite/dist/docs/`、`website/config/**`   |
| `$docs-and-website-sync`                | 根据真实实现同步 `website`、README、skills、AI 指南和随包 `dist/docs`               | 源码、CLI、类型定义、`packages/weapp-vite/docs/**`、`website/.vitepress/**` |
| `$release-and-changeset-best-practices` | changeset 判断、发布检查、GitHub issue 修复、worktree 与 PR 闭环                    | `.changeset/**`、`e2e-apps/github-issues`、发布检查脚本                     |
| `$weapp-devtools-e2e-best-practices`    | `e2e/ide/**`、automator 复用、`miniProgram.reLaunch(...)`、真实运行时截图和日志验收 | `e2e/ide/**`、`e2e/scripts/**`、DevTools 配置                               |
| `$weapp-vite-vue-sfc-best-practices`    | 小程序 `.vue`、JSON 宏、`definePageMeta`、layout、`v-model`、模板兼容               | `.weapp-vite` 类型文件、Vue SFC 文档、模板兼容清单                          |
| `$wevu-best-practices`                  | wevu 生命周期、事件、store、router、layout、运行时性能治理                          | `packages-runtime/wevu`、wevu 文档、运行时排障清单                          |
| `$native-to-weapp-vite-wevu-migration`  | 原生小程序迁移到 `weapp-vite + 原生`，或继续升级到 `weapp-vite + wevu + Vue SFC`    | 路线选择、迁移清单、API 映射、回滚与验收计划                                |

## 任务路由建议

| 用户意图                                                 | 主 skill                                | 常见次 skill                                           |
| -------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------ |
| “帮我调分包、chunk、自动路由或 CLI”                      | `$weapp-vite-best-practices`            | `$weapp-vite-vue-sfc-best-practices`                   |
| “根据当前实现更新 website / skills / README”             | `$docs-and-website-sync`                | `$weapp-vite-best-practices`                           |
| “这个 issue 要按仓库流程修完并开 PR”                     | `$release-and-changeset-best-practices` | `$wevu-best-practices` 或 `$weapp-vite-best-practices` |
| “新增 DevTools runtime e2e 或截图验收”                   | `$weapp-devtools-e2e-best-practices`    | `$weapp-vite-best-practices`                           |
| “`.vue` 宏、模板或 `usingComponents` 不生效”             | `$weapp-vite-vue-sfc-best-practices`    | `$weapp-vite-best-practices`                           |
| “wevu 生命周期、store 或页面切换行为异常”                | `$wevu-best-practices`                  | `$weapp-vite-vue-sfc-best-practices`                   |
| “原生项目先接入 weapp-vite，或逐步迁移到 Vue SFC / wevu” | `$native-to-weapp-vite-wevu-migration`  | `$weapp-vite-best-practices` 或 `$wevu-best-practices` |

## 给 AI 的推荐提示词

```text
请先判断本任务应该使用哪个 weapp-vite skill。
如果任务涉及当前安装版本，请优先读取 node_modules/weapp-vite/dist/docs/。
如果任务涉及真实小程序运行时截图、截图对比或日志，请优先使用 wv screenshot、wv compare、wv ide logs --open 或对应 MCP tools。
最后请给出：使用的 skill、改动文件、验证命令和结论。
```

## 维护公开 Skills

新增、删除或合并 skill 时，需要同步这些入口：

| 入口                                                | 需要同步的内容                                |
| --------------------------------------------------- | --------------------------------------------- |
| `skills/<name>/SKILL.md`                            | skill 正文、触发场景、输出要求                |
| `skills/<name>/agents/openai.yaml`                  | display name、short description、隐式触发提示 |
| `skills/skill-trigger-regression-checklist.md`      | 主用例、边界用例、冲突场景                    |
| `skills/scripts/score-skill-trigger-regression.mjs` | 预期 skill 映射与统计分组                     |
| `website/guide/skills.md`                           | 对外索引、任务路由和关联文档                  |
| `website/guide/ai.md` 与 `/ai` 页面                 | 安装方式和公开 skill 清单                     |
| `CLAUDE.md` / 脚手架 `AGENTS.md` 模板               | AI 客户端可见的默认清单                       |

完成后至少运行：

```sh
pnpm skills:check:yaml
pnpm skills:score:json
pnpm seo-quality-check
```

## 关联阅读

1. [AI 协作指南](/guide/ai)
2. [AI 任务工作流](/guide/ai-workflows)
3. [CLI 命令参考](/guide/cli)
4. [@weapp-vite/mcp 包说明](/packages/mcp)

---

---
url: /guide/ai-workflows.md
description: 将 Weapp-vite 常见 AI 协作任务拆成可执行流程，覆盖 issue 修复、文档同步、DevTools e2e、SFC 排障和原生迁移。
---

# AI 任务工作流

本文把常见 AI 协作任务整理成“入口、事实源、执行步骤、验收信号”。如果你还不确定该先用哪个 skill，先看 [AI Skills 使用指南](/guide/skills)。

## 工作流总览

| 任务                         | 主 skill                                | 事实源                                                      | 验收信号                                |
| ---------------------------- | --------------------------------------- | ----------------------------------------------------------- | --------------------------------------- |
| 同步网站和 skills 文档       | `$docs-and-website-sync`                | 源码、CLI、类型定义、随包 docs、VitePress 配置              | 相关入口一致，`seo-quality-check` 通过  |
| 修 GitHub issue              | `$release-and-changeset-best-practices` | issue 描述、最小复现、单测、e2e                             | 复现先失败后通过，changeset 判定清楚    |
| 调整项目配置或 CLI           | `$weapp-vite-best-practices`            | `vite.config.ts`、`packages/weapp-vite/src/**`、`dist/docs` | 目标包先 build，下游窄范围验证通过      |
| 排查 Vue SFC 编译或模板      | `$weapp-vite-vue-sfc-best-practices`    | `.vue`、JSON 宏、`.weapp-vite` 类型支持文件                 | `wv prepare` 后类型与产物一致           |
| 排查 wevu 运行时行为         | `$wevu-best-practices`                  | 生命周期、事件、store、router、运行时日志                   | 单测或 DevTools runtime 信号稳定        |
| 新增 DevTools e2e            | `$weapp-devtools-e2e-best-practices`    | `e2e/ide/**`、automator 会话、项目配置                      | suite 复用 automator，`reLaunch` 串场景 |
| 原生迁移到 Weapp-vite / Wevu | `$native-to-weapp-vite-wevu-migration`  | 原生页面、路线选择、迁移映射、回滚点、截图日志              | 分波次迁移，每波有可回滚验收            |

## 文档同步

适用场景：

1. CLI、配置项、MCP、截图、日志或模板能力变化。
2. `website`、README、skills、`dist/docs` 或脚手架 `AGENTS.md` 出现不一致。
3. 新增、删除、合并 skill。

推荐流程：

1. 使用 `$docs-and-website-sync`。
2. 先查真实实现，不要在旧文案之间互相复制。
3. 按“能力变化 -> 公开入口”建立修改清单。
4. 同步 `website/guide/ai.md`、`website/guide/skills.md`、`website/.vitepress/components/AiLearningPage.vue` 和相关包说明。
5. 如果涉及随包文档，检查 `packages/weapp-vite/docs/**` 与 `packages/weapp-vite/scripts/sync-package-docs.mjs`。
6. 运行最小验证。

```sh
pnpm skills:check:yaml
pnpm seo-quality-check
pnpm --filter website-weapp-vite build
```

## GitHub issue 修复

适用场景：

1. 用户明确给出 GitHub issue。
2. 需要在 `e2e-apps/github-issues` 增加复现。
3. 修复会影响运行时、构建行为或用户可见输出。

推荐流程：

1. 使用 `$release-and-changeset-best-practices`。
2. 按仓库规则在 `.codex-tmp/<issue>` 创建本地 worktree。
3. 先补最小复现，确认修复前失败。
4. 再分析根因并修改对应包。
5. 包源码变化后，先重建 touched package，再做下游验证。
6. 判断是否需要 changeset；行为修复通常需要。
7. 本地验证完成后开中文 PR。

验收输出应包含：

| 项   | 要求                         |
| ---- | ---------------------------- |
| 复现 | 说明新增的最小用例和失败信号 |
| 修复 | 说明根因和修改文件           |
| 验证 | 列出实际运行的窄范围命令     |
| 发布 | 说明 changeset 和 PR 状态    |

## DevTools runtime 验收

适用场景：

1. 需要真实微信开发者工具运行时信号。
2. 需要截图、截图对比、console 日志或页面结构检查。
3. 需要新增 `e2e/ide/**` 用例。

推荐流程：

1. 使用 `$weapp-devtools-e2e-best-practices`。
2. 先确认没有残留 E2E、DevTools 或 watch 进程。
3. 同一个 app suite 内只启动一次 automator。
4. 多页面场景通过 `miniProgram.reLaunch(...)` 切换。
5. 截图优先用 `wv screenshot` 或 `take_weapp_screenshot`。
6. 日志优先用 `wv ide logs --open` 或 MCP DevTools runtime tools。

```sh
wv screenshot --json
wv compare --json
wv ide logs --open
```

## SFC 与 wevu 排障

如果主问题是 `.vue` 宏、模板编译、`v-model` 或 `usingComponents`，优先使用 `$weapp-vite-vue-sfc-best-practices`。

执行顺序：

1. 先读项目根 `AGENTS.md` 和本地 `node_modules/weapp-vite/dist/docs/vue-sfc.md`。
2. 检查 `definePageJson`、`definePageMeta`、`usingComponents` 和 `<json>` 是否职责混杂。
3. `.weapp-vite` 类型文件漂移时先执行 `wv prepare`。
4. 再做页面级或组件级验证。

如果主问题是生命周期、store、事件、router、页面切换或性能，优先使用 `$wevu-best-practices`。

执行顺序：

1. 确认生命周期注册是否同步发生在 `setup()` 内。
2. 检查 store 解构是否使用 `storeToRefs`。
3. 检查事件 `detail` 与小程序事件契约是否稳定。
4. 性能问题先找高频 `setData`、滚动事件、资源缓存和页面切换链路。

## 原生迁移

适用场景：

1. 原生项目要先迁移到 `weapp-vite + 原生`。
2. 原生 `Page/Component` 要进一步逐步迁移到 Vue SFC。
3. 迁移期间必须可回滚。
4. 迁移后需要 AI 能继续稳定维护项目。

推荐流程：

1. 使用 `$native-to-weapp-vite-wevu-migration`。
2. 先判断路线 A（`weapp-vite + 原生`）还是路线 B（`weapp-vite + wevu + Vue SFC`）。
3. 先拆波次，不把工具链接入、机械迁移和语义升级混在同一轮。
4. 每波迁移前记录页面入口、原生 API、事件契约和回滚点。
5. 路线 A 只收口构建、TS、路径、资源、DevTools、截图日志和 AI 指引。
6. 路线 B 再把 `properties/observers/triggerEvent` 分别映射到 `defineProps/watch/defineEmits`。
7. 迁移后补截图、日志或 e2e 验收，并更新项目 AI 指引。

## 给 AI 的统一交付格式

```text
请按 weapp-vite 项目规则处理这个任务。
输出必须包含：
1. 使用的主 skill 和必要的次 skill。
2. 先读取的事实源。
3. 修改的文件。
4. 执行的验证命令。
5. 未执行验证时说明原因。
```

## 关联阅读

1. [AI 协作指南](/guide/ai)
2. [AI Skills 使用指南](/guide/skills)
3. [CLI 命令参考](/guide/cli)
4. [调试与贡献](/guide/debug)

---

---
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": {
    "postinstall": "wv prepare",
    "dev": "wv dev",
    "build": "wv build",
    "open": "wv open",
    "analyze": "wv analyze",
    "prepare": "wv prepare"
  }
}
```

后续运行时只需执行 `pnpm run dev` / `pnpm run build` 等常规命令；`postinstall` 与显式 `prepare` 则用于提前生成 `.weapp-vite/*` 托管类型文件。

### 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/**/*", ".weapp-vite/**/*.d.ts"]
}
```

```json
// tsconfig.node.json
{
  "compilerOptions": {
    "composite": true,
    "module": "ESNext",
    "moduleResolution": "Node"
  },
  "include": ["vite.config.ts", "weapp-vite.config.ts"]
}
```

### vite.config.ts / weapp-vite.config.ts

在项目根目录创建 `vite.config.ts` 或 `weapp-vite.config.ts`：

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

export default defineConfig({
  weapp: {
    srcRoot: 'src', // 若原项目位于 miniprogram，可改为 './miniprogram'
    autoRoutes: true,
    chunks: {
      sharedStrategy: 'duplicate',
    },
  },
})
```

如果两个文件同时存在，`weapp-vite` 会把 `weapp-vite.config.*` 中的 `weapp` 配置与 `vite.config.*` 合并；如果你只想保留一个文件，也完全可以只保留其中任意一个。

`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`。
4. 如果只想先生成类型支持文件而不启动开发服务，可单独执行 `pnpm run prepare`。

## 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": "wv generate"`，之后执行 `pnpm run g pages/dashboard` 快速生成页面文件夹。

这样就完成了在现有小程序中的手动集成，无需依赖 `create` 或 `init` 脚本。

---

---
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: /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`，所以你只要完成这些配置，就能在代码中直接使用别名。`paths` 不再强依赖 `baseUrl`；没有 `baseUrl` 时会相对当前 tsconfig 所在目录解析。

例如：

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "./*"
      ]
    }
  }
}
```

然后你就可以在代码里这样写：

```ts
import utils from '@/utils'
```

运行 `wv dev` / `wv build` 时，别名会被自动解析成真实文件位置。

> \[!TIP]
> 默认场景建议直接使用原生 `resolve.tsconfigPaths`。如果需要指定多个 `tsconfig` 或忽略某些目录，再在 `vite.config.ts` 或 `weapp-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-vite.config.ts` 中配置 [`weapp.jsonAlias.entries`](/config/json.md#weapp-jsonalias)。语法与 Vite 的 `resolve.alias` 完全一致：

`compilerOptions.paths` 只负责 JS/TS 模块解析，不会默认用于 JSON / JSONC 的 `usingComponents`。如果需要在 JSON 中使用别名，请显式配置 `weapp.jsonAlias.entries`；如果需要完全关闭 JSON 别名，设置 `weapp.jsonAlias=false`。

> `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-vite.config.ts` 中配置 [`weapp.tsconfigPaths.projects`](../config/js.md#weapp-tsconfigpaths) 指定额外的配置文件，让 monorepo 子包共享同一套别名。

---

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

# npm 自动构建

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

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

## 自动构建

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

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

### 1. 构建到 `miniprogram_npm`（明确的小程序包 / 显式指定的包）

以下依赖会优先进入 npm 构建：

* 包自身就是小程序包，例如 `tdesign-miniprogram`、`@vant/weapp`
* 你在 `weapp.npm.include`、`mainPackage.dependencies`、`pluginPackage.dependencies`、`subPackages.<root>.dependencies` 里显式指定的包

这些依赖会输出到 `project.config.json` 的 `miniprogramNpmDistDir` 目录下（也就是 `miniprogram_npm/`）。

### 2. 内联到脚本产物（默认行为）

没有命中 npm 构建规则的依赖，不管它写在 `dependencies` 还是 `devDependencies`，在被 `import`/`require` 后都会被构建器打包并**内联**到对应的页面/组件脚本里。

### 详细解释

看一个最常见的例子：

```json
{
  "dependencies": {
    "lodash": "^4.17.21",
    "tdesign-miniprogram": "^1.12.3"
  },
  "devDependencies": {
    "lodash-es": "^4.17.21",
    "@vant/weapp": "^1.11.6"
  }
}
```

其中：

* `lodash`、`lodash-es` 都会默认内联进页面脚本
* `tdesign-miniprogram`、`@vant/weapp` 会默认进入 `miniprogram_npm`

在页面里分别引入它们时，Weapp-vite 的处理方式大致如下：

* **普通依赖 → 内联到页面脚本**：构建期会转成普通 JavaScript，并直接合并进页面入口，避免额外的 npm 目录。
  ```js
  var add = /* lodash add 的实现主体 */
  Page({
    data: {
      num0: add(1, 1),
    },
  })
  ```
* **小程序包 → 构建 `miniprogram_npm`**：产物保留包路径引用，依赖会被同步到 `miniprogram_npm`。
  ```js
  const button = require('tdesign-miniprogram/button/button')
  Page({
    components: { button },
  })
  ```

> \[!TIP]
> 实际内联出来的代码会比示例长得多（可能包含工具函数等），但你不需要手动维护。默认情况下，Weapp-vite 会优先把依赖当普通包处理；只有明确的小程序包或你显式指定的包，才会进 `miniprogram_npm`。

### 怎么选（建议）

* **普通运行时库**：照常放进 `dependencies` 或 `devDependencies`，默认都会被 Vite 内联。
* **明确的小程序组件库**：直接安装即可，默认会进 `miniprogram_npm`。
* **想让普通依赖也进入 `miniprogram_npm`**：用 `weapp.npm.include` 或包级 `dependencies` 配置显式声明。
* **仅开发/构建期使用的工具**：放进 `devDependencies`。
* **想恢复旧规则**：把 `weapp.npm.strategy` 设成 `'legacy'`。

## 手动构建

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

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

> `wv npm` 别名 `wv build:npm` / `wv build-npm`

---

---
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`）。它适合两类情况：

* 你不想每次都手动建目录、复制四件套模板
* 团队希望统一目录和文件后缀，减少“每个人生成出来都不一样”

## 快速上手

命令形式为 `wv generate [outDir]`，别名 `wv g [outDir]`。在执行 `wv init` 后，`package.json` 中会新增脚本 `pnpm g`，方便在项目中调用。

示例：在项目根目录执行：

```sh
pnpm g components/avatar
# 或直接调用二进制
pnpm wv g components/avatar
```

默认会创建如下结构：

```text
.
└── components
    └── avatar
        ├── avatar.json
        ├── avatar.js
        ├── avatar.wxss
        └── avatar.wxml
```

> \[!TIP]
> `wv init` 会自动把脚本添加到 `package.json`。如果你在现有项目中手动安装了 Weapp-vite，也可以自行补上 `"g": "wv 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: /guide/auto-routes.md
description: weapp-vite 提供可选的自动路由能力，扫描主包和分包页面目录，生成路由清单、类型声明与虚拟模块导出。
---

# 自动路由（`weapp-vite/auto-routes`）

`weapp-vite` 提供了一个可选的“自动路由”能力：扫描主包/分包的页面目录，自动生成路由清单，并通过虚拟模块 `weapp-vite/auto-routes` 导出。

它解决的核心问题是：**生成一份随目录变化的路由清单**，供 `app.json.ts` 或业务代码消费，同时在 TypeScript 里还能拿到“页面路径”的类型提示，避免字符串写错。

## 适用场景

* 团队遵循约定式目录结构，希望“新增页面 = 自动进清单”，再由 `app.json.ts` 自动组装。
* 希望在 TypeScript 里拿到页面路径的类型提示（少写错、少返工）。
* 想区分主包/分包入口，用于生成导航菜单、埋点清单等数据。

## 快速开启

自动路由默认关闭；如果想启用或做细粒度控制，可以在 `vite.config.ts` 或 `weapp-vite.config.ts` 中配置：

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

export default defineConfig({
  weapp: {
    autoRoutes: {
      enabled: true,
      typedRouter: true,
      include: ['pages/**'],
      persistentCache: false,
      watch: true,
    },
  },
})
```

启用后会自动完成以下工作：

* 生成 `.weapp-vite/typed-router.d.ts`，里面包含 `AutoRoutes` 等类型；
* 暴露虚拟模块 `weapp-vite/auto-routes`，默认导出完整路由对象，并额外提供 `entries`、`pages`、`subPackages` 等数组；
* 在开发与构建过程中持续监听页面相关文件，增删改都会立刻刷新清单并触发热更新。

如果你还没跑过 `dev/build`，但希望先把这些支持文件产出来，也可以手动执行：

```bash
wv prepare
```

## 默认扫描规则

不传 `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.*` 或 `weapp-vite.config.*` 所在目录解析；如果没有配置文件路径，则退回到当前工作目录。

如果你在项目里使用 `wevu` 的 `useNativeRouter()/useNativePageRouter()`，或 `wevu/router` 的 `useRouter()`，`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/layouts.md
description: >-
  详细说明 weapp-vite 的页面 layout 能力，包括 srcRoot/layouts
  目录约定、definePageMeta、routeRules 与运行时 setPageLayout 切换。
---

# 页面 Layout 使用指南

`weapp-vite` 现在已经支持接近 Nuxt `app/layouts` 的页面布局能力。它不是单独某一个配置项，而是由“目录约定 + 编译期声明 + 配置层回退 + 运行时切换”四部分协同完成。

## 1. 先理解这套能力解决什么问题

如果你的项目里有这些重复结构：

* 页面统一的头部、底部、侧边栏
* 后台页、营销页、沉浸式页三种不同壳子
* 同一个页面在运行时需要切换“带壳”和“无壳”两种模式

那就适合用 layout，而不是在每个页面里重复包一层公共组件。

| 能力                                  | 作用                       |
| ------------------------------------- | -------------------------- |
| `srcRoot/layouts/**`                  | 声明可用的布局组件         |
| `definePageMeta({ layout })`          | 在页面里显式指定布局       |
| `weapp.routeRules`                    | 为一批页面批量设置默认布局 |
| `setPageLayout()` / `usePageLayout()` | 在运行时切换或读取当前布局 |

## 2. layout 放在哪里

默认约定是放在 `srcRoot/layouts/` 下：

```txt
src/
├─ layouts/
│  ├─ default.vue
│  ├─ admin.vue
│  └─ native-shell/
│     ├─ index.json
│     ├─ index.wxml
│     ├─ index.wxss
│     └─ index.ts
└─ pages/
   └─ dashboard/
      └─ index.vue
```

支持两种 layout 形式：

| 形式        | 说明                     | 典型文件                          |
| ----------- | ------------------------ | --------------------------------- |
| Vue layout  | 用 Vue SFC 写页面壳      | `layouts/default.vue`             |
| 原生 layout | 用原生小程序组件写页面壳 | `layouts/native-shell/index.wxml` |

layout 名称由相对 `layouts/` 的路径推导：

| 文件位置                       | 推导出的 layout 名 |
| ------------------------------ | ------------------ |
| `layouts/default.vue`          | `default`          |
| `layouts/admin.vue`            | `admin`            |
| `layouts/native-shell/index.*` | `native-shell`     |

> **注意**：`default` 具有特殊意义。只要它存在，页面在没有显式声明 `layout` 时，就会优先尝试命中默认布局。

## 3. 页面里怎么声明 layout

### 3.1 默认命中 `default`

如果项目里存在 `src/layouts/default.vue`，而页面没有写 `definePageMeta({ layout })`，就会自动使用默认布局。

```vue
<script setup lang="ts">
definePageJson(() => ({
  navigationBarTitleText: '默认布局页面',
}))
</script>

<template>
  <view>page content</view>
</template>
```

### 3.2 显式指定命名 layout

```vue
<script setup lang="ts">
definePageMeta({
  layout: 'admin',
})
</script>

<template>
  <view>admin content</view>
</template>
```

### 3.3 指定 layout + props

```vue
<script setup lang="ts">
definePageMeta({
  layout: {
    name: 'admin',
    props: {
      sidebar: true,
      title: '控制台',
    },
  },
})
</script>
```

### 3.4 显式关闭 layout

```vue
<script setup lang="ts">
definePageMeta({
  layout: false,
})
</script>
```

这类页面适合登录页、全屏页、沉浸式落地页。

## 4. `definePageMeta({ layout })` 的约束

这部分需要特别注意，因为它是编译期静态分析的：

| 支持的写法                                         | 是否支持 |
| -------------------------------------------------- | -------- |
| `layout: 'admin'`                                  | ✅       |
| `layout: false`                                    | ✅       |
| `layout: { name: 'admin', props: { title: 'A' } }` | ✅       |
| `layout: someRef.value`                            | ❌       |
| `layout: computed(() => 'admin')`                  | ❌       |
| `props: dynamicObject`                             | ❌       |

也就是说：

* `layout` 只支持静态字符串、`false`，或 `{ name, props }` 对象
* `props` 必须是对象字面量
* `props` 的键名必须是静态键名

> **提示**：如果你需要按状态切换 layout，不要把 `layout.name` 写成响应式值，而应该改用运行时 `setPageLayout()`。

## 5. `routeRules` 怎么和 layout 配合

如果你不想每个页面都手写 `definePageMeta({ layout })`，可以在 `vite.config.ts` 或 `weapp-vite.config.ts` 里用 `weapp.routeRules` 批量声明默认布局。

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

export default defineConfig({
  weapp: {
    routeRules: {
      'pages/dashboard/**': {
        appLayout: 'dashboard',
      },
      'pages/admin/**': {
        appLayout: {
          name: 'admin',
          props: {
            sidebar: true,
            title: 'Admin',
          },
        },
      },
    },
  },
})
```

### 5.1 优先级

优先级从高到低：

1. 页面源码里的 `definePageMeta({ layout })`
2. `weapp.routeRules`
3. `srcRoot/layouts/default.*`

如果页面显式写了：

```ts
definePageMeta({
  layout: false,
})
```

那就会跳过默认 layout 包裹。

## 6. 运行时怎么切换 layout

如果页面需要在运行过程中切换 layout，可以使用 `setPageLayout()`。

### 6.1 Wevu 页面写法

```vue
<script setup lang="ts">
import { ref, setPageLayout, usePageLayout } from 'wevu'

const currentLayout = ref<'default' | 'admin' | 'none'>('default')
const pageLayout = usePageLayout()

function applyDefaultLayout() {
  currentLayout.value = 'default'
  setPageLayout('default')
}

function applyAdminLayout() {
  currentLayout.value = 'admin'
  setPageLayout('admin', {
    title: '业务后台布局',
    subtitle: '这个标题来自 setPageLayout() 运行时传入的 props。',
  })
}

function clearLayout() {
  currentLayout.value = 'none'
  setPageLayout(false)
}

console.log(pageLayout.name)
</script>
```

### 6.2 原生 Page 写法

原生页面也可以切换 layout。当前 `setPageLayout` 也会从 `weapp-vite/runtime` 侧暴露给原生 Page 使用。

```ts
import { setPageLayout } from 'weapp-vite/runtime'

Page({
  onLoad() {
    setPageLayout('default')
  },
  applyAdminLayout() {
    setPageLayout('admin', {
      title: 'Native Console',
      subtitle: '这个标题来自原生 Page 调用 setPageLayout()。',
    })
  },
  clearLayout() {
    setPageLayout(false)
  },
})
```

### 6.3 `usePageLayout()` 有什么用

`usePageLayout()` 用于读取当前页面的 layout 状态：

```ts
import { usePageLayout } from 'wevu'

const pageLayout = usePageLayout()

if (pageLayout.name === 'admin') {
  console.log(pageLayout.props.title)
}
```

当项目里存在 layout 扫描结果时，`.weapp-vite/wevu-layouts.d.ts` 会自动增强 `WevuPageLayoutMap`，从而让 `layout.name` 与 `props` 拿到更严格的类型提示。

## 7. page 和 layout 怎么通信

layout 不只是“包一层壳”，还经常要解决页面和壳子之间的数据流与能力协作。建议先把几种通信方式的边界分清楚：

| 方式                                                          | 方向                     | 适合场景                   | 推荐程度 |
| ------------------------------------------------------------- | ------------------------ | -------------------------- | -------- |
| `definePageMeta({ layout: { name, props } })`                 | page -> layout           | 静态标题、模式、文案       | 高       |
| `setPageLayout(name, props)`                                  | page -> layout           | 运行时切换 layout 与 props | 高       |
| `usePageLayout()`                                             | page 读取 layout 状态    | 页面感知当前壳子模式       | 高       |
| store + page `watch`                                          | store -> page -> layout  | 统一管理布局状态与交互意图 | 高       |
| `layout-host` / `resolveLayoutHost()` / `waitForLayoutHost()` | page/组件 -> layout 宿主 | toast、dialog、反馈节点    | 高       |
| `provide()` / `inject()`                                      | 当前实例或全局兜底       | 局部上下文共享             | 低       |

### 7.1 通过 layout props 通信

最直接的方式是由页面把布局需要的静态信息传给 layout，例如标题、副标题、页面模式、头部按钮文案。

编译期静态场景：

```vue
<script setup lang="ts">
definePageMeta({
  layout: {
    name: 'admin',
    props: {
      title: '订单中心',
      subtitle: '这里的 props 会直接传给 admin layout。',
    },
  },
})
</script>
```

运行时动态场景：

```vue
<script setup lang="ts">
import { setPageLayout } from 'wevu'

function switchToReviewMode() {
  setPageLayout('admin', {
    title: '审核中心',
    subtitle: '标题和副标题由页面在运行时切换。',
  })
}
</script>
```

> **提示**：如果你的目标只是“页面告诉 layout 现在该显示什么”，优先用 `props`，不要一开始就引入额外的全局通信层。

### 7.2 页面读取当前 layout 状态

页面也可以通过 `usePageLayout()` 读取当前命中的 layout 名称与 props。这在“页面自身也要根据 layout 模式调整局部 UI”时很有用。

```vue
<script setup lang="ts">
import { computed, usePageLayout } from 'wevu'

const layout = usePageLayout()
const isAdminLayout = computed(() => layout.name === 'admin')
</script>

<template>
  <view>
    <text>当前布局：{{ layout.name || 'none' }}</text>
    <text v-if="isAdminLayout">{{ layout.props.title }}</text>
  </view>
</template>
```

适合这类场景：

* 页面想知道自己当前是否处于 `admin` / `default` / `false`
* 页面上的某个区块需要跟着 layout 模式切换
* 调试运行时布局切换结果

### 7.3 通过 store 让页面协调 layout

当 layout 状态来自 store 时，推荐的边界是：

* store 只保存“布局状态”和“交互意图”
* 页面负责 `watch` store，并调用 `setPageLayout()`
* layout 继续只关心自己的 props 和宿主能力

示例可以参考 e2e 用例里的 `e2e-apps/template-wevu-tdesign-regression/src/pages/layout-store/index.vue`。

```vue
<script setup lang="ts">
import { setPageLayout, storeToRefs, watch } from 'wevu'
import { useLayoutInteractionDemoStore } from '@/stores/layoutInteractionDemo'

const store = useLayoutInteractionDemoStore()
const { activeLayout, adminLayoutProps } = storeToRefs(store)

watch([activeLayout, adminLayoutProps], ([layout, props]) => {
  if (layout === 'admin') {
    setPageLayout('admin', props)
    return
  }
  setPageLayout('default')
}, { immediate: true })
</script>
```

这样做的好处是：

* store 不需要直接依赖 page runtime hook
* layout 切换逻辑仍然留在页面上下文，职责更清晰
* 后续替换 layout、增加平台差异处理时更容易收敛

### 7.4 通过 `layout-host` 暴露 layout 内宿主能力

有些能力天然属于 layout，而不是页面内容本身，例如 toast、dialog、抽屉、全局反馈层。这时更推荐把它们放在 layout 中，再通过 `layout-host` 暴露给页面或子组件使用。

layout 侧：

```vue
<template>
  <view class="layout-admin">
    <slot />
    <t-toast layout-host="layout-toast" />
    <t-dialog layout-host="layout-dialog" />
  </view>
</template>
```

页面或组件侧：

```ts
import { resolveLayoutHost, waitForLayoutHost } from 'wevu'

const toast = resolveLayoutHost<any>('layout-toast')
toast?.show?.({ message: '操作成功' })

const dialog = await waitForLayoutHost<any>('layout-dialog')
dialog?.show?.({ title: '确认删除？' })
```

这类模式的重点不是“拿到 layout 实例”，而是“拿到 layout 暴露出来的宿主能力”。因此建议：

* 页面/组件只调用业务 hook 或 `resolveLayoutHost()` / `waitForLayoutHost()`
* 不直接手写 `selectComponent()` 去找 layout 内部节点
* layout 内部组件的选择器和实现细节由 layout 自己维护

> **提示**：如果你的项目已经封装了 `useToast()`、`useDialog()` 一类 hook，优先让这些 hook 内部对接 `layout-host`，而不是把 layout 结构细节散落到页面代码里。

TDesign Toast/Dialog 可以按下面的形态封装为模板级 recipe。核心约束是：页面只调用业务 hook，hook 内部再解析 layout 暴露的宿主实例。

```ts
import { getCurrentInstance, resolveLayoutHost } from 'wevu'

interface ToastHost {
  show: (options: { message: string, theme?: string }) => void
}

export function showToast(message: string, theme = 'default') {
  const context = getCurrentInstance()
  const toast = resolveLayoutHost<ToastHost>('layout-toast', { context })
  toast?.show({
    message,
    ...(theme === 'default' ? {} : { theme }),
  })
}
```

这种封装不属于 `wevu` core 的 UI 能力：`wevu` 只负责 `layout-host` 的注册与解析，具体的 Toast/Dialog 参数、按钮行为和关闭逻辑仍然由 TDesign 或业务 hook 维护。

### 7.5 不推荐直接把 layout 当成父组件做祖先注入

很多人会先想到 Vue Web 里的 `provide()` / `inject()`。但在当前 `wevu` 运行时语义下，这不是 page/layout 主通信手段。

原因是当前版本没有完整的祖先组件树查找语义，`inject()` 不会像 Web Vue 那样稳定地沿着“layout -> page -> 子组件”逐级向上查找。更准确地说：

* `provide()` / `inject()` 优先作用于当前实例上下文
* 找不到时会回落到全局存储
* 它适合局部共享或全局兜底，不适合承担 page/layout 主通信链路

所以：

* ✅ page -> layout 传参，优先 `definePageMeta(...props)` 或 `setPageLayout(...props)`
* ✅ layout 内能力暴露，优先 `layout-host`
* ✅ 跨页面稳定共享状态，优先 store
* ❌ 不要默认假设 layout 可以像 Vue 父组件一样稳定向 page `inject()`

## 8. Vue layout 和原生 layout 怎么选

| 场景                       | 更推荐的方式                  |
| -------------------------- | ----------------------------- |
| 页面本身就是 Vue SFC 项目  | 优先 Vue layout               |
| 你需要纯原生小程序组件布局 | 原生 layout                   |
| 团队里有大量原生 Page      | 原生 layout 更容易渐进迁移    |
| 需要和现有组件体系保持统一 | 优先与页面技术栈一致的 layout |

### 8.1 Vue layout 示例

```vue
<script setup lang="ts">
defineProps<{
  title?: string
  subtitle?: string
}>()
</script>

<template>
  <view class="layout-admin">
    <view class="layout-admin__header">
      {{ title || "后台布局" }}
    </view>
    <slot />
  </view>
</template>
```

### 8.2 原生 layout 示例

```wxml
<view class="layout-admin">
  <view class="layout-admin__header">{{title || '后台布局'}}</view>
  <slot></slot>
</view>
```

```json
{
  "component": true
}
```

## 9. layout 相关类型文件

启用 layout 后，常见会看到这些支持文件：

| 文件                            | 作用                       |
| ------------------------------- | -------------------------- |
| `.weapp-vite/wevu-layouts.d.ts` | 增强 `WevuPageLayoutMap`   |
| `.weapp-vite/components.d.ts`   | 补齐自动组件与布局组件类型 |

如果你在编辑器里没有拿到 layout 类型提示，优先检查：

1. 是否执行过 `wv prepare`
2. `tsconfig.json` 是否已经引用 `.weapp-vite/*`
3. `srcRoot/layouts/**` 是否位于当前项目真实源码根目录下

## 10. 常见问题

**Q1: 为什么我写了 `layout: computed(() => 'admin')` 不生效？**

因为 `definePageMeta({ layout })` 是编译期静态分析，不会执行响应式表达式。需要动态切换时请改用 `setPageLayout()`。

**Q2: 为什么 `default` 布局会自动包裹页面？**

因为 `default` 是约定式默认 layout。页面没写 `definePageMeta({ layout })` 时，会把它作为最后一层回退。

**Q3: 为什么原生页面也能切 layout？**

因为当前 runtime 已经为页面实例补齐了 `setPageLayout()` 的调用链，原生 Page 也可以显式切换当前页面壳。

**Q4: page 和 layout 之间推荐怎么通信？**

优先级建议是：`layout props` 解决 page -> layout 传参，`usePageLayout()` 解决页面读状态，`layout-host` 解决 layout 内宿主能力，store 负责跨页面或较复杂的交互状态。

**Q5: `provide()` / `inject()` 能不能拿来做 layout 到 page 的主通信？**

不建议。当前 `wevu` 没有完整的祖先组件树注入语义，`inject()` 更适合当前实例上下文共享或全局兜底，不应替代 layout props、store 或 `layout-host`。

## 11. 总结

layout 能力的核心不是“多一个配置项”，而是让“页面内容”和“页面外壳”真正分层：

* `srcRoot/layouts/**` 负责定义壳
* `definePageMeta({ layout })` 负责页面声明
* `routeRules` 负责批量回退
* `setPageLayout()` 负责运行时切换
* `layout-host` 负责暴露 layout 内部宿主能力

如果你现在要落地这套能力，建议先从 `default` + 一个命名 layout 开始，再按需要引入运行时切换。

最后可以按下面的顺序选型：

| 目标                     | 更推荐的方式                                  |
| ------------------------ | --------------------------------------------- |
| 页面给 layout 传静态信息 | `definePageMeta({ layout: { name, props } })` |
| 页面在运行时切换 layout  | `setPageLayout()`                             |
| 页面读取当前 layout      | `usePageLayout()`                             |
| 统一管理布局状态         | store + page `watch`                          |
| 访问 layout 内反馈节点   | `layout-host` / `resolveLayoutHost()`         |
| 共享全局状态             | store                                         |

## 12. 参考资源

| 主题                  | 推荐入口                                                          |
| --------------------- | ----------------------------------------------------------------- |
| Route Rules 与 Layout | [config/route-rules](/config/route-rules)                         |
| `layouts/` 目录说明   | [directory-structure/layouts](/guide/directory-structure/layouts) |
| Wevu 运行时 API       | [wevu/api/setup-context](/wevu/api/setup-context)                 |
| Wevu 运行时机制       | [wevu/runtime](/wevu/runtime)                                     |
| 目录结构总览          | [guide/directory-structure](/guide/directory-structure/)          |

---

---
url: /guide/auto-import.md
description: >-
  weapp-vite 可以在构建阶段自动扫描并注册组件，让你在 WXML 或 Vue SFC 模板里直接写组件标签，而不必手动维护
  usingComponents。
---

# 自动引入组件

`weapp-vite` 可以在构建阶段自动扫描并注册组件，让你在 WXML 或 Vue SFC 模板里直接写组件标签，而不需要手动维护 `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`。
>
> 当你显式写成 `autoImportComponents: true` 时，除了扫描组件目录，还会默认开启 `.weapp-vite/auto-import-components.json`、`.weapp-vite/typed-components.d.ts`、`.weapp-vite/mini-program.html-data.json` 与 `vueComponents` 输出。

## 适用场景

* 在模板里直接写 `<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 内掌控组件列表。

### 组件清单

默认会在 `.weapp-vite/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、微信开发者工具读取，实现标签/属性智能提示。
* `vueComponents`: 生成 `.weapp-vite/components.d.ts`，为 Vue SFC 模板补齐全局组件声明。

```ts
export default <UserConfig>{
  weapp: {
    autoImportComponents: {
      globs: ['components/**/*.wxml'],
      typedComponents: true, // 或 'types/typed-components.d.ts'
      vueComponents: true,
      htmlCustomData: 'dist/mini-program.html-data.json',
    },
  },
}
```

构建器会在组件扫描、resolver 匹配的同一流程中自动刷新这些文件，无需手动触发。

从 `weapp-vite 6.15.1` 开始，`components.d.ts` 在为“带源码跳转的原生组件”补齐 Vue 模板类型时，也会稳定合并小程序通用基础属性。这意味着像下面这样的写法不再被误报：

```vue
<template>
  <Tabbar id="main-tabbar" class="text-red" style="padding: 8rpx" />
</template>
```

如果你依赖组件库或业务组件在模板里接收 `class`、`style`、`id` 这类基础属性，建议保持 `vueComponents` 输出开启。

如果你需要在编辑器或 CI 预热阶段提前生成这些文件，可以执行：

```bash
wv prepare
```

## 常见疑问

* **为什么没自动注册？** 先检查组件 `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-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: /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: /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: /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: /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: /guide/subpackage.md
description: 微信小程序的分包机制在 Weapp-vite 中得到完整支持。本页帮你快速搞清楚两件事：
---

# 分包指南

微信小程序的分包机制在 `weapp-vite` 中得到完整支持。本页帮你快速搞清楚两件事：

* **普通分包 vs 独立分包** 有什么区别（哪些能互相引用、哪些不能）
* **Weapp-vite 会怎么分发产物**（共享代码/依赖/样式会落到哪里）

如果你需要原理级配置（`weapp.subPackages`、`weapp.chunks` 等），请继续阅读 [配置文档 · 分包配置](/config/subpackages.md)、[配置文档 · 共享 Chunk 配置](/config/chunks.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()`，否则行为不可预期。
* 独立分包中暂时不支持使用插件。

### 只构建主包和指定分包

如果你的项目有很多分包，但当前只需要开发订单、会员等少数业务域，可以使用 scoped build：

```bash
wv dev --scope main,packages/order
wv build --scope packages/order
```

`--scope` 不是简单地在构建结束后删除目录，而是在入口阶段裁剪本次构建的 app 注册图：

* `main` 表示主包。
* `packages/order` 匹配 `app.json.subPackages[].root`。
* `wv build --scope packages/order` 默认仍包含主包。
* 最终产物 `app.json.subPackages` 只包含参与 scope 的分包。
* 未参与 scope 的分包页面不会被注册到本次产物。
* 开启 `autoRoutes` 时，`weapp-vite/auto-routes` 也只导出参与 scope 的主包页面和分包页面。

也可以把常用 scope 固化到配置里：

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

export default defineConfig({
  weapp: {
    buildScope: {
      includeMainPackage: true,
      include: ['packages/order'],
    },
  },
})
```

> \[!NOTE]
> scoped build 更适合开发和局部验证。发布前仍建议跑一次不带 scope 的完整构建，确认所有分包注册、依赖落位和包体分析都覆盖完整小程序。

### 单独开发某个分包（把它当成独立分包）

当你想“只专注开发某个分包”（例如一个业务域由独立小组交付、或希望尽量隔离主包依赖）时，推荐把该分包按 **独立分包** 的方式组织与编译：运行时隔离、构建时独立上下文、依赖/样式/组件策略也能只对这个分包生效。

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` 或 `weapp-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`，再用 `wv dev -c vite.config.order.ts` 运行；生产构建仍用默认的 `vite.config.ts` 或 `weapp-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-vite.config.ts` 中的 `weapp.subPackages` 保持一致。
2. 利用 `weapp.debug.watchFiles` 查看产物位置，确认独立分包是否生成独立的 `miniprogram_npm`。
3. 如果分包引用到了主包路径，构建会报错提示，请及时调整引用方式或拆分公共模块。

### 分析产物布局

快速核对“源码最终落在主包 / 分包 / 共享 chunk”的最短路径：

```json
{
  "scripts": {
    "analyze": "wv analyze"
  }
}
```

然后执行：

```bash
pnpm run analyze
```

默认会输出人类可读摘要，并在可用时打开分析仪表盘。需要对接 CI 或自定义检查时，用 JSON、Markdown 或预算检查模式：

```bash
pnpm run analyze -- --json --output report/analyze.json
pnpm run analyze -- --markdown --output report/analyze.md
pnpm run analyze -- --budget-check
```

输出文件会包含主包、分包、共享 chunk、源码映射和组件依赖建议，便于做体积预警和规则校验。若配置了 `weapp.analyze.budgets`，`--budget-check` 会在超限时返回非 0 退出码；若保持默认历史快照，Markdown / PR 报告会对比上一份快照并输出增量归因。

更多预算和历史快照配置见 [Analyze 报告配置](/config/analyze.md)。

## 常见问题

* **本地运行时报路径错误？** 检查页面是否引用了其他分包的资源，或在 `weapp.chunks` 中启用了与你项目不符的策略。
* **产物体积过大？** 使用 `weapp.npm.mainPackage.dependencies` 与 `weapp.npm.subPackages.<root>.dependencies` 精确声明主包/分包 npm 依赖落位。
* **想在分包中调试 Worker？** 记得同时在 `weapp.worker` 中声明入口，并确保 Worker 文件位于对应分包目录。

---

---
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: /guide/app-prelude-web-runtime.md
description: App Prelude 与 Web Runtime 全局对象注入的功能入口，帮助你区分前置脚本和 Web 风格全局对象注入。
---

# App Prelude 与 Web Runtime 注入

`weapp-vite` 提供两类容易混淆、但经常一起使用的运行时增强：

* [App Prelude](/guide/app-prelude)：在小程序 `app`、页面、组件等入口执行前插入一段前置脚本。
* [Web Runtime 全局对象注入](/guide/web-runtime-globals)：把 `fetch`、`Headers`、`XMLHttpRequest`、`WebSocket` 等 Web 风格全局对象安装到小程序运行环境。

它们解决的是两个不同问题：

| 功能                     | 解决的问题                                         | 配置入口                                                     |
| ------------------------ | -------------------------------------------------- | ------------------------------------------------------------ |
| App Prelude              | 代码执行时机，适合在业务入口前运行自包含初始化脚本 | [`weapp.appPrelude`](/config/app-prelude)                    |
| Web Runtime 全局对象注入 | 第三方依赖对 Web 全局对象的运行环境假设            | [`weapp.appPrelude.webRuntime`](/config/web-runtime-globals) |

如果你只是想做浏览器预览，请看 [Web 运行时配置](/config/web)。这里讨论的是“小程序产物中如何提前安装运行时能力”。

## 继续阅读

* [App Prelude](/guide/app-prelude)
* [Web Runtime 全局对象注入](/guide/web-runtime-globals)
* [App Prelude 配置](/config/app-prelude)
* [Web Runtime 全局对象注入配置](/config/web-runtime-globals)

---

---
url: /guide/app-prelude.md
description: 介绍 weapp-vite 的 app.prelude 前置脚本，以及它在小程序入口执行前统一初始化代码的使用方式。
---

# App Prelude

`app.prelude` 用来在小程序 `app`、页面、组件等入口执行前插入一段前置脚本。它关注的是“代码执行时机”：先把基础运行环境或自定义全局状态准备好，再让业务入口继续执行。

\[\[toc]]

## 什么时候需要它

常见场景包括：

* 你要在业务入口前统一初始化一段自包含脚本。
* 你需要在主包、普通分包和独立分包中保持一致的前置注入行为。
* 你希望把运行时补丁、监控启动标记、基础全局变量放到业务模块初始化之前。

如果你的问题是让 `axios`、`graphql-request`、`socket.io-client` 等依赖在小程序里识别 `fetch`、`XMLHttpRequest`、`WebSocket`，请看 [Web Runtime 全局对象注入](/guide/web-runtime-globals)。

## 它做什么

在源码根目录放置 `app.prelude.ts` 或 `app.prelude.js` 后，`weapp-vite` 会把它包装成一段只执行一次的前置脚本，并按配置注入到产物中。

```ts
// src/app.prelude.ts
globalThis.__appBootMeta__ = {
  env: 'dev',
  startedAt: Date.now(),
}
```

默认配置下，`weapp-vite` 会采用 `require` 模式：

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

export default defineConfig({
  weapp: {
    appPrelude: {
      enabled: true,
      mode: 'require',
    },
  },
})
```

`require` 模式会按主包、普通分包和独立分包作用域生成 `app.prelude.js`，再在对应 JS chunk 顶部插入静态 `require(...)`。这样既能保持较早执行时机，又能减少重复内联代码。

> \[!NOTE]
> `app.prelude` 当前必须是自包含脚本，不能包含 `import` 或 `export`。

## 推荐做法

新项目优先使用：

```ts
export default defineConfig({
  weapp: {
    appPrelude: {
      mode: 'require',
    },
  },
})
```

需要 Web 风格全局对象时，再在同一个 `appPrelude` 配置下启用 `webRuntime`。这样前置脚本和 Web Runtime 注入会共享清晰的执行时机。

## 验证方式

构建后可以检查产物中是否出现这些内容：

* `app.prelude.js`
* 入口 JS 顶部的 `require("./app.prelude.js")` 或等价相对路径

```bash
pnpm build
```

然后查看 `dist` 下的 `app.js`、页面 JS 和分包目录。

## 继续阅读

* [App Prelude 配置](/config/app-prelude)
* [Web Runtime 全局对象注入](/guide/web-runtime-globals)
* [调试与排错](/handbook/debugging)

---

---
url: /guide/web-runtime-globals.md
description: 介绍 weapp-vite 如何在小程序产物中注入 fetch、XMLHttpRequest、WebSocket 等 Web 风格全局对象。
---

# Web Runtime 全局对象注入

`weapp.appPrelude.webRuntime` 会在前置时机把 Web Runtime 提供的兼容对象安装到小程序运行环境，并在 chunk 作用域内保留局部绑定兜底。

它关注的是“第三方依赖运行环境假设”：有些依赖会在模块初始化阶段直接读取 `fetch`、`XMLHttpRequest`、`URL`、`AbortController` 这类自由变量，小程序宿主默认不一定提供这些对象。

\[\[toc]]

## 什么时候需要它

常见场景包括：

* 你在小程序里使用 `axios`、`graphql-request`、`socket.io-client` 等更偏 Web 环境的依赖。
* 第三方依赖在模块初始化阶段直接读取 `fetch`、`XMLHttpRequest`、`URL`、`AbortController` 这类自由变量。
* 你需要在主包、普通分包和独立分包中保持一致的 Web Runtime 注入行为。

如果你只是想在业务入口前运行一段自包含初始化脚本，请看 [App Prelude](/guide/app-prelude)。

## 注入哪些对象

小程序宿主不等同于浏览器。很多 Web 依赖会默认全局存在这些对象：

* `fetch`
* `Headers`
* `Request`
* `Response`
* `XMLHttpRequest`
* `WebSocket`
* `AbortController`
* `URL`
* `URLSearchParams`

启用后，构建器会在前置时机安装 Web Runtime 提供的兼容对象，并在 chunk 作用域内保留局部绑定兜底。这个兜底很重要，因为部分第三方库会在模块初始化阶段直接执行 `typeof XMLHttpRequest`、`new URL()` 或缓存 `fetch` 引用。

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

export default defineConfig({
  weapp: {
    appPrelude: {
      mode: 'require',
      webRuntime: true,
    },
  },
})
```

如果你只想覆盖请求相关对象，可以显式配置 `targets`：

```ts
export default defineConfig({
  weapp: {
    appPrelude: {
      mode: 'require',
      webRuntime: {
        enabled: true,
        targets: [
          'fetch',
          'Headers',
          'Request',
          'Response',
          'AbortController',
          'AbortSignal',
          'XMLHttpRequest',
        ],
        dependencies: [/^axios$/, /^graphql-request$/],
      },
    },
  },
})
```

## 和浏览器 Web runtime 的关系

`weapp.web` 和 `weapp.appPrelude.webRuntime` 名字相近，但作用不同。

| 配置                          | 作用位置             | 主要用途                            |
| ----------------------------- | -------------------- | ----------------------------------- |
| `weapp.web`                   | 浏览器侧附加运行链路 | 页面预览、兼容验证、截图联调        |
| `weapp.appPrelude.webRuntime` | 小程序构建产物       | 在小程序运行时安装 Web 风格全局对象 |

如果你要在浏览器中预览小程序页面，配置 `weapp.web`。
如果你要让小程序产物兼容 Web 风格请求库，配置 `weapp.appPrelude.webRuntime`。

## 推荐做法

新项目优先使用：

```ts
export default defineConfig({
  weapp: {
    appPrelude: {
      mode: 'require',
      webRuntime: {
        enabled: true,
      },
    },
  },
})
```

建议把 Web Runtime 全局对象注入统一放在 `weapp.appPrelude.webRuntime` 下，这样配置和执行时机都更清晰。

## 验证方式

构建后可以检查产物中是否出现这些内容：

* `app.prelude.js`
* `weapp-vendors/request-globals-web-apis-shared.js`
* 入口 JS 顶部的 `require("./app.prelude.js")` 或等价相对路径

```bash
pnpm build
```

然后查看 `dist` 下的 `app.js`、页面 JS 和分包目录。

## 继续阅读

* [Web Runtime 全局对象注入配置](/config/web-runtime-globals)
* [App Prelude](/guide/app-prelude)
* [Web 运行时配置](/config/web)

---

---
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',
    },
  },
})
```

## 发布到 npm（宿主自行安装 `wevu`）

如果你的组件库会发布到 npm，并要求宿主项目自行安装 `wevu`，推荐把 `wevu` 作为 `peerDependencies`，同时在库构建里显式 external 掉 `wevu` 与它的子路径。

```json
{
  "peerDependencies": {
    "wevu": "^6.10.2"
  },
  "devDependencies": {
    "wevu": "^6.10.2"
  }
}
```

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

export default defineConfig({
  weapp: {
    lib: {
      entry: [
        'components/button/index.vue',
      ],
    },
  },
  build: {
    rolldownOptions: {
      external: [
        /^wevu(?:\/.*)?$/,
      ],
    },
  },
})
```

这样可以避免把 `wevu`、`wevu/router`、`wevu/api` 等运行时子路径直接打进组件库产物，同时保留本地开发与类型检查所需的依赖。

### 核心字段说明

* `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`）

这样不会互相影响，也更容易维护。

### 发布到 npm 时，为什么不只写 `external: ['wevu']`？

因为组件库内部可能还会引用 `wevu/router`、`wevu/api`、`wevu/fetch` 等子路径。只 external 根包时，这些子路径仍可能被打进最终产物。推荐直接使用：

```ts
/^wevu(?:\/.*)?$/
```

---

---
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/plugin.md
description: >-
  Weapp-vite 可以在同一个项目中同时维护主应用与插件，只要开启 pluginRoot
  就能复用现有的热更新、构建、调试能力。本页将介绍适用场景、目录约定和常见问题，帮助你在几分钟内完成插件开发环境的搭建。
---

# 微信小程序插件开发

`weapp-vite` 可以在同一个项目中同时维护主应用与插件，只要开启 `pluginRoot` 就能复用现有的热更新、构建、调试能力。本页将介绍适用场景、目录约定和常见问题，帮助你在几分钟内完成插件开发环境的搭建。

::: tip TL;DR

1. 在 `vite.config.ts` 或 `weapp-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": "wv dev",
      "dev:open": "wv dev -o",
      "build": "wv build",
      "open": "wv open"
    }
  }
  ```

运行 `pnpm --filter plugin-demo dev` 即可复现插件开发体验。

## 常见问题

### 插件 WXSS 没有生成？

* 检查是否升级到最新版本，并确认 `pluginRoot` 指向正确；
* 仅当插件目录存在对应的 `.wxss` 文件或从脚本中引用样式时，才会生成；
* 若文件名出现 `../plugin` 等路径，请升级至包含本修复的版本。

### 附加功能是否生效？

插件编译共享绝大部分能力：

* 自动构建 npm、WXML/WXSS 增强、auto-import 等功能均可在插件内使用；
* 如果某些能力需要额外配置（如自动导入组件），请在 `vite.config.ts`、`weapp-vite.config.ts` 或插件目录下的模块中参照主应用的写法。

如仍有疑问，可到 [社区交流群](/community/group) 反馈或查看示例仓库的实现，或在 Issue 板块留言寻求帮助。

---

---
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: /guide/multi-platform.md
description: Weapp-vite 提供实验性的多端适配能力：在开发/构建命令后追加 --platform （或短写 -p ），即可输出目标平台所需的文件后缀与目录结构。
---

# 面向多平台构建 experimental {#multi-platform}

`weapp-vite` 内置了多端适配能力：在开发/构建命令后追加 `--platform <id>`（或短写 `-p <id>`），即可输出目标平台所需的文件后缀与目录结构。

下面示例假设你在 `package.json` 脚本里使用的是 `wv dev` / `wv build`：

> \[!WARNING]
> 多平台输出当前仍处于实验阶段（experimental）。执行命令前请先安装对应平台的 IDE；如果你需要用命令行唤起 IDE，请在 IDE 里开启“服务端口”，并务必在目标平台开发者工具里验证产物行为。

## 目标声明 {#targets}

多平台项目建议先启用多平台模式，再通过命令参数选择单个平台构建：

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

export default defineConfig({
  weapp: {
    multiPlatform: true,
    web: {
      enable: true,
      outDir: 'dist/web',
    },
  },
})
```

`multiPlatform: true` 不会一次构建所有平台。`wv build -p weapp`、`wv build -p alipay`、`wv build -p web` 都是独立的单目标构建。`multiPlatform.targets` 仍可作为小程序平台 allowlist 使用，但普通项目不需要显式列出所有平台。

## 支付宝小程序 {#platform-alipay}

```sh
pnpm dev -- --platform alipay
pnpm build -- --platform alipay
pnpm open -- --platform alipay
# 也可以直接调用 CLI，省去额外的 --
pnpm exec wv dev --platform alipay
pnpm exec wv build --platform alipay
pnpm exec wv 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 wv dev --platform tt
pnpm exec wv build --platform tt
```

* 支持字节全家桶（抖音 / 今日头条 / 番茄小说等）所需的 `ttml` / `ttss` 扩展名。
* 推荐使用字节小程序开发者工具导入构建产物。

## 百度智能小程序 {#platform-swan}

```sh
pnpm dev -- --platform swan
pnpm build -- --platform swan
pnpm exec wv dev --platform swan
pnpm exec wv build --platform swan
```

* 输出 `swan` / `css` / `sjs` 等百度专用格式。
* 在百度智能小程序开发者工具中选择 `dist/` 目录。

## 京东小程序 {#platform-jd}

```sh
pnpm dev -- --platform jd
pnpm build -- --platform jd
pnpm exec wv dev --platform jd
pnpm exec wv build --platform jd
```

* 自动转换为 `jxml` / `jxss` 等京东特有的扩展名。
* 构建完成后可直接导入京东小程序 IDE。

## 小红书小程序 {#platform-xhs}

```sh
pnpm dev -- --platform xhs
pnpm build -- --platform xhs
pnpm exec wv dev --platform xhs
pnpm exec wv build --platform xhs
```

* 生成 `xhsml` / `css` 等小红书小程序所需格式。
* 结合小红书开发者中心提供的工具进行预览 / 上传。

> \[!TIP]
> 需要同时输出 Web 版本时，可以在另一个终端运行 `pnpm dev -- --platform web` 或 `pnpm exec wv dev --platform web`。
> 也可以在 `package.json` 里写专用脚本（例如 `"dev:alipay": "wv dev --platform alipay"`），之后直接运行 `pnpm dev:alipay`，避免每次手动输入 `-- --platform ...`。

---

---
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: /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 侧静态分析时，可执行 `wv analyze --platform h5 --json`。
4. 若业务依赖 `⛔` 能力，建议在业务侧提供平台分支与降级策略。

---

---
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: /config.md
description: weapp-vite 基于 Vite 配置模型扩展 weapp 字段，统一管理小程序构建、自动路由、自动导入、MCP、Web 运行时与库模式等能力。
---

# 配置概览 {#config-overview}

`weapp-vite` 采用 **Vite 顶层配置 + `weapp` 小程序专属配置** 的组合模型：

* 顶层字段仍然是标准 Vite 配置，例如 `build`、`resolve`、`css`、`server`
* 小程序专属字段放在 `weapp` 下，例如 `srcRoot`、`autoRoutes`、`buildScope`、`subPackages`、`mcp`

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

export default defineConfig({
  resolve: {
    alias: {
      '@': new URL('./src', import.meta.url).pathname,
    },
  },
  build: {
    sourcemap: true,
  },
  weapp: {
    srcRoot: 'src',
    autoRoutes: true,
  },
})
```

> \[!NOTE]
> 除了 `vite.config.*`，你也可以额外提供 `weapp-vite.config.*`。`weapp-vite` 会读取其中的 `weapp` 配置，再与 `vite.config.*` 合并，适合把“小程序专属配置”和“通用 Vite 配置”拆开维护。

> \[!TIP]
> 配置文件以 ESM 方式执行。需要绝对路径时，优先使用 `import.meta.dirname`，或基于 `import.meta.url` 自行转换。

\[\[toc]]

## 先分清两类配置

### 看本目录的场景

当你在配置这些能力时，优先看 `/config/*`：

* 小程序源码入口、插件入口、静态资源复制
* 自动路由、自动导入组件、分包、共享 chunk
* Vue SFC / Wevu 编译期增强
* 托管 TypeScript 支持文件、analyze 报告
* MCP、日志转发、运行时注入
* Web 运行时、库模式、worker 构建

### 看 Vite 官方配置的场景

当你在配置这些标准 Vite 能力时，优先看 Vite 中文官方配置文档：

* `root`
* `resolve.alias`
* `define`
* `css`
* `server`
* `plugins`
* `build`
* `optimizeDeps`
* `worker`

官方入口：

* [Vite 中文官方配置文档](https://cn.vite.dev/config/)

> \[!TIP]
> `weapp-vite` 不会重新发明一套 `build` / `server` / `resolve` API。文档里提到这些字段时，通常只解释“它在小程序链路里要注意什么”，更完整的字段定义请以 Vite 官方文档为准。

## `defineConfig` 推荐写法

推荐始终从 `weapp-vite/config` 导入 `defineConfig`，而不是直接从 `vite` 导入。这样 `weapp` 字段能拿到完整的类型提示、JSDoc 和跳转能力。

默认情况下，项目可以只保留 `vite.config.*`，也可以只保留 `weapp-vite.config.*`；如果两者同时存在，`weapp-vite` 会读取并合并其中的 `weapp` 配置。

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

export default defineConfig(env => ({
  weapp: {
    srcRoot: env.command === 'build' ? 'src' : 'src',
  },
}))
```

支持的主要形态包括：

* 对象配置
* `Promise` 对象配置
* 同步函数配置
* 异步函数配置
* 带 `env` 的同步/异步函数配置

深入说明请看：

* [defineConfig 重载与类型推导说明](https://github.com/weapp-vite/weapp-vite/blob/main/packages/weapp-vite/docs/define-config-overloads.md)

## 推荐阅读顺序

1. 先看 [基础目录与资源收集](./paths.md)、[构建输出与兼容](./build-and-output.md)、[TypeScript 支持文件](./typescript.md)，把目录、输出、类型支持先稳定下来。
2. 再看 [共享配置](./shared.md)、[自动导入组件配置](./auto-import-components.md)、[分包配置](./subpackages.md)、[共享 Chunk 配置](./chunks.md)、[App Prelude 配置](./app-prelude.md)、[Web Runtime 全局对象注入配置](./web-runtime-globals.md)，接入增强能力。
3. 最后再看 [Vue SFC 配置](./vue.md)、[Wevu 编译期配置](./wevu.md)、[Web 运行时配置](./web.md)、[库模式配置](./lib.md) 这些偏进阶链路。

## 按场景找配置

| 场景 | 建议先看 |
| --- | --- |
| 刚接入项目，先让目录、输出、TS 提示稳定 | [基础目录与资源收集](./paths.md)、[构建输出与兼容](./build-and-output.md)、[TypeScript 支持文件](./typescript.md) |
| 想减少手写 `app.json.pages` / `usingComponents` | [共享配置](./shared.md)、[自动导入组件配置](./auto-import-components.md) |
| 想按目录批量套 layout | [Route Rules 与 Layout](./route-rules.md) |
| 项目有分包、独立分包、共享样式或分包独立 npm | [分包配置](./subpackages.md)、[npm 配置](./npm.md)、[共享 Chunk 配置](./chunks.md) |
| 使用 Vue SFC / Wevu，需要调模板编译、setData 策略或 HMR | [Vue SFC 配置](./vue.md)、[Wevu 编译期配置](./wevu.md)、[开发态 HMR 配置](./hmr.md) |
| 想把分包体积、重复模块和 HMR profile 纳入本地或 CI 检查 | [Analyze 报告配置](./analyze.md)、[分包配置](./subpackages.md)、[开发态 HMR 配置](./hmr.md) |
| 想让小程序产物兼容 `fetch` / `XMLHttpRequest` / `WebSocket` 等 Web 风格全局对象 | [Web Runtime 全局对象注入配置](./web-runtime-globals.md) |
| 想做浏览器预览、AI 协作、截图、日志桥接 | [共享配置](./shared.md)、[Web 运行时配置](./web.md) |
| 想做小程序组件库或业务模块库 | [库模式配置](./lib.md) |

## 配置索引

| 主题 | 内容概览 |
| --- | --- |
| [基础目录与资源收集](./paths.md) | `srcRoot` / `pluginRoot` / `copy` / `isAdditionalWxml` |
| [构建输出与兼容](./build-and-output.md) | `platform` / `multiPlatform` / `buildScope` / `jsFormat` / `cleanOutputsInDev` / `packageSizeWarningBytes` / 顶层 `build.*` |
| [TypeScript 支持文件](./typescript.md) | `.weapp-vite/tsconfig.*`、托管类型输出、`weapp.typescript` |
| [Analyze 报告配置](./analyze.md) | `weapp.analyze.budgets`、历史快照、Markdown / PR 报告、HMR profile 分析 |
| [App Prelude 配置](./app-prelude.md) | `appPrelude` 前置脚本开关、注入模式与产物行为 |
| [Web Runtime 全局对象注入配置](./web-runtime-globals.md) | `appPrelude.webRuntime` / Web Runtime 全局对象注入 |
| [共享配置](./shared.md) | `autoRoutes` / `debug` / `logger` / `forwardConsole` / `injectWeapi` / `mcp` |
| [Route Rules 与 Layout](./route-rules.md) | `weapp.routeRules`、layout 默认值、`layouts/` 约定 |
| [JSON 配置](./json.md) | `jsonAlias` / `json.defaults` / `json.mergeStrategy` |
| [JS 配置](./js.md) | `tsconfigPaths` / `ast` 与顶层 `resolve.alias` 的边界 |
| [Vue SFC 配置](./vue.md) | `weapp.vue.template`、模板编译开关、自动导入保留字段 |
| [Wevu 编译期配置](./wevu.md) | `weapp.wevu.preset` / `defaults` / `autoSetDataPick` |
| [开发态 HMR 配置](./hmr.md) | `weapp.hmr.runtime` / `sharedChunks` / `touchAppWxss` / `logLevel` / `profileJson` |
| [分包配置](./subpackages.md) | `weapp.subPackages`、共享样式、分包级 `inlineConfig` |
| [Worker 配置](./worker.md) | `weapp.worker.entry` |
| [库模式配置](./lib.md) | `weapp.lib` 入口、路径、组件 JSON 与 DTS |
| [生成脚手架配置](./generate.md) | `weapp.generate` 目录、后缀、文件名、模板 |
| [npm 配置](./npm.md) | `weapp.npm` 依赖落位、缓存、支付宝 npm 模式、构建覆盖 |
| [WXML 配置](./wxml.md) | `weapp.wxml` 扫描与模板处理入口 |
| [WXS 配置](./wxs.md) | `weapp.wxs` 与 Vue class/style 运行时的关系 |
| [自动导入组件配置](./auto-import-components.md) | `weapp.autoImportComponents` 字段与产物输出 |
| [共享 Chunk 配置](./chunks.md) | `weapp.chunks` 共享策略、输出形态与优化日志 |
| [Web 运行时配置](./web.md) | `weapp.web` 浏览器预览与调试 |

## 常见边界问题

### `weapp` 和顶层 `build` / `resolve` 会冲突吗

通常不会。

* `weapp` 负责小程序特有能力
* 顶层 `build` / `resolve` / `css` / `server` 继续按 Vite 规则工作

如果一个功能同时涉及两边：

* 先用 `weapp` 定义小程序语义
* 再用顶层 Vite 配置调整底层构建行为

例如：

* `weapp.lib` 决定“进入库模式”
* 顶层 `build.rolldownOptions` 决定 external、chunk、输出细节

### 配置改了但编辑器没提示

优先排查这几项：

1. 是否从 `weapp-vite/config` 导入 `defineConfig`
2. 是否已经执行过 `wv prepare`
3. 根 `tsconfig.json` 是否包含 `.weapp-vite` 生成的引用或类型输出
4. 是否误把小程序字段写到了 Vite 顶层，而不是 `weapp` 下

### 不知道一个字段到底归谁管

可以用这个经验法则：

* 只和小程序构建/运行语义有关，通常在 `weapp.*`
* 只和 Vite/Rolldown 服务、解析、打包行为有关，通常在 Vite 顶层

***

如果你不确定从哪一页开始，先看 **基础目录与资源收集**、**构建输出与兼容**、**共享配置**。这三页基本覆盖了项目刚接入或升级时最容易踩坑的部分。

---

---
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) 也遵循同样的目录要求。

## `.weapp-vite` 支持文件缺失或过期？

* **症状**：
  * Volar / TypeScript 提示异常
  * 自动路由类型丢失
  * 终端提示支持文件缺失或已过期
* **优先操作**：

```bash
wv prepare
```

* **补充说明**：
  * `.weapp-vite/` 是托管支持文件目录，不建议长期手写并偏离工具输出。
  * 如果你刚升级 `weapp-vite`，优先先跑一次 `prepare` 再继续排查。

## AI 截图失败或截图对比失败？

优先检查：

1. 微信开发者工具是否已登录；
2. 是否开启了「设置 > 安全设置 > 服务端口」；
3. `--project` 是否真的指向小程序构建目录；
4. `--page` 是否为真实路由；
5. baseline 图片尺寸是否与当前截图一致。

推荐命令：

```bash
wv screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json
wv compare --project ./dist/build/mp-weixin --page pages/index/index --baseline .screenshots/baseline/index.png --diff-output .tmp/index.diff.png --max-diff-pixels 100 --json
```

## 终端里看不到小程序日志？

优先使用：

```bash
wv ide logs --open
```

如果项目启用了 `weapp.forwardConsole.enabled = 'auto'`，AI 终端场景下 `wv dev --open` 也可能自动附加日志桥。

## 修改源码后，下游验证结果还是旧的？

如果你改的是 `packages/weapp-vite/src/**`、`packages-runtime/**/src/**` 之类的源码，但验证走的是 app/template/e2e 产物，优先怀疑 `dist` 产物陈旧。

先重建相关包，再做下游验证：

```bash
pnpm --filter wv build
```

***

若以上方案未解决问题，请收集：

* 复现步骤与最小示例仓库；
* `pnpm build` 输出日志、微信开发者工具控制台日志；
* `vite.config.ts`、`app.json` 关键配置。

然后在 [GitHub Issues](https://github.com/weapp-vite/weapp-vite/issues) 或社区群提问，我们会尽快协助排查。

---

---
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. 建议先执行 `corepack enable`。
2. 在仓库根目录使用 pnpm 11 安装依赖：
   ```sh
   corepack pnpm@11 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 附加调试，会同样命中源码断点。

### 补充：直接把 DevTools 日志桥接回终端

如果你当前排查的是运行时问题，而不是编译期断点，通常不需要先打开 DevTools 控制台。

可以直接在仓库里执行：

```sh
pnpm dev --open
```

如果当前终端是 AI 终端，并且项目保持默认 `weapp.forwardConsole.enabled = 'auto'`，那么打开微信开发者工具后会自动尝试把小程序 `console` 日志桥接回当前终端。

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

```sh
wv ide logs --open
```

这个方式适合：

1. 定位页面初始化报错。
2. 观察某次交互触发的 `warn` / `error`。
3. 让 AI 直接基于终端里的运行时日志继续分析问题。

相关说明见：

* [CLI 命令参考：ide logs](/guide/cli)
* [共享配置：weapp.forwardConsole](/config/shared#weapp-forwardconsole)

## 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: /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: /deep/init.md
description: >-
  Weapp-vite init 是在现有原生项目上接入 Weapp-vite
  的最快方式。它会检查当前目录结构、补齐必需的配置文件，然后提示你后续可以手动调整的地方。本节逐步拆解各项改动，方便团队在需要时自行定制或纯手动迁移。
---

# `wv init` 做了什么？

`wv 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": "wv dev",
    "build": "wv build",
    "open": "wv 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 等需要额外配置的工具，脚手架会保留注释提示下一步应该如何开启。

***

完成 `wv 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: /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: /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: /community/showcase.md
description: 优秀案例展示，聚焦 community / showcase 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 优秀案例展示

> 当前共收录 4 个案例。案例数据与素材由 `scripts/sync-community-showcase.ts` 根据 GitHub issue 自动同步，展示交互由 `CommunityShowcase.vue` 统一渲染。

## xiaomusic

## MBTI性格测试工具

## 草莓拼豆

## 早睡搭子小程序：按时睡教

---

---
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: /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: /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: /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: /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: /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
wv mcp
```

如果你不在仓库目录下执行，再补 `--workspace-root <repo-root>`。

最后是 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: /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: /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: /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`），用于提升开发效率。

最基础的用法只需要 `wv 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: /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 wv 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: /config/paths.md
description: 说明 weapp-vite 如何确定源码根目录、插件目录和资源复制范围，以及这些配置与 Vite root/publicDir 的边界。
---

# 基础目录与资源收集 {#paths-config}

这一页聚焦几类最基础、也最容易把整个工程带偏的配置：

1. 小程序源码从哪里开始扫描
2. 插件源码在哪里
3. 哪些非代码资源会被复制进产物
4. 哪些字段目前仍是预留位

如果这些路径先没对齐，后面的自动路由、自动导入、分包和 TS 支持都会出现连锁误判。

\[\[toc]]

## `weapp.srcRoot` {#weapp-srcroot}

* **类型**：`string`
* **默认值**：项目根目录

表示小程序应用入口目录，也就是 `app.json` 所在目录。

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

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

它会影响：

* `app.json`、页面、组件、分包的扫描起点
* 自动路由默认扫描范围
* 静态资源复制范围
* `.weapp-vite` 托管类型里的一部分推导结果

常见场景：

* 老项目把源码放在 `miniprogram/`
* Vue SFC / Wevu 项目把源码放在 `src/`

## `weapp.pluginRoot` {#weapp-pluginroot}

* **类型**：`string`
* **默认值**：`undefined`

表示插件入口目录，也就是 `plugin.json` 所在目录。

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

适用场景：

* 同仓库同时维护主应用和小程序插件
* 需要让插件也走同一套 alias、TypeScript、npm 构建链路

> \[!NOTE]
> `pluginRoot` 只负责声明插件源码入口。插件最终输出目录仍会结合平台 project config 和构建上下文推导。

## `weapp.copy` {#weapp-copy}

* **类型**：`{ include?: string[]; exclude?: string[]; filter?: (filePath: string, index: number, array: string[]) => boolean }`
* **默认值**：`undefined`

用于把字体、证书、原始数据、模型、额外静态资源等复制到产物目录。

```ts
export default defineConfig({
  weapp: {
    copy: {
      include: ['**/*.ttf', '**/*.wasm', 'assets/raw/**'],
      exclude: ['**/__tests__/**'],
      filter(filePath) {
        return !filePath.endsWith('.map')
      },
    },
  },
})
```

说明：

* `include` / `exclude` 基于 `srcRoot` 或 `pluginRoot` 匹配
* `filter` 会在 glob 命中后再进行一次过滤
* 默认情况下，常见图片、音视频、字体、`wasm` 等资源已经会被收集

### 与 `public/` 的关系

如果资源天然适合走 Vite 的公共资源目录，也可以使用顶层 `publicDir`。

边界可以这样理解：

* 需要按小程序源码树一起管理的资源，用 `weapp.copy`
* 需要按 Vite 公共目录原样复制的资源，用 `publicDir`

更多原生字段说明：

* [Vite 中文官方配置文档 · shared options](https://cn.vite.dev/config/shared-options)

## `weapp.isAdditionalWxml` {#weapp-isadditionalwxml}

* **类型**：`(wxmlFilePath: string) => boolean`
* **默认值**：`() => false`

这是预留字段，当前版本尚未正式接入扫描和产物流程。

如果你的项目有“运行时动态拼接额外 WXML”的历史逻辑，当前更稳的做法仍然是：

* 改成显式引用
* 或在你自己的构建前后置步骤里补充产物

不要把核心流程建立在这个字段已经生效的假设上。

## 顶层 `root` 和 `weapp.srcRoot` 的区别

这两个字段经常被混淆：

* 顶层 `root`：Vite 项目根目录，影响 Vite 自身的配置解析、`index.html`、插件上下文等
* `weapp.srcRoot`：小程序源码根目录，影响 `app.json`、页面、组件、分包扫描

通常业务项目里：

* 不需要改 Vite `root`
* 只需要改 `weapp.srcRoot`

如果你确实在做多工程或自定义工作区结构，再去同时调整两者。

更多原生字段说明：

* [Vite 中文官方配置文档 · shared options](https://cn.vite.dev/config/shared-options)

***

接下来建议继续看 [构建输出与兼容](./build-and-output.md)。路径确定后，下一步通常就是把输出位置、平台和 JS 格式稳定下来。

---

---
url: /config/build-and-output.md
description: 解释 weapp-vite 的平台、输出目录、JS 输出格式与兼容策略，以及这些配置与 Vite build 的边界。
---

# 构建输出与兼容 {#build-and-output}

这一页回答两个问题：

1. `weapp-vite` 最终把小程序产物输出到哪里
2. 这些产物按哪个平台、哪种 JS 格式和怎样的兼容策略输出

它覆盖的是 **小程序语义层** 的配置；如果你在找 `build.minify`、`build.sourcemap`、`build.rollupOptions` 这类 **Vite 原生 build 配置**，请结合阅读：

* [Vite 中文官方配置文档 · build](https://cn.vite.dev/config/build-options)

\[\[toc]]

## 输出目录是怎么决定的

默认情况下，`weapp-vite` 会优先从当前平台对应的 `project.config.*` 中读取：

* `miniprogramRoot`
* `pluginRoot`

如果顶层 Vite `build.outDir` 没有显式指定：

* 小程序主应用默认输出到 `miniprogramRoot`
* 插件输出目录会结合 `pluginRoot` 与构建上下文推导

如果你显式配置了顶层 `build.outDir`，则以你的 Vite 配置为准。

> \[!NOTE]
> 当启用 `weapp.multiPlatform`，且多个平台共用相对 `miniprogramRoot` 时，建议明确检查最终产物目录，避免不同平台互相覆盖。

## `weapp.platform` {#weapp-platform}

* **类型**：`'weapp' | 'alipay' | 'tt' | 'swan' | 'jd' | 'xhs'`
* **默认值**：`'weapp'`

作用：

* 决定当前构建按哪个小程序平台解析扩展名和 project config
* 影响平台分支逻辑、模板兼容策略、部分 JSON / npm 输出行为

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

export default defineConfig({
  weapp: {
    platform: 'alipay',
  },
})
```

适用建议：

* 单平台项目：直接写死即可
* 多平台项目：通常配合 CLI 的 `--platform` 与 `weapp.multiPlatform` 使用

## `weapp.multiPlatform` {#weapp-multiplatform}

* **类型**：`boolean | { enabled?: boolean; projectConfigRoot?: string }`
* **默认值**：`false`

用于同仓库维护多套平台 `project.config.*`。

```ts
export default defineConfig({
  weapp: {
    multiPlatform: {
      enabled: true,
      projectConfigRoot: 'config',
    },
  },
})
```

行为说明：

* `true` 等价于 `{ enabled: true, projectConfigRoot: 'config' }`
* 启用后会按平台读取 `${projectConfigRoot}/${platform}/...` 下的项目配置文件
* 一般要配合命令行 `--platform` 使用，例如 `wv build --platform alipay`

适用场景：

* 同一业务同时维护微信、支付宝、抖音小程序
* 平台间 `appid`、编译选项、输出目录策略不同

## `weapp.cleanOutputsInDev` {#weapp-cleanoutputsindev}

* **类型**：`boolean`
* **默认值**：`true`

控制开发态启动前是否清空输出目录。

```ts
export default defineConfig({
  weapp: {
    cleanOutputsInDev: false,
  },
})
```

说明：

* `dev` 模式默认会先清空输出目录，避免旧产物干扰
* `build` 模式始终清空输出目录，不受此字段影响
* 大项目若频繁冷启动，可按需关闭开发态清理换取速度

## `weapp.buildScope` {#weapp-buildscope}

* **类型**：`string | string[] | { includeMainPackage?: boolean; include?: string[] }`
* **默认值**：不启用，完整构建

用于只构建主包和指定分包。它适合中大型小程序按业务分包日常开发、局部验证或临时分析，不建议直接替代发布前的完整构建。

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

export default defineConfig({
  weapp: {
    buildScope: {
      includeMainPackage: true,
      include: ['packages/order', 'packages/user'],
    },
  },
})
```

等价的 CLI 写法：

```bash
wv dev --scope main,packages/order,packages/user
wv build --scope packages/order
```

语义说明：

* `main` 表示主包。
* `packages/order` 这类值匹配 `app.json.subPackages[].root` / `subpackages[].root`。
* CLI `--scope` 优先级高于配置文件里的 `weapp.buildScope`。
* 字符串写法会按逗号分隔，例如 `'main,packages/order'`。
* 数组写法适合在配置里复用，例如 `['main', 'packages/order']`。
* `includeMainPackage` 默认是 `true`，所以 `wv build --scope packages/order` 会构建主包和 `packages/order` 分包。
* 如果确实要排除主包，可以使用对象写法并设置 `includeMainPackage: false`。

构建效果：

* 产物 `app.json.pages` 只在包含主包时保留。
* 产物 `app.json.subPackages` 只保留参与 scope 的分包。
* `preloadRule` 会同步过滤到参与 scope 的页面和分包。
* 开启 `weapp.autoRoutes` 时，`weapp-vite/auto-routes` 导出的 `pages`、`subPackages`、typed router 也会基于 scope 后的结果生成。
* 开发态 watcher 会收窄到主包 `pages/**` 与参与 scope 的分包 root。

> \[!NOTE]
> `buildScope` 是入口级裁剪，不是构建完成后删除文件。未参与 scope 的分包不会进入本次 app 注册图，因此微信开发者工具读取到的 `app.json` 也只包含本次参与构建的分包。

## `weapp.packageSizeWarningBytes` {#weapp-packagesizewarningbytes}

* **类型**：`number`
* **默认值**：`2097152`

用于主包/分包体积告警阈值，单位是字节。

```ts
export default defineConfig({
  weapp: {
    packageSizeWarningBytes: 1.5 * 1024 * 1024,
  },
})
```

适合：

* 团队想在逼近平台限制前更早收到提醒
* 有明确包体预算，需要设置更保守的阈值

## `weapp.jsFormat` {#weapp-jsformat}

* **类型**：`'cjs' | 'esm'`
* **默认值**：`'cjs'`

决定脚本产物使用 CommonJS 还是 ESM。

```ts
export default defineConfig({
  weapp: {
    jsFormat: 'esm',
  },
})
```

选择建议：

* `cjs`：兼容性最好，默认推荐
* `esm`：适合明确采用 ESM 输出策略的项目，但要结合目标平台验证

> \[!WARNING]
> 若你选择 `esm`，应同时检查目标开发者工具与平台对该输出形式的支持，不要只在 Web 或单机环境里验证。

## 顶层 `build.*` 该怎么配

这些字段仍然按 Vite 标准语义工作：

* `build.outDir`
* `build.target`
* `build.minify`
* `build.sourcemap`
* `build.rolldownOptions`

例如：

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

export default defineConfig({
  build: {
    target: 'es2020',
    minify: false,
    sourcemap: true,
  },
  weapp: {
    jsFormat: 'cjs',
  },
})
```

建议这样理解边界：

* `weapp.platform` / `weapp.jsFormat` / `weapp.multiPlatform` 决定“小程序产物应该长什么样”
* 顶层 `build.*` 决定“Vite / Rolldown 用什么方式构建这些产物”

更多字段说明请直接看：

* [Vite 中文官方配置文档 · build](https://cn.vite.dev/config/build-options)

## 常见组合

### 多平台项目

```ts
export default defineConfig({
  build: {
    sourcemap: true,
  },
  weapp: {
    platform: 'weapp',
    multiPlatform: true,
  },
})
```

适合把“具体平台”交给 CLI 参数，而不是写死在单个配置文件里。

### 保守兼容输出

```ts
export default defineConfig({
  build: {
    target: 'es2020',
  },
  weapp: {
    jsFormat: 'cjs',
  },
})
```

这是绝大多数业务项目更稳的起点。

### 调试优先输出

```ts
export default defineConfig({
  build: {
    minify: false,
    sourcemap: true,
  },
  weapp: {
    cleanOutputsInDev: false,
  },
})
```

适合当前重点在定位运行时和产物问题，而不是压缩包体。

***

如果你接下来要处理源码入口、插件目录、资源复制，请继续看 [基础目录与资源收集](./paths.md)。如果你要处理分包和共享模块，再看 [分包配置](./subpackages.md) 与 [共享 Chunk 配置](./chunks.md)。

---

---
url: /config/typescript.md
description: >-
  weapp-vite 会生成 .weapp-vite 下的托管 tsconfig 与类型文件，用于稳定承接自动路由、自动导入组件、layout
  和编辑器提示。
---

# TypeScript 支持文件 {#typescript-support}

`weapp-vite` 会在项目根目录生成一组 `.weapp-vite/*` 托管文件，用来解决两类问题：

* 给自动路由、自动导入组件、layout 等增强能力提供稳定的类型输出位置
* 让旧项目也能逐步接入更规范的 TS 引用结构，而不是一次性强制重构

\[\[toc]]

## 会生成哪些文件

常见输出包括：

* `.weapp-vite/tsconfig.app.json`
* `.weapp-vite/tsconfig.server.json`
* `.weapp-vite/tsconfig.node.json`
* `.weapp-vite/tsconfig.shared.json`
* `.weapp-vite/typed-router.d.ts`
* `.weapp-vite/typed-components.d.ts`
* `.weapp-vite/components.d.ts`
* `.weapp-vite/wevu-layouts.d.ts`

它们分别服务于：

* 业务源码与页面/组件类型检查
* Node / 配置文件类型检查
* 自动路由类型输出
* 自动导入组件与 Vue 模板补全
* layout 名称和 props 类型增强

## 什么时候生成

这些文件会在以下命令中自动生成或刷新：

* `wv dev`
* `wv build`
* `wv open`
* `wv analyze`
* `wv prepare`

如果你希望在编辑器、CI、AI 工具接入前先预热类型产物，推荐显式执行：

```bash
wv prepare
```

## `weapp.typescript` {#weapp-typescript}

* **类型**：
  ```ts
  {
    shared?: {
      compilerOptions?: CompilerOptions
    }
    app?: {
      compilerOptions?: CompilerOptions
      vueCompilerOptions?: Record<string, any>
      include?: string[]
      exclude?: string[]
      files?: string[]
    }
    node?: {
      compilerOptions?: CompilerOptions
      include?: string[]
      exclude?: string[]
      files?: string[]
    }
    server?: {
      compilerOptions?: CompilerOptions
      include?: string[]
      exclude?: string[]
      files?: string[]
    }
  }
  ```

用于定制托管 `tsconfig` 的各分组内容。

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

export default defineConfig({
  weapp: {
    typescript: {
      shared: {
        compilerOptions: {
          strict: true,
        },
      },
      app: {
        include: ['src/**/*', '.weapp-vite/**/*.d.ts'],
      },
      node: {
        compilerOptions: {
          types: ['node'],
        },
      },
      server: {
        include: ['server/**/*.ts'],
      },
    },
  },
})
```

### 四个分组分别管什么

* `shared`：多端共享、公共基础配置
* `app`：页面、组件、SFC、布局相关源码
* `node`：`vite.config.*`、`weapp-vite.config.*`、脚本、生成器、Node 工具
* `server`：服务端辅助代码或本地 server 代码

### 每个分组都支持什么

`shared` 只支持 `compilerOptions`，用于给其他托管 tsconfig 通过 `extends` 继承公共编译器选项。

`app` / `node` / `server` 支持：

* `compilerOptions`
* `include`
* `exclude`
* `files`

其中 `app` 额外支持：

* `vueCompilerOptions`

## 推荐接入方式

### 新项目

优先采用托管 `references` 结构：

```json
{
  "references": [
    { "path": "./.weapp-vite/tsconfig.app.json" },
    { "path": "./.weapp-vite/tsconfig.server.json" },
    { "path": "./.weapp-vite/tsconfig.node.json" },
    { "path": "./.weapp-vite/tsconfig.shared.json" }
  ],
  "files": []
}
```

根 `tsconfig.json` 是 TypeScript solution config，只负责把编辑器和 `tsc -b` 引到 `.weapp-vite/*` 子项目。业务 `.vue`、页面、组件和自动导入组件的类型检查入口是 `.weapp-vite/tsconfig.app.json`，它会包含：

* `../src/**/*`
* `./**/*.d.ts`
* `types: ["miniprogram-api-typings", "weapp-vite/client"]`
* `vueCompilerOptions.plugins: ["weapp-vite/volar"]`
* 使用 `wevu` 时的 `vueCompilerOptions.lib: "wevu"`

`.weapp-vite/tsconfig.shared.json` 只用于被 `app` / `node` / `server` 通过 `extends` 继承。即使根 solution config 保留对它的 `references`，它也必须保持为显式空 project。由于 `tsc -b` 不接受完全空的 `files: []` project，托管配置会只引用一个空占位声明文件：

```jsonc
{
  "compilerOptions": {
    // ...
  },
  "files": ["./tsconfig.shared.empty.d.ts"]
}
```

这样可以避免 TypeScript 在单独加载 shared project 时按默认 `**/*` 隐式包含全仓库文件，重复解析 `.weapp-vite/*.d.ts`、小程序 typings、`wevu` 等声明，同时仍能通过 solution build，从而改善 Vue Official / Volar 对 `.vue` 文件的归属判断和跳转稳定性。

### 旧项目

建议按这个顺序迁移：

1. 先执行一次 `wv prepare`
2. 确认 `.weapp-vite/*` 已生成
3. 再逐步把根 `tsconfig.json` 收敛到托管 `references`
4. 最后在 `weapp.typescript` 里补团队自己的覆盖项

## 与顶层 `resolve.alias` / `compilerOptions.paths` 的关系

`weapp.typescript` 只负责托管 TS 文件本身的结构和编译器选项。

如果你在处理路径别名：

* TS 层别名：`compilerOptions.paths`
* Vite 解析层：顶层 `resolve.alias` 或 `weapp.tsconfigPaths`

更多 Vite 原生配置说明：

* [Vite 中文官方配置文档 · resolve](https://cn.vite.dev/config/shared-options#resolve-alias)

## 常见问题

### 为什么改了配置后编辑器还没提示

优先检查：

1. 是否已执行 `wv prepare`
2. 根 `tsconfig.json` 是否包含 `.weapp-vite` 产物
3. 是否使用了 `weapp-vite/config` 的 `defineConfig`

### `typed-router.d.ts` / `typed-components.d.ts` 没生成

分别检查：

* 是否启用了 `weapp.autoRoutes`
* 是否启用了 `weapp.autoImportComponents`

### 可以手动改 `.weapp-vite/*.json` 吗

不建议。它们属于托管产物，应通过 `weapp.typescript` 和相关功能配置来改。

***

接下来如果你要处理自动路由、日志桥接、MCP 或运行时注入，请继续看 [共享配置](./shared.md)。

---

---
url: /config/analyze.md
description: 说明 weapp.analyze 的包体预算、历史快照，以及 wv analyze 的 Markdown、PR 摘要和预算检查工作流。
---

# Analyze 报告配置 {#analyze-config}

`weapp.analyze` 用来给 `wv analyze` 补充项目级预算和历史快照配置。它不会改变构建产物，只影响分析报告、预算检查和增量归因。

\[\[toc]]

## `weapp.analyze.budgets` {#weapp-analyze-budgets}

* **类型**：`object`
* **默认值**：总包 `20 MB`，主包 / 普通分包 / 独立分包 `2 MB`，预警比例 `0.85`
* **适用场景**：在本地或 CI 中对小程序产物体积做预算检查。

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

export default defineConfig({
  weapp: {
    analyze: {
      budgets: {
        totalBytes: 20 * 1024 * 1024,
        mainBytes: 2 * 1024 * 1024,
        subPackageBytes: 2 * 1024 * 1024,
        independentBytes: 2 * 1024 * 1024,
        warningRatio: 0.85,
      },
    },
  },
})
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `totalBytes` | 全部小程序产物合计预算 |
| `mainBytes` | 主包预算 |
| `subPackageBytes` | 普通分包预算 |
| `independentBytes` | 独立分包预算 |
| `warningRatio` | 预警比例，达到该比例但未超限时标记为接近预算 |

运行预算检查：

```bash
wv analyze --budget-check
```

当任一预算超限时，命令会设置非 0 退出码，适合放进 CI。

## `weapp.analyze.history` {#weapp-analyze-history}

* **类型**：`boolean | object`
* **默认值**：开启，目录 `.weapp-vite/analyze-history`，保留 20 份快照
* **适用场景**：让 Markdown / PR 报告自动对比上一次分析结果，输出体积增量归因。

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

export default defineConfig({
  weapp: {
    analyze: {
      history: {
        enabled: true,
        dir: '.weapp-vite/analyze-history',
        limit: 20,
      },
    },
  },
})
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `enabled` | 是否写入历史快照 |
| `dir` | 快照目录，相对路径基于项目根目录解析 |
| `limit` | 最大保留快照数量，旧快照会自动清理 |

如果不希望本地写入历史快照，可以关闭：

```ts
export default defineConfig({
  weapp: {
    analyze: {
      history: false,
    },
  },
})
```

## 报告输出工作流 {#report-workflow}

`wv analyze` 支持三类常用输出：

```bash
# JSON，适合脚本消费
wv analyze --json --output reports/analyze.json

# 完整 Markdown 报告
wv analyze --markdown --output reports/analyze.md

# PR 摘要，适合写入 CI 评论
wv analyze --report pr --output reports/analyze-pr.md
```

Markdown 和 PR 报告会结合预算、重复模块、Top 增量和历史快照生成建议动作。第一次运行没有历史快照时，增量列会显示为无变化；从第二次开始会基于上一份快照对比。

## HMR profile 分析 {#hmr-profile}

如果开启了 [开发态 HMR 配置](./hmr.md) 中的 `weapp.hmr.profileJson`，可以直接聚合 JSONL profile：

```bash
wv analyze --hmr-profile
```

也可以显式指定文件：

```bash
wv analyze --hmr-profile .tmp/weapp-vite-hmr-profile.jsonl --json
```

该模式会输出样本数量、阶段平均耗时、最大耗时、事件分布、dirty / pending 原因和最慢样本，适合定位 HMR 变慢的阶段。

## Web 平台边界 {#web-platform}

```bash
wv analyze --platform h5 --json
```

Web 模式当前只做静态配置分析，覆盖 `weapp.web` 是否启用、`root` / `srcDir` / `outDir` 和 `runtime.executionMode`。它不扫描 Web 产物体积，也不提供分包映射和 dashboard。

## 关联阅读

* [CLI：analyze](../guide/cli.md#_3-analyze)
* [分包指南：分析产物布局](../guide/subpackage.md#分析产物布局)
* [开发态 HMR 配置](./hmr.md)

---

---
url: /config/route-rules.md
description: >-
  使用 weapp.routeRules 为页面批量声明默认 layout，并结合 srcRoot/layouts 与 definePageMeta
  实现页面外壳复用。
---

# Route Rules 与 Layout {#route-rules-layout}

`weapp-vite` 当前已经支持页面级 layout。它不是单独某一个开关，而是由以下几部分协同工作：

* `srcRoot/layouts/**`：声明可用的 layout 组件或原生 layout 目录
* `definePageMeta({ layout })`：在页面里显式指定 layout
* `weapp.routeRules`：在配置层为一批页面声明默认 layout
* `setPageLayout()` / `usePageLayout()`：在运行时切换或读取当前页面 layout 状态

\[\[toc]]

## `weapp.routeRules`

* **类型**：
  ```ts
  Record<
    string,
    {
      appLayout?:
        | string
        | false
        | {
            name: string;
            props?: Record<string, unknown>;
          };
    }
  >;
  ```
* **默认值**：`undefined`

示例：

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

export default defineConfig({
  weapp: {
    routeRules: {
      "pages/dashboard/**": {
        appLayout: "dashboard",
      },
      "pages/admin/**": {
        appLayout: {
          name: "admin",
          props: {
            sidebar: true,
            title: "Admin",
          },
        },
      },
    },
  },
});
```

作用：

* 为一批页面提供默认 layout
* 当页面本身没有写 `definePageMeta({ layout })` 时，作为回退规则生效
* 适合后台壳子、仪表盘壳子、营销页壳子这类“按目录批量套 layout”的场景

## 优先级

优先级从高到低：

1. 页面源码里的 `definePageMeta({ layout })`
2. `weapp.routeRules`
3. `srcRoot/layouts/default.*` 作为默认 layout

如果页面显式写了：

```ts
definePageMeta({
  layout: false,
});
```

则会跳过默认 layout 包裹。

## layout 文件放哪里

默认约定在 `srcRoot/layouts/` 下：

```text
src/
  layouts/
    default.vue
    admin.vue
    dashboard.vue
    native-shell/
      index.json
      index.wxml
      index.wxss
      index.ts
```

支持两种 layout 形式：

* `*.vue`：Vue layout 组件
* 原生四件套目录或文件：原生小程序 layout

layout 名称会根据相对 `layouts/` 目录的路径推导，例如：

* `layouts/default.vue` → `default`
* `layouts/admin.vue` → `admin`
* `layouts/native-shell/index.*` → `native-shell`

## 页面里怎么声明

### 1. 直接指定 layout 名

```vue
<script setup lang="ts">
definePageMeta({
  layout: "admin",
});
</script>
```

### 2. 指定 layout + props

```vue
<script setup lang="ts">
definePageMeta({
  layout: {
    name: "dashboard",
    props: {
      sidebar: true,
      title: "控制台",
    },
  },
});
</script>
```

### 3. 显式关闭 layout

```vue
<script setup lang="ts">
definePageMeta({
  layout: false,
});
</script>
```

> \[!NOTE]
> `definePageMeta().layout` 只支持静态字符串、`false`，或 `{ name, props }` 对象。
> `props` 必须是对象字面量，键名必须是静态的。

## 运行时动态切换

如果页面需要在运行过程中切换 layout，可以使用 `wevu` 提供的 API：

```ts
import { setPageLayout, usePageLayout } from "wevu";

const currentLayout = usePageLayout();

function switchToAdmin() {
  setPageLayout("admin", {
    sidebar: true,
    title: "管理后台",
  });
}

function switchToPlain() {
  setPageLayout(false);
}
```

当项目里存在 layout 扫描结果时，`.weapp-vite/wevu-layouts.d.ts` 会自动为这些 API 生成更严格的类型提示。

## layout 相关类型文件

layout 能力会联动生成：

* `.weapp-vite/wevu-layouts.d.ts`
* `.weapp-vite/components.d.ts`

其中 `wevu-layouts.d.ts` 会增强 `WevuPageLayoutMap`，让 `setPageLayout()` 与 `usePageLayout()` 拿到 layout 名称和 props 类型。

## 适用场景

* 按页面目录批量挂载同一套页面壳子
* 让业务页面复用导航栏、侧边栏、底部容器等布局结构
* 在 Vue layout 与原生 layout 间混合使用
* 在页面运行时按状态切换 layout

## 相关文档

* [页面 Layout 使用指南](/guide/layouts)
* [layouts 目录说明](/guide/directory-structure/layouts)
* [Vue SFC 配置](/config/vue)
* [TypeScript 支持文件](/config/typescript)
* [Wevu 概览](/wevu/)

---

---
url: /config/subpackages.md
description: >-
  weapp-vite 会读取 app.json.subPackages 生成分包产物；weapp.subPackages
  则提供独立分包、分包级内联配置、自动导入覆盖与共享样式等增强能力。
---

# 分包配置 {#subpackages-config}

`app.json.subPackages` 决定“小程序有哪些分包”，而 `weapp.subPackages` 决定“这些分包在构建阶段还需要哪些额外能力”。

这两者要一起看：

* `app.json.subPackages`：声明分包本身
* `weapp.subPackages`：补充构建期增强

\[\[toc]]

## `weapp.subPackages` {#weapp-subpackages}

* **类型**：
  ```ts
  Record<string, {
    independent?: boolean
    inlineConfig?: Partial<InlineConfig>
    autoImportComponents?: AutoImportComponents | boolean
    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',
          },
        ],
      },
    },
  },
})
```

> \[!NOTE]
> 这里的 key 必须与 `app.json.subPackages[].root` 一致，否则不会生效。

## 字段说明

### `independent`

* **类型**：`boolean`

表示该分包是否按独立分包上下文处理。

它通常应和 `app.json` 中对应分包的 `independent: true` 保持一致，避免配置语义分裂。

### `inlineConfig`

* **类型**：`Partial<InlineConfig>`

允许为单个分包追加 Vite 内联配置。

适用场景：

* 某个分包需要额外 `define`
* 某个分包要临时增加插件或局部构建参数

> \[!TIP]
> `inlineConfig` 里写的是 **Vite 原生配置**。字段本身的语义请直接看 [Vite 中文官方配置文档](https://cn.vite.dev/config/)。

### `autoImportComponents`

* **类型**：`AutoImportComponents | boolean`

用于给单个分包覆盖全局组件自动导入策略，或直接关闭它。

常见场景：

* 某个分包不希望自动补 `usingComponents`
* 某个分包需要额外的 resolver 或组件扫描规则

### `watchSharedStyles`

* **类型**：`boolean`

控制该分包在开发时是否监听共享样式并触发重新生成。

适合：

* 分包共享样式很多，且你明确想控制 dev 监听成本

### `styles`

* **类型**：`SubPackageStyleConfigEntry | SubPackageStyleConfigEntry[]`

用于声明分包共享样式入口。

## `subPackages.*.styles` {#subpackages-styles}

`SubPackageStyleConfigEntry` 支持两种形式：

* 字符串
* 对象

对象结构为：

```ts
{
  source: string
  scope?: 'all' | 'pages' | 'components'
  include?: string | string[]
  exclude?: string | string[]
}
```

示例：

```ts
export default defineConfig({
  weapp: {
    subPackages: {
      marketing: {
        styles: [
          'styles/shared.wxss',
          {
            source: 'styles/page-only.wxss',
            scope: 'pages',
            exclude: ['pages/legacy/**'],
          },
        ],
      },
    },
  },
})
```

字段说明：

* `source`：样式源文件路径，可相对分包 root、相对 `srcRoot`，也可直接用绝对路径
* `scope`：
  * `all`：分包内所有页面和组件
  * `pages`：只作用于页面
  * `components`：只作用于组件
* `include` / `exclude`：更精细的 glob 匹配

## 与自动路由的关系

当启用 `weapp.autoRoutes` 时，`weapp.subPackages` 还有一个额外作用：

* 告诉自动路由“哪些 root 应按分包页面目录处理”

如果你的分包页面不走默认 `root/pages/**` 约定，通常需要同时配置：

* `weapp.subPackages`
* `weapp.autoRoutes.include`

## 与 npm 分包落位的关系

`weapp.subPackages` 不负责 npm 包落位。

如果你要控制：

* 哪些依赖进入主包 `miniprogram_npm`
* 哪些依赖进入指定分包 `miniprogram_npm`

请使用：

* `weapp.npm.mainPackage`
* `weapp.npm.subPackages`

详见 [npm 配置](./npm.md)。

## 常见建议

### 什么时候要用 `inlineConfig`

只有当某个分包真的需要“局部构建差异”时再用。大多数分包项目先保持全局统一配置更稳。

### 什么时候要把样式抽到 `styles`

当一套共享样式要稳定作用于整个分包，而不是单个组件手动导入时，这个字段价值最高。

### 独立分包为什么还要单独关注共享 chunk

因为独立分包不参与普通分包那套共享分发模型。做分包优化时，要一起看：

* [共享 Chunk 配置](./chunks.md)
* [npm 配置](./npm.md)

***

如果你接下来要继续处理分包依赖落位，请看 [npm 配置](./npm.md)。如果你要继续处理共享模块落盘策略，请看 [共享 Chunk 配置](./chunks.md)。

---

---
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: /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}

* **类型**：`false | { entries?: Record<string, string> | { find: string | RegExp; replacement: string }[] }`
* **默认值**：不启用，需要通过 `entries` 显式配置
* **作用范围**：**仅作用于 `usingComponents`**（其他字段保持原样）。

默认情况下，`compilerOptions.paths` 只会参与 JS/TS 模块解析，不会自动作用到 JSON / JSONC 的 `usingComponents`。如果源码页面 `src/pages/index/index.json` 里需要写 `@/components/foo` 这类路径，请显式配置 `weapp.jsonAlias.entries`。

如果需要完全关闭 JSON 别名，可以设置 `jsonAlias: false`：

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

export default defineConfig({
  weapp: {
    jsonAlias: false,
  },
})
```

```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: /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 流程中。JSON / JSONC 的 `usingComponents` 不会默认继承 `paths`，需要别名时请显式配置 `weapp.jsonAlias`。只有在你传入高级选项对象时，才会回退到 `vite-tsconfig-paths` 插件。

\[\[toc]]

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

* **类型**：`true | 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。
* JSON / JSONC 的 `usingComponents` 不会默认继承 `compilerOptions.paths`；需要别名时请显式配置 `weapp.jsonAlias`。
* 你仍然可以在 `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`；它不会默认继承 `compilerOptions.paths`（见 [JSON 配置](/config/json.md#weapp-jsonalias)）。

## `weapp.ast` {#weapp-ast}

* **类型**：`{ engine?: 'babel' | 'oxc' }`
* **默认值**：`{ engine: 'babel' }`

`weapp.ast` 用来控制部分“静态分析链路”优先使用哪套 AST 引擎，例如：

* 组件 props 元数据提取
* `usingComponents` / 自动导入相关分析
* `setData.pick` 模板 key 收集
* 一部分平台 API / require 快速判定

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

export default defineConfig({
  weapp: {
    ast: {
      engine: 'oxc',
    },
  },
})
```

使用建议：

* 默认保持 `babel` 即可，兼容性最稳。
* 当你明确想在“分析链路”上尝试更快的解析实现时，再切到 `oxc`。
* 这不是“所有编译流程全部切换引擎”的总开关，而是给已接入 AST 抽象层的分析能力提供统一入口。

***

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

---

---
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）编译链路。这里聚焦编译期可配置项。

> \[!TIP]
> 如果你在找页面级 `layout` 能力，请优先看 [Route Rules 与 Layout](/config/route-rules)。`layout` 本身不属于 `weapp.vue` 字段，而是通过 `definePageMeta()`、`weapp.routeRules` 与 `srcRoot/layouts/` 目录协同工作。

\[\[toc]]

## `weapp.vue.enable` {#weapp-vue-enable}

* **类型**：`boolean`
* **默认值**：`true`
* **说明**：保留字段。当前版本会在检测到 `.vue` 时自动启用 SFC 支持，该字段不影响行为。

## `weapp.vue.template` {#weapp-vue-template}

* **类型**：
  ```ts
  {
    removeComments?: boolean
    simplifyWhitespace?: boolean
    formatWxml?: boolean | 'auto'
    htmlTagToWxml?: boolean | Record<string, string>
    htmlTagToWxmlTagClass?: boolean
    scopedSlotsCompiler?: 'auto' | 'augmented' | 'off'
    scopedSlotsRequireProps?: boolean
    slotSingleRootNoWrapper?: boolean
    slotFallbackWrapperStrategy?: 'view' | 'virtual-host'
    slotFallbackWrapper?: string | {
      tag?: string
      attrs?: Record<string, string>
      singleRootNoWrapper?: boolean
      rules?: Array<{
        component?: string | RegExp | Array<string | RegExp>
        componentName?: string | RegExp | Array<string | RegExp>
        slot?: string | RegExp | Array<string | RegExp>
        tag?: string
        attrs?: Record<string, string>
        singleRootNoWrapper?: boolean
      }>
    }
    slotMultipleInstance?: boolean
    classStyleRuntime?: 'auto' | 'wxs' | 'js'
    objectLiteralBindMode?: 'runtime' | 'inline'
    mustacheInterpolation?: 'compact' | 'spaced'
    classStyleWxsShared?: boolean
    functionPropNames?: Array<string | RegExp>
  }
  ```

示例：

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        htmlTagToWxml: true,
        htmlTagToWxmlTagClass: true,
        formatWxml: 'auto',
        scopedSlotsCompiler: 'auto',
        scopedSlotsRequireProps: false,
        slotSingleRootNoWrapper: false,
        slotFallbackWrapperStrategy: 'virtual-host',
        slotFallbackWrapper: {
          tag: 'view',
          attrs: {
            class: 'slot-wrapper',
          },
          rules: [
            { component: 'IssueCard', slot: 'header', tag: 'cover-view' },
            { componentName: 'HelloWorld', slot: 'header', tag: 'cover-view' },
            {
              component: 'IssueCard',
              slot: 'footer',
              attrs: {
                class: 'slot-footer',
              },
            },
            { component: /^Van/, slot: ['title', 'label'], tag: 'view' },
          ],
        },
        slotMultipleInstance: true,
        classStyleRuntime: 'js',
        objectLiteralBindMode: 'runtime',
        mustacheInterpolation: 'compact',
        classStyleWxsShared: true,
        functionPropNames: ['handler', /^on[A-Z]/],
      },
    },
  },
})
```

字段说明：

* `htmlTagToWxml`：是否将 `.vue` 模板中的常见 HTML 标签映射为小程序内置标签。
  * `true` 或省略：启用默认映射表（例如 `div -> view`、`span -> text`、`img -> image`、`a -> navigator`、`br -> view`、`hr -> view`）。
  * `false`：关闭该能力，保留模板中的原始标签名。
  * `Record<string, string>`：在默认映射表基础上追加或覆盖自定义映射。
* `htmlTagToWxmlTagClass`：是否在发生 HTML 标签映射时，同时给转换后的节点追加“原标签名 class”。
  * 默认 `true`。
  * 启用后，`<h3 class="title" :class="dynamicCls" />` 会编译为带有稳定语义 class 的节点，静态 class 会拼合成 `h3 title`，动态 `:class` 保持原样。
  * 适合低成本还原 `h1/h2/h3/ul/ol/li/p/br/hr` 等 HTML 标签的默认外观。
  * 设为 `false` 时，只做标签名映射，不追加这层 class。
* `formatWxml`：是否格式化 `.vue` / JSX 编译生成的 WXML。
  * `auto` 或省略：开发态默认开启，生产构建默认关闭。
  * `true`：始终输出带缩进和换行的 WXML，便于在开发者工具中调试。
  * `false`：始终保持紧凑输出，适合对包体更敏感的场景。
  * 当前只做标签层级缩进；含文本内容的元素会保持单行，避免重排文本空白语义。
* `scopedSlotsCompiler`：作用域插槽编译策略。
  * `auto`：自动选择最小可用方案（默认）。
  * `augmented`：强制使用增强方案。
  * `off`：关闭 scoped slot（仅保留原生 slot，不支持 slot props）。
* `scopedSlotsRequireProps`：仅在 slot 传递作用域参数时才生成 scoped slot 组件。默认 `false`，普通插槽内容也会走增强 scoped slot 组件，以便 slot 投影下的运行时父子关系可被 `provide()` / `inject()` 正确解析；设为 `true` 可保留普通插槽的原生 slot 输出。
* `slotSingleRootNoWrapper`：普通具名插槽内容只有一个可投影根节点时，是否把 `slot="..."` 直接下推到该根节点，避免额外生成 wrapper。
  * 默认 `false`，保持稳定的真实节点 wrapper。
  * 开启后只影响“单个可投影根节点”；多节点、空内容、转发 `<slot />` 等场景仍会保留真实 wrapper。
* `slotFallbackWrapperStrategy`：配置普通具名插槽 fallback wrapper 的默认策略。
  * 微信平台默认 `virtual-host`，会自动生成内部 `virtualHost` 组件作为 wrapper，减少 `view` 带来的布局影响。
  * 其他平台默认 `view`。
  * 如果需要回到旧行为，可显式配置为 `view`，或继续显式配置 `slotFallbackWrapper: 'view'`。
* `slotFallbackWrapper`：配置普通具名插槽 fallback wrapper 的真实标签。
  * 微信平台默认由 `slotFallbackWrapperStrategy: 'virtual-host'` 生成内部 `virtualHost` wrapper；其他平台默认 `view`。
  * 字符串形式等价于 `{ tag: '...' }`。
  * 显式配置该字段后，会优先使用这里指定的真实标签，并保持旧版 `view` / 自定义标签行为。
  * 对象形式支持全局默认 `tag`、全局默认 `attrs`、全局默认 `singleRootNoWrapper`，以及按组件 / 插槽匹配的 `rules`。
  * `rules[].component` 匹配模板里的组件标签名，例如 `<IssueCard>` 对应 `IssueCard`，`<issue-card>` 对应 `issue-card`。
  * `rules[].componentName` 匹配被引用 Vue SFC 的组件名，也就是子组件里静态 `defineOptions({ name: 'HelloWorld' })` 的 `name`。这个字段需要编译器能解析到该子组件的 `.vue` 文件；原生组件或第三方小程序组件通常没有这个信息，应继续用 `component`。
  * `rules[].component`、`rules[].componentName` 与 `rules[].slot` 都支持字符串、正则或数组；同一条规则里写了多个匹配条件时需要同时命中。规则按顺序匹配，后匹配到的字段可覆盖前面的字段。
  * `attrs` 是追加到 fallback wrapper 上的静态属性，适合项目级 class、style 或 `data-*`；组件使用处可用 `slot-wrapper-class` / `slot-wrapper-style` 继续覆盖。
  * `block` 不能作为 wrapper。`<block slot="header"><slot /></block>` 在转发 slot 场景会在真实 DevTools 运行时丢内容；如果配置成 `block`，编译器会回退到 `view` 并输出 warning。
* `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（主包与非独立分包共享，独立分包各自生成）。
* `functionPropNames`：显式声明需要按函数 prop 传递的组件 prop 名称。
  * 默认值为空，不内置 `callback`、`handler`、`on-*`、`change` 等名称猜测。
  * 字符串按 prop 名称精确匹配；正则表达式按 prop 名称测试。
  * 例如 `functionPropNames: ['handler', /^on[A-Z]/]` 会让 `&lt;Comp :handler="callbacks[id]" /&gt;` 生成运行时绑定；普通值绑定如 `&lt;Comp :selected="data.userId" /&gt;` 仍直接输出 `selected` 对 `data.userId` 的 Mustache 绑定，不会生成 `__wv_bind_*`。

示例：关闭默认映射

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        htmlTagToWxml: false,
      },
    },
  },
})
```

示例：覆盖部分标签映射

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        htmlTagToWxml: {
          section: 'view',
          article: 'view',
          a: 'navigator',
        },
      },
    },
  },
})
```

示例：关闭自动追加原标签 class

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        htmlTagToWxml: true,
        htmlTagToWxmlTagClass: false,
      },
    },
  },
})
```

示例：默认开启时的模板效果

```vue
<template>
  <div class="wrap">
    <h3 :class="titleClass">标题</h3>
    <hr />
    <br />
  </div>
</template>
```

会编译出类似结果：

```wxml
<view class="div wrap">
  <view class="h3" :class="titleClass">标题</view>
  <view class="hr" />
  <view class="br" />
</view>
```

> \[!NOTE]
> `htmlTagToWxml` 只作用于 Vue SFC 模板编译，不影响原生 `.wxml` 文件。
>
> `htmlTagToWxmlTagClass` 只在“标签名确实发生了 HTML -> WXML 映射”时生效；像 `button -> button` 这类未改名场景，不会额外注入 `.button`。
>
> `removeComments` / `simplifyWhitespace` 当前仍是兼容性预留位，尚未接入实际编译流程；其余字段已经参与模板编译输出。

### 自定义具名插槽 wrapper {#slot-fallback-wrapper}

当普通具名插槽内容是转发的 `<slot />` 时，小程序不能直接接收 `<slot slot="header" />`，也不能稳定接收 `<block slot="header"><slot /></block>`。微信平台默认会生成一个内部 `virtualHost` 组件作为 wrapper：

```wxml
<weapp-slot-wrapper slot="header">
  <slot />
</weapp-slot-wrapper>
```

同时会在当前入口 JSON 中自动注入内部组件引用。若需要回到旧版 `view` 行为，可配置 `slotFallbackWrapperStrategy: 'view'`，或显式配置 `slotFallbackWrapper: 'view'`。

如果某些组件的某些具名插槽需要用其他真实节点承载，可以用 `slotFallbackWrapper` 全局配置：

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        slotFallbackWrapper: {
          tag: 'view',
          attrs: {
            class: 'slot-wrapper',
          },
          rules: [
            { component: 'IssueCard', slot: 'header', tag: 'cover-view' },
            { componentName: 'HelloWorld', slot: 'header', tag: 'cover-view' },
            {
              component: 'IssueCard',
              slot: 'footer',
              attrs: {
                class: 'slot-footer-global',
              },
            },
            { component: /^Van/, slot: ['title', 'label'], tag: 'view' },
          ],
        },
      },
    },
  },
})
```

`component` 匹配的是使用处模板标签名，不是子组件声明名。比如下面这个模板里，`component: 'issue-card'` 会命中，`component: 'HelloWorld'` 不会命中：

```vue
<template>
  <issue-card>
    <template #header>
      <slot />
    </template>
  </issue-card>
</template>

<script setup lang="ts">
import IssueCard from '@/components/IssueCard.vue'
</script>
```

如果你希望按子组件自己的名字匹配，需要让子组件声明静态 `defineOptions({ name })`，然后在规则里使用 `componentName`：

```vue
<!-- components/IssueCard.vue -->
<script setup lang="ts">
defineOptions({
  name: 'HelloWorld',
})
</script>
```

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        slotFallbackWrapper: {
          rules: [
            { componentName: 'HelloWorld', slot: 'header', tag: 'cover-view' },
          ],
        },
      },
    },
  },
})
```

`componentName` 只在编译器能解析到被引用的 Vue SFC 时可用，包括 `<script setup>` 直接 import 的组件和自动导入 resolver 标记为 `wevu-sfc` 的组件。原生小程序组件、没有静态 `defineOptions({ name: '...' })` 的组件，继续使用 `component` 匹配模板标签名更明确。

也可以直接在组件使用处用静态属性覆盖当前组件的 wrapper。组件内配置推荐使用普通 kebab-case 静态属性，避免和 Vue 指令参数语法混淆。

#### `slot-wrapper`：当前组件所有普通具名插槽的默认 wrapper {#slot-wrapper-default}

`slot-wrapper` 会作为当前组件所有普通具名插槽的默认 wrapper。下面的 `header` 和 `footer` 都会使用 `cover-view`：

```vue
<template>
  <IssueCard slot-wrapper="cover-view">
    <template #header>
      <slot />
    </template>
    <template #footer>
      <slot name="footer" />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <cover-view slot="header">
    <slot />
  </cover-view>
  <cover-view slot="footer">
    <slot name="footer" />
  </cover-view>
</IssueCard>
```

#### `slot-wrapper-<slotName>`：覆盖指定具名插槽 {#slot-wrapper-named}

如果同一个组件的不同具名插槽需要不同 wrapper，可以继续保留 `slot-wrapper` 作为默认值；单个 slot 的覆盖更推荐直接写在对应的 `<template #xxx>` 上：

```vue
<template>
  <IssueCard slot-wrapper="cover-view">
    <template #header>
      <slot />
    </template>
    <template #footer slot-wrapper="view">
      <slot name="footer" />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <cover-view slot="header">
    <slot />
  </cover-view>
  <view slot="footer">
    <slot name="footer" />
  </view>
</IssueCard>
```

这里 `header` 继承 `slot-wrapper="cover-view"`，`footer` 在对应的 `<template #footer>` 上覆盖。

如果只想覆盖某一个 `<template #xxx>`，更推荐把配置直接写在对应的 slot template 上。这个写法最贴近 slot 内容，优先级也高于父组件标签上的默认值和 `slot-wrapper-<slotName>`：

```vue
<template>
  <IssueCard slot-wrapper="cover-view">
    <template #header slot-wrapper="text" slot-wrapper-class="slot-header">
      <slot />
    </template>
    <template #footer>
      <slot name="footer" />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <text slot="header" class="slot-header" style="margin-top: 12px">
    <slot />
  </text>
  <cover-view slot="footer">
    <slot name="footer" />
  </cover-view>
</IssueCard>
```

在 `<template #header>` 上写时，已经知道目标 slot 名，属性仍写 `slot-wrapper` / `slot-wrapper-class` / `slot-wrapper-style` / `slot-single-root-no-wrapper`，不需要再写 `slot-wrapper-header`。如果只是改单个 slot，优先把配置写在 `<template #header>` 上。

#### `slot-wrapper-class/style`：给生成的 wrapper 加属性 {#slot-wrapper-attrs}

普通 `class` / `style` 仍然属于组件本身，不会被转移到编译器生成的 slot wrapper 上。如果要给 wrapper 加样式，需要使用 wrapper 虚拟属性：

```vue
<template>
  <IssueCard slot-wrapper="cover-view">
    <template #header slot-wrapper="cover-view" slot-wrapper-class="slot-default" slot-wrapper-style="padding: 8px">
      <slot />
    </template>
    <template
      #footer
      slot-wrapper="view"
      slot-wrapper-class="slot-footer"
      slot-wrapper-style="margin-top: 12px"
    >
      <slot name="footer" />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <cover-view slot="header" class="slot-default" style="padding: 8px">
    <slot />
  </cover-view>
  <view slot="footer" class="slot-footer" style="margin-top: 12px">
    <slot name="footer" />
  </view>
</IssueCard>
```

也支持动态绑定，仍然使用静态参数名：

```vue
<IssueCard
  :slot-wrapper-class="headerClass"
  :slot-wrapper-style="headerStyle"
>
  <template #header>
    <slot />
  </template>
  <template #footer :slot-wrapper-class="footerClass">
    <slot name="footer" />
  </template>
</IssueCard>
```

指定插槽的 class/style 只覆盖对应属性。上例中 `footer` 在 `<template #footer>` 上覆盖了 class，但仍会继承默认的 `slot-wrapper-style`。

局部配置优先级高于全局配置。整体优先级为：`<template #slot>` 上的 `slot-wrapper` / `slot-wrapper-class/style` / `slot-single-root-no-wrapper` > 父组件标签上的 `slot-wrapper-<slotName>` / `slot-wrapper-<slotName>-class/style` / `slot-single-root-no-wrapper-<slotName>` > 父组件标签上的 `slot-wrapper` / `slot-wrapper-class/style` / `slot-single-root-no-wrapper` > `slotFallbackWrapper.rules` > `slotFallbackWrapper.tag` / `slotFallbackWrapper.attrs` > `slotFallbackWrapperStrategy` 默认策略。

#### `slot-single-root-no-wrapper-<slotName>`：单根真实节点下推 `slot` {#slot-single-root-no-wrapper-named}

如果要按插槽开启单根下推，也可以用全局规则：

```ts
export default defineConfig({
  weapp: {
    vue: {
      template: {
        slotFallbackWrapper: {
          tag: 'view',
          rules: [
            { component: 'IssueCard', slot: 'icon', singleRootNoWrapper: true },
          ],
        },
      },
    },
  },
})
```

或在组件使用处写静态属性：

```vue
<template>
  <IssueCard slot-single-root-no-wrapper-icon>
    <template #icon>
      <image src="/assets/icon.png" />
    </template>
  </IssueCard>
</template>
```

当 `icon` 插槽内容是单个真实节点时，会尽量把 `slot="icon"` 下推到这个节点：

```wxml
<IssueCard>
  <image slot="icon" src="/assets/icon.png" />
</IssueCard>
```

这个策略只适用于“单根真实节点”。如果插槽内容是转发 `<slot />`、多个根节点、空内容，编译器仍会保留 wrapper：

```vue
<template>
  <IssueCard slot-single-root-no-wrapper-header>
    <template #header>
      <slot />
    </template>
  </IssueCard>
</template>
```

产物仍是：

```wxml
<IssueCard>
  <weapp-slot-wrapper slot="header">
    <slot />
  </weapp-slot-wrapper>
</IssueCard>
```

#### `block`：显式配置后按原样输出 {#slot-wrapper-block}

默认策略不会把 `block` 作为 fallback wrapper。你可以显式配置 `block`，编译器会按原样输出，但这需要自行承担宿主运行时兼容性风险：

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        slotFallbackWrapper: 'block',
      },
    },
  },
})
```

下面的 Vue 写法：

```vue
<template>
  <IssueCard>
    <template #header>
      <slot />
    </template>
  </IssueCard>
</template>
```

会生成 `<block slot="header"><slot /></block>`：

```wxml
<IssueCard>
  <block slot="header">
    <slot />
  </block>
</IssueCard>
```

注意：issue #613 的真实 WeChat DevTools e2e 已验证，`<block slot="header"><slot></slot></block>` 在转发 `<slot />` 的部分场景会丢失内容。因此 `block` 不作为默认值，只建议在你确认目标运行时和具体插槽内容可用时显式启用。

#### wrapper 必须能承载实际内容 {#slot-wrapper-content}

编译器只负责按配置生成标签，目标小程序运行时是否允许该标签承载子节点，仍取决于宿主规则和实际内容。比如下面的配置会让 `header` 使用 `text`：

```vue
<template>
  <IssueCard>
    <template #header slot-wrapper="text">
      <view>Header</view>
    </template>
  </IssueCard>
</template>
```

产物会是：

```wxml
<IssueCard>
  <text slot="header">
    <view>Header</view>
  </text>
</IssueCard>
```

> \[!WARNING]
> `text` 不适合包裹 `<view>` 子内容。需要包裹视图节点时，使用 `view`、`cover-view` 或经过目标小程序运行时验证的自定义组件；`block` 不是可渲染 wrapper，不能用于转发 `<slot />` 的命名插槽容器。

## `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: /config/wevu.md
description: 说明 weapp.wevu.defaults、preset 与 autoSetDataPick 的作用、默认行为和适用场景。
---

# Wevu 编译期配置 {#wevu-config}

本页聚焦 `weapp.wevu` 这组“编译期注入 / 默认值治理”配置。它们主要影响：

* `app.vue` 编译时是否自动注入 `setWevuDefaults()`
* 组件 / 页面默认 `setData` 策略
* 是否自动从模板推导 `setData.pick`

> \[!NOTE]
> 这里讨论的是 `weapp-vite` 在编译阶段帮你做什么，不是 `wevu` 运行时 API 的完整手册。运行时能力请继续阅读 [/wevu/runtime](/wevu/runtime)。

> \[!TIP]
> Wevu 在执行 `defineAppJson()`、`definePageJson()` 等 JSON 宏时，临时配置缓存默认写入项目内的 `.weapp-vite/wevu-config`，并会在首次使用时按需创建该目录；只有无法定位有效项目目录时才会回退到系统临时目录。

\[\[toc]]

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

* **类型**：`WevuDefaults`
* **默认值**：`undefined`
* **作用**：在编译 `app.vue` 时自动注入 `setWevuDefaults()`，统一控制 Wevu 的 `createApp/defineComponent` 默认值。

### 配置示例

```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`，避免页面虚拟节点导致的渲染层错误；需要为页面开启时请在页面内显式配置。

### `component.allowNullPropInput`

从 `weapp-vite 6.15.1 / wevu 6.15.1` 开始，`weapp.wevu.defaults.component.allowNullPropInput` 默认会被设为 `true`：

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

export default defineConfig({
  weapp: {
    wevu: {
      defaults: {
        component: {
          allowNullPropInput: true,
        },
      },
    },
  },
})
```

它的作用是兼容小程序运行时把传入的 `undefined` 视为 `null` 的行为，减少 `String`、`Number` 等已声明类型 props 在微信开发者工具里反复出现的 `null` 类型告警。

如果你的项目明确希望保持“`null` 一律视为非法输入”的旧行为，也可以显式关闭：

```ts
export default defineConfig({
  weapp: {
    wevu: {
      defaults: {
        component: {
          allowNullPropInput: false,
        },
      },
    },
  },
})
```

> \[!TIP]
> 这个默认值同样会覆盖“页面 / 组件没有显式 props 定义”的场景，避免空属性归一化时出现 `Object.entries(undefined)` 一类启动期报错。

### 全局默认开启 `virtualHost: true`

微信官方文档里的 `virtualHost: true`，在 `weapp-vite` + `wevu` 里推荐通过 `weapp.wevu.defaults.component.options.virtualHost` 统一配置。

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

export default defineConfig({
  weapp: {
    wevu: {
      defaults: {
        component: {
          options: {
            virtualHost: true,
          },
        },
      },
    },
  },
})
```

这样做之后：

* 所有通过 Wevu 编译的**组件**默认都会带上 `options.virtualHost = true`
* **页面**不会继承这个默认值；Weapp-vite 会自动补成 `virtualHost: false`
* 某个组件如果显式写了自己的 `options.virtualHost`，以组件内声明为准

适合场景：

* 你希望项目里的大多数业务组件都走虚拟节点
* 你不想在每个组件里重复手写 `options: { virtualHost: true }`
* 你仍然希望页面保持安全默认值，避免误把页面也变成虚拟节点

### `virtualHost` 的覆盖规则

可以把优先级理解成：

1. 组件/页面文件里的显式配置
2. `weapp.wevu.defaults.component.options`
3. Wevu / Weapp-vite 内建默认值

最常见的结果是：

* 全局设了 `component.options.virtualHost = true` 后，组件默认开启
* 页面即使命中了同一套默认项，也会被编译器改写为 `virtualHost: false`
* 如果你真的要给某个页面开启，必须在页面内手动显式声明

## 手动开启 `virtualHost` 的几种方式 {#manual-virtualhost}

如果你不想全局开启，或者只想给少数组件/页面单独配置，可以直接在文件里手动声明。

### 方式 1：`<script setup>` + `defineComponentJson`

适合新增的 Wevu Vue SFC 组件：

```vue
<script setup lang="ts">
defineComponentJson(() => ({
  component: true,
  options: {
    virtualHost: true,
  },
}))
</script>
```

### 方式 2：`<script setup>` + `defineOptions`

适合你已经在组件里使用 `defineOptions()` 管原生组件选项：

```vue
<script setup lang="ts">
defineOptions({
  options: {
    virtualHost: true,
  },
})
</script>
```

### 方式 3：`defineComponent({ options })`

适合非 `<script setup>` 写法：

```ts
import { defineComponent } from 'wevu'

export default defineComponent({
  options: {
    virtualHost: true,
  },
  setup() {
    return {}
  },
})
```

### 方式 4：`<json>` 配置块

适合历史 SFC 或仍在用 `<json>` 的项目：

```vue
<json lang="jsonc">
{
  "component": true,
  "options": {
    "virtualHost": true
  }
}
</json>
```

### 方式 5：原生组件 `component.json`

适合不是 Wevu SFC、而是原生小程序组件目录：

```json
{
  "component": true,
  "options": {
    "virtualHost": true
  }
}
```

## FAQ

### Q: 能不能让全局组件默认都开启 `virtualHost: true`？

可以。直接配置 `weapp.wevu.defaults.component.options.virtualHost = true` 即可。

### Q: 全局开启后，会不会把页面也一起改成 `virtualHost: true`？

不会。Weapp-vite 会对页面自动回退成 `virtualHost: false`，避免页面误用虚拟节点。

### Q: 页面如果也想开启怎么办？

在页面文件里显式声明 `options.virtualHost = true`。页面内的手动配置优先级高于全局默认值。

### Q: 手动配置和全局默认同时存在时，谁生效？

以文件内显式配置为准；全局默认只负责“补默认值”，不会覆盖你在页面或组件里手写的 `options.virtualHost`。

### Q: 我全局开了 `virtualHost: true`，为什么 `<MyCard class="text-red-500" />` 还不能把组件内部文字变红？

因为这里涉及两个不同层面的能力：

* `virtualHost: true` 只决定“组件宿主节点是否可见”
* `styleIsolation: 'apply-shared'` 只决定“页面样式是否允许影响组件内部”

它们都**不会**自动把组件标签上的 `class/style` 透传到组件内部根节点。

如果你需要外部样式真正落到组件内部，推荐：

* 用 `externalClasses` 显式接收外部类名
* 或者提供 `rootStyle` / `customStyle` 这类显式 prop

更多写法见 [/wevu/vue-sfc/config](/wevu/vue-sfc/config)。

> \[!TIP]
> 如果你不通过 Weapp-vite 构建，也可以在运行时手动调用 `setWevuDefaults()`（见 [/wevu/runtime](/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` 数组。

## 关联阅读

* [Vue SFC 配置](/config/vue.md)
* [TypeScript 支持文件](/config/typescript.md)
* [Wevu 运行时](/wevu/runtime)

---

---
url: /config/hmr.md
description: >-
  说明 weapp.hmr.runtime、sharedChunks、touchAppWxss、logLevel 与 profileJson
  的默认行为、适用场景和取舍。
---

# 开发态 HMR 配置 {#hmr-config}

`weapp.hmr` 用来控制开发态更新时的“稳定性 vs 速度”取舍，也可以打开更细的终端诊断与结构化 profile 输出。本页覆盖：

* `weapp.hmr.sharedChunks`
* `weapp.hmr.runtime`
* `weapp.hmr.touchAppWxss`
* `weapp.hmr.logLevel`
* `weapp.hmr.profileJson`

\[\[toc]]

## `weapp.hmr.runtime` {#weapp-hmr-runtime}

* **类型**：`'classic' | 'stateful-experimental'`
* **默认值**：`'classic'`
* **适用场景**：在微信开发者工具中更新原生 Page、原生 Component 或 wevu Vue SFC 时，保留当前页面实例、路由参数、输入和可序列化 data/setup ref。

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

export default defineConfig({
  weapp: {
    hmr: {
      runtime: 'stateful-experimental',
    },
  },
})
```

`stateful-experimental` 目前只支持微信小程序平台。它使用 Vite bundled dev graph 和微信 App Service 内的增量补丁协议，JavaScript/Vue 安全更新会在现有实例上替换方法并恢复状态。CSS、静态资源、JSON/配置变化、模块边界不兼容、补丁积压超过保留上限或补丁执行失败时，会回退到完整构建并通过 `wx.reLaunch` 恢复当前 route/query。

使用前请确认：

* 微信开发者工具已开启服务端口，并在项目设置中启用热重载。
* `project.private.config.json` 的 `setting.compileHotReLoad` 为 `true`。
* 这是实验能力；需要完全沿用既有写盘/刷新语义时保持默认 `classic`。
* 状态恢复只覆盖可序列化的小程序 data 和 wevu setup ref；定时器、网络连接、原生句柄等副作用仍应由应用生命周期管理。

## `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 导出关系复杂时更容易出现开发态不一致。

建议：

* 普通项目保持默认 `auto`。
* 遇到“开发态偶发错乱、刷新后恢复正常”的共享 chunk 问题时，优先尝试 `full`。
* 只有在你确认项目结构简单且极度在意 dev 重建速度时，再考虑 `off`。

## `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-tailwindcss` 且样式热更新已经稳定，可保持默认或显式关闭。

## `weapp.hmr.logLevel` {#weapp-hmr-loglevel}

* **类型**：`'default' | 'concise' | 'verbose'`
* **默认值**：`'default'`
* **适用场景**：控制 HMR 终端日志的详细程度。

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

export default defineConfig({
  weapp: {
    hmr: {
      logLevel: 'concise',
    },
  },
})
```

行为说明：

* `default`：只输出总耗时等基础信息，适合日常开发。
* `concise`：输出关键阶段耗时，适合定位“哪一类更新慢”。
* `verbose`：输出更完整的阶段诊断，适合排查 HMR 链路异常。

建议：

* 日常保持 `default`。
* 只有在定位 HMR 慢、共享 chunk 回退或 DevTools 热重载不稳定时，再临时提高到 `concise` 或 `verbose`。

## `weapp.hmr.profileJson` {#weapp-hmr-profilejson}

* **类型**：`boolean | string`
* **默认值**：`false`
* **适用场景**：输出 HMR 结构化 profile，方便后续脚本、AI 或报告工具分析。

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

export default defineConfig({
  weapp: {
    hmr: {
      profileJson: '.tmp/weapp-vite-hmr-profile.jsonl',
    },
  },
})
```

行为说明：

* `false`：不输出结构化 profile。
* `true`：使用默认 profile 输出路径。
* 字符串：写入指定 JSONL 文件路径。

> \[!TIP]
> 当你需要把 HMR 诊断交给 AI 或 CI 侧脚本复盘时，优先开启 `profileJson`，再结合 `logLevel: 'concise'` 或 `verbose` 缩小问题范围。

## 关联阅读

* [共享 Chunk 配置](/config/chunks.md)
* [共享配置](/config/shared.md)
* [调试指南](/guide/debug.md)

---

---
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: /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: /config/shared.md
description: weapp-vite 的共享增强配置，包含自动路由、调试钩子、日志、forwardConsole、injectWeapi 与 MCP 等能力。
---

# 共享配置 {#shared-config}

这一页覆盖那些“不只属于某一种文件类型”的通用增强能力：

* 自动路由
* 调试钩子
* 构建日志控制
* DevTools 控制台日志桥接
* 本地 MCP 服务

\[\[toc]]

## `weapp.autoRoutes` {#weapp-autoroutes}

* **类型**：`boolean | WeappAutoRoutesConfig`
* **默认值**：`false`

其中 `WeappAutoRoutesConfig` 为：

```ts
{
  enabled?: boolean
  typedRouter?: boolean
  include?: string | RegExp | Array<string | RegExp>
  persistentCache?: boolean | string
  watch?: boolean
}
```

作用：

* 从页面目录自动生成路由清单
* 输出 `.weapp-vite/typed-router.d.ts`
* 提供 `weapp-vite/auto-routes` 虚拟模块

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

export default defineConfig({
  weapp: {
    autoRoutes: {
      enabled: true,
      typedRouter: true,
      include: ['pages/**'],
      persistentCache: true,
      watch: true,
    },
  },
})
```

字段说明：

* `enabled`：总开关
* `typedRouter`：是否输出路由类型文件
* `include`：扫描规则，支持 glob、正则和数组
* `persistentCache`：是否启用持久化缓存，或指定缓存文件路径
* `watch`：开发态是否监听页面目录变化

> \[!TIP]
> 默认规则会扫描主包 `pages/**` 和已声明分包 root 下的 `pages/**`。如果你的页面目录不走这个约定，记得同步配置 `include` 和 `weapp.subPackages`。

## `weapp.debug` {#weapp-debug}

用于排查“为什么没扫描到”“为什么模块没被正确处理”“为什么某个环节很慢”。

主要钩子包括：

* `watchFiles`
* `resolveId`
* `load`
* `vueTransformTiming`
* `inspect`

```ts
export default defineConfig({
  weapp: {
    debug: {
      watchFiles(files, meta) {
        console.info(meta?.subPackage.root ?? 'main', files)
      },
      resolveId(id) {
        if (id.includes('tdesign')) {
          console.log('[resolveId]', id)
        }
      },
      inspect: {
        hooks: 'all',
      },
    },
  },
})
```

适用场景：

* 模块解析异常
* 构建卡顿定位
* 分包边界和监听文件排查
* Vue SFC 编译耗时定位

## `weapp.logger` {#weapp-logger}

* **类型**：`LoggerConfig`

控制 CLI、构建器和分析命令的日志输出。

```ts
export default defineConfig({
  weapp: {
    logger: {
      level: 'info',
      tags: {
        build: true,
        mcp: false,
      },
    },
  },
})
```

它主要适合：

* CI 降噪
* 只打开特定子系统标签
* 本地排查时临时放大日志范围

## `weapp.forwardConsole` {#weapp-forwardconsole}

* **类型**：`boolean | WeappForwardConsoleConfig`

其中 `WeappForwardConsoleConfig` 为：

```ts
{
  enabled?: boolean | 'auto'
  logLevels?: Array<'debug' | 'log' | 'info' | 'warn' | 'error'>
  unhandledErrors?: boolean
}
```

用于把微信开发者工具中的运行时日志桥接回当前终端。

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

常见用途：

* AI 联调时不来回切 DevTools 控制台
* 截图验收前同步观察页面日志和异常
* 远程协作时把小程序错误统一收敛到终端

相关命令：

```bash
wv dev --open
wv ide logs
wv ide logs --open
```

## `weapp.injectWeapi` {#weapp-injectweapi}

* **类型**：`boolean | { enabled?: boolean; replaceWx?: boolean; globalName?: string }`

用于注入 `@wevu/api` 运行时实例。

```ts
export default defineConfig({
  weapp: {
    injectWeapi: {
      enabled: true,
      replaceWx: false,
      globalName: 'wpi',
    },
  },
})
```

字段说明：

* `enabled`：是否启用注入
* `replaceWx`：是否同步替换全局 `wx`
* `globalName`：挂载到全局的变量名

适用场景：

* 团队统一走 `@wevu/api`
* 希望在运行时补齐一套更一致的 API 访问入口

> \[!NOTE]
> 当前 `replaceWx` 会采用静态宿主全局同步与源码重写，不再依赖 `Function(...)` 这类动态执行能力，因此更适合真实小程序宿主与受限运行环境。

## `weapp.mcp` {#weapp-mcp}

* **类型**：`boolean | WeappMcpConfig`

其中 `WeappMcpConfig` 为：

```ts
{
  enabled?: boolean
  autoStart?: boolean
  host?: string
  port?: number
  endpoint?: string
  restEndpoint?: string | false
}
```

用于控制本地 MCP 服务。`streamable-http` 模式会同时暴露 DevTools runtime REST 接口，默认
`restEndpoint` 为 `/api/weapp/devtools`；设为 `false` 可关闭。

```ts
export default defineConfig({
  weapp: {
    mcp: {
      enabled: true,
      autoStart: true,
      host: '127.0.0.1',
      port: 8099,
      endpoint: '/mcp',
      restEndpoint: '/api/weapp/devtools',
    },
  },
})
```

常见用途：

* AI 直接接管小程序打开、截图、截图对比、日志读取
* 本地协作工具调用 weapp-vite 提供的能力入口

如果你正在做 AI 亲和性增强，这一组配置通常和下面这些能力一起使用：

* `forwardConsole`
* `appPrelude.webRuntime`
* 自动截图
* 截图对比
* `wv prepare`

> \[!TIP]
> `app.prelude` 配置请看 [App Prelude 配置](./app-prelude.md)，`appPrelude.webRuntime` 配置请看 [Web Runtime 全局对象注入配置](./web-runtime-globals.md)。

## 这页和 Vite 原生配置的边界

以下字段不在这页定义，但经常会一起配：

* `server.host`
* `server.port`
* `define`
* `plugins`

这些仍然属于 Vite 顶层配置，请直接参考：

* [Vite 中文官方配置文档](https://cn.vite.dev/config/)

***

如果你下一步想继续接自动导入组件，请看 [自动导入组件配置](./auto-import-components.md)。如果你要处理 layout，则继续看 [Route Rules 与 Layout](./route-rules.md)。

---

---
url: /config/app-prelude.md
description: weapp.appPrelude 的配置说明，覆盖 app.prelude 前置脚本开关、注入模式与产物行为。
---

# App Prelude 配置 {#app-prelude-config}

这一页介绍 `weapp.appPrelude` 的配置。它控制 `src/app.prelude.ts` 或 `src/app.prelude.js` 的注入方式。

如果你想先理解这个功能解决什么问题，请看 [App Prelude](/guide/app-prelude)。

\[\[toc]]

## `weapp.appPrelude` {#weapp-appprelude}

* **类型**：

```ts
boolean | {
  enabled?: boolean
  mode?: 'inline' | 'entry' | 'require'
  webRuntime?: boolean | WeappWebRuntimeConfig
}
```

* **默认值**：`{ mode: 'require' }`

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

export default defineConfig({
  weapp: {
    appPrelude: {
      enabled: true,
      mode: 'require',
    },
  },
})
```

### `enabled`

* **类型**：`boolean`

是否启用 `app.prelude` 注入。设置为 `false` 后，即使源码目录下存在 `app.prelude.ts` 或 `app.prelude.js`，也不会注入。

### `mode`

* **类型**：`'inline' | 'entry' | 'require'`
* **默认值**：`'require'`

| 值 | 行为 | 适合场景 |
| --- | --- | --- |
| `inline` | 把 prelude 代码内联到目标 JS chunk 顶部 | 追求最早执行时机，可以接受重复代码 |
| `entry` | 只注入到 `app`、页面、组件入口 chunk | 希望控制注入范围 |
| `require` | 生成作用域级 `app.prelude.js`，再在 chunk 顶部静态 `require` | 默认推荐，兼顾执行时机和产物体积 |

`require` 模式下，主包、普通分包和独立分包会各自拿到对应作用域的 `app.prelude.js`。

> \[!NOTE]
> `app.prelude` 当前仅支持无 `import` / `export` 的自包含脚本。

## 产物说明

启用 `appPrelude` 后，构建产物中可能出现：

| 产物 | 说明 |
| --- | --- |
| `app.prelude.js` | `require` 模式下按作用域生成的前置脚本 |
| 入口 JS 顶部的 `require(...)` | 用于提前执行对应作用域的 `app.prelude.js` |

## 常见配置

### 使用默认注入模式

```ts
export default defineConfig({
  weapp: {
    appPrelude: {
      mode: 'require',
    },
  },
})
```

### 关闭前置脚本注入

```ts
export default defineConfig({
  weapp: {
    appPrelude: {
      enabled: false,
    },
  },
})
```

## 继续阅读

* [App Prelude](/guide/app-prelude)
* [Web Runtime 全局对象注入配置](/config/web-runtime-globals)
* [共享配置](/config/shared)

---

---
url: /config/web-runtime-globals.md
description: weapp.appPrelude.webRuntime 的配置说明，覆盖 Web Runtime 全局对象注入、目标对象、依赖匹配与网络默认参数。
---

# Web Runtime 全局对象注入配置 {#web-runtime-globals-config}

这一页介绍 `weapp.appPrelude.webRuntime` 的配置。它在 `appPrelude` 时机安装 Web Runtime 全局对象，并保留 chunk 级局部绑定兜底。

如果你想先理解这个功能解决什么问题，请看 [Web Runtime 全局对象注入](/guide/web-runtime-globals)。

\[\[toc]]

## `weapp.appPrelude.webRuntime` {#weapp-appprelude-webruntime}

* **类型**：

```ts
boolean | {
  enabled?: boolean
  targets?: WeappInjectWebRuntimeGlobalsTarget[]
  dependencies?: (string | RegExp)[]
  networkDefaults?: MiniProgramNetworkDefaults
}
```

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

export default defineConfig({
  weapp: {
    appPrelude: {
      mode: 'require',
      webRuntime: {
        enabled: true,
        targets: ['fetch', 'Headers', 'Request', 'Response', 'XMLHttpRequest'],
        dependencies: [/^axios$/, /^graphql-request$/],
        networkDefaults: {
          request: {
            timeout: 10000,
          },
          socket: {
            timeout: 10000,
          },
        },
      },
    },
  },
})
```

### `enabled`

* **类型**：`boolean`

显式启用或关闭 Web Runtime 全局对象注入。

当 `webRuntime: true` 时，等价于使用默认目标集合启用注入。

### `targets`

* **类型**：`WeappInjectWebRuntimeGlobalsTarget[]`

可选值包括：

| 目标 | 说明 |
| --- | --- |
| `fetch` / `Headers` / `Request` / `Response` | Fetch 请求相关对象 |
| `XMLHttpRequest` | 兼容 axios 等 XHR 路径 |
| `WebSocket` | 兼容 WebSocket 风格客户端 |
| `AbortController` / `AbortSignal` | 请求取消相关对象 |
| `TextEncoder` / `TextDecoder` | 请求体、响应体和二进制处理 |
| `atob` / `btoa` | Base64 编解码 |
| `queueMicrotask` | 微任务调度 |
| `performance` / `crypto` | 常见 Web API |
| `Event` / `CustomEvent` | 事件构造器 |

当请求类目标启用时，构建器还会为 `URL`、`URLSearchParams`、`Blob`、`FormData` 等依赖对象补充局部绑定。

### `dependencies`

* **类型**：`(string | RegExp)[]`

自动模式下用于匹配项目依赖。匹配到相关依赖后，`weapp-vite` 会按规则启用对应目标。

默认会关注：

* `axios`
* `graphql-request`
* `socket.io-client`
* `engine.io-client`
* `@tanstack/query-core`
* `@tanstack/vue-query`

### `networkDefaults`

* **类型**：`MiniProgramNetworkDefaults`

传给 Web Runtime 网络兼容层的宿主默认参数，会作用到 `fetch`、`XMLHttpRequest`、`WebSocket` 对应的小程序底层能力。

显式调用时传入的 `miniProgram` 或 `miniprogram` 参数优先级更高。

## 产物说明

启用 `appPrelude.webRuntime` 后，构建产物中可能出现：

| 产物 | 说明 |
| --- | --- |
| `app.prelude.js` | `require` 模式下按作用域生成的前置脚本 |
| `weapp-vendors/request-globals-web-apis-shared.js` | Web Runtime 全局对象 installer 共享模块 |
| 入口 JS 顶部的 `require(...)` | 用于提前执行对应作用域的 `app.prelude.js` |

## 常见配置

### 只启用默认注入

```ts
export default defineConfig({
  weapp: {
    appPrelude: {
      webRuntime: true,
    },
  },
})
```

### 仅兼容 axios / graphql-request 请求链路

```ts
export default defineConfig({
  weapp: {
    appPrelude: {
      webRuntime: {
        enabled: true,
        targets: [
          'fetch',
          'Headers',
          'Request',
          'Response',
          'AbortController',
          'AbortSignal',
          'XMLHttpRequest',
        ],
        dependencies: [/^axios$/, /^graphql-request$/],
      },
    },
  },
})
```

## 继续阅读

* [Web Runtime 全局对象注入](/guide/web-runtime-globals)
* [App Prelude 配置](/config/app-prelude)
* [Web 运行时配置](/config/web)

---

---
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: /config/chunks.md
description: weapp.chunks 用于控制共享模块在主包、普通分包中的输出位置与输出形态。这是分包优化里最关键的一组配置。
---

# 共享 Chunk 配置 {#chunks-config}

`weapp.chunks` 用于控制 **复用模块最终如何落盘**。

它主要解决三类问题：

* 跨分包复用的代码，到底要放到主包还是复制到各分包；
* 共享代码到底要输出成 `common.js`，还是保留更稳定的路径结构；
* 动态 `import()`、局部目录、历史模块，是否要使用不同的共享策略。

如果你在做分包体积优化、首开性能优化、`common.js` 治理，或者排查“为什么模块被提到主包了 / 为什么某个分包多出共享代码了”，优先看这页。

如果你想先理解运行时背景和整体产物分发模型，再看 [分包指南](/guide/subpackage) 与 [共享 Chunk 策略指南](/guide/chunks)。

\[\[toc]]

## `weapp.chunks` {#weapp-chunks}

* **类型**：
  ```ts
  {
    sharedStrategy?: 'duplicate' | 'hoist'
    sharedMode?: 'common' | 'path' | 'inline'
    sharedOverrides?: Array<{
      test: string | RegExp
      mode: 'common' | 'path' | 'inline'
    }>
    sharedPathRoot?: string
    dynamicImports?: 'preserve' | 'inline'
    logOptimization?: boolean
    forceDuplicatePatterns?: Array<string | RegExp>
    duplicateWarningBytes?: number
  }
  ```
* **默认值**：
  ```ts
  {
    sharedStrategy: 'duplicate',
    sharedMode: 'common',
    dynamicImports: 'preserve',
    logOptimization: true
  }
  ```

### 基础示例

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

export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'common',
      dynamicImports: 'preserve',
      logOptimization: true,
      duplicateWarningBytes: 768 * 1024,
    },
  },
})
```

## 先记住这个判断模型

可以把 `weapp.chunks` 理解成两层：

* `sharedStrategy` 决定“共享模块放在哪”
* `sharedMode` 决定“共享模块长什么样”

也就是说：

* 你在纠结“主包 vs 分包”时，先看 `sharedStrategy`
* 你在纠结“common.js vs 保持路径 vs 不生成共享 chunk”时，先看 `sharedMode`

## `sharedStrategy`

* **类型**：`'duplicate' | 'hoist'`
* **默认值**：`'duplicate'`
* **作用**：决定跨普通分包共享模块，优先复制到各分包，还是统一提升到主包。

### `duplicate`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
    },
  },
})
```

含义：

* 某模块被多个普通分包复用时，优先复制到各自分包；
* 这样分包首开时更不依赖主包共享产物；
* 代价是可能带来重复体积。

适合：

* 分包首开性能优先；
* 业务域隔离较强，希望每个分包尽量自给自足；
* 你不希望某个公共依赖频繁被提升到主包。

### `hoist`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'hoist',
    },
  },
})
```

含义：

* 多个普通分包复用的模块会统一提升到主包；
* 这样总包体更容易去重；
* 代价是分包运行时更依赖主包里的共享代码。

适合：

* 包体去重优先；
* 共享依赖很多，复制后冗余明显；
* 团队更希望集中管理主包的公共产物。

### 怎么选

* 更看重首开体验：先用 `duplicate`
* 更看重总体积：先用 `hoist`
* 不确定时：先保留默认 `duplicate`，再结合 `duplicateWarningBytes` 和构建日志评估

> \[!TIP]
> 这里说的“共享模块”主要指 **多个普通分包之间复用、且可被共享策略处理的模块**。独立分包不参与这套共享分发。

## `sharedMode`

* **类型**：`'common' | 'path' | 'inline'`
* **默认值**：`'common'`
* **作用**：决定共享模块最终的输出形态。

### `common`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'common',
    },
  },
})
```

含义：

* 共享模块会汇总为 `common.js` 一类共享产物；
* 入口会自动改写引用，指向这些共享文件；
* 这是最容易理解、最接近传统小程序分包共享思路的模式。

适合：

* 团队希望共享逻辑直观可见；
* 你能接受 `common.js` 的存在；
* 你想用最稳妥、最通用的共享形态。

### `path`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'path',
      sharedPathRoot: 'src',
    },
  },
})
```

含义：

* 共享模块按源码相对路径输出；
* 不再强制汇总为单一 `common.js`；
* 更适合希望产物路径稳定、可读、便于排查的项目。

适合：

* 你想弱化 `common.js`；
* 你希望共享模块产物能更容易对应回源码目录；
* 团队需要更稳定的构建输出路径做审计或比对。

### `inline`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'inline',
    },
  },
})
```

含义：

* 共享模块会尽量内联到引用方；
* 不再额外生成共享 chunk；
* 适合极度强调“不要共享产物文件”的场景。

适合：

* 你明确不想要共享 chunk；
* 共享模块很小，但产物拆分过多；
* 某些历史项目对额外 chunk 路径较敏感。

> \[!WARNING]
> `inline` 会减少共享产物文件，但通常会增加重复代码。它不是默认推荐解，只适合你明确知道自己在规避什么问题时使用。

## `sharedOverrides`

* **类型**：`Array<{ test: string | RegExp; mode: 'common' | 'path' | 'inline' }>`
* **默认值**：`undefined`
* **作用**：为特定模块或目录覆盖 `sharedMode`。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'common',
      sharedOverrides: [
        { test: 'components/**', mode: 'path' },
        { test: /legacy\//, mode: 'inline' },
      ],
    },
  },
})
```

说明：

* `test` 支持 glob 字符串或正则；
* 匹配时会基于 `srcRoot` 相对路径或模块绝对路径判断；
* 适合“全局用一种模式，少数目录例外”的项目。

常见用途：

* 把公共组件目录改成 `path`，方便定位真实产物；
* 把历史兼容目录改成 `inline`，避免额外共享文件；
* 主体继续使用 `common`，只对局部做精细治理。

## `sharedPathRoot`

* **类型**：`string`
* **默认值**：未显式配置时使用 `srcRoot`
* **作用**：当 `sharedMode: 'path'` 时，用它来计算“按路径输出”的根目录。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'path',
      sharedPathRoot: 'src/shared',
    },
  },
})
```

建议：

* 希望产物更贴近源码结构时，通常设置为 `src` 或更具体的公共目录；
* 若配置的目录不在 `srcRoot` 内，构建会自动回退到 `srcRoot`。

## `dynamicImports`

* **类型**：`'preserve' | 'inline'`
* **默认值**：`'preserve'`
* **作用**：控制动态 `import()` 产物是否保留独立 chunk。

### `preserve`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      dynamicImports: 'preserve',
    },
  },
})
```

含义：

* 保留独立动态 chunk；
* 更符合按需加载的预期；
* 也是默认推荐值。

### `inline`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      dynamicImports: 'inline',
    },
  },
})
```

含义：

* 尽量减少动态 import 生成的额外 chunk；
* 适合想压缩 chunk 数量的项目；
* 但可能牺牲按需加载边界。

## `logOptimization`

* **类型**：`boolean`
* **默认值**：`true`
* **作用**：在构建日志中输出共享模块的复制、回退、提升等信息。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      logOptimization: true,
    },
  },
})
```

建议：

* 本地调优分包策略时保持开启；
* CI 如果日志噪声太大，再考虑关闭；
* 当你怀疑配置没生效时，先检查这里输出了什么。

## `forceDuplicatePatterns`

* **类型**：`Array<string | RegExp>`
* **默认值**：`undefined`
* **作用**：即使某些共享模块看起来被主包引用，只要其直接导入方命中规则，仍强制按 `duplicate` 方向复制到分包。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      forceDuplicatePatterns: ['action/**', /services\//],
    },
  },
})
```

适合：

* 导入图中存在“伪主包引用”；
* 某些业务目录你明确希望它永远跟随分包走；
* 你想阻止这些模块被意外提升到主包。

## `duplicateWarningBytes`

* **类型**：`number`
* **默认值**：`0`
* **作用**：当 `duplicate` 带来的冗余体积超过阈值时给出警告。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      duplicateWarningBytes: 768 * 1024,
    },
  },
})
```

建议：

* 团队开始治理分包冗余时，把它设成一个明确阈值；
* 小项目可以先不设；
* 设置为 `0` 或 `undefined` 可关闭提醒。

## 常见组合

### 组合 1：默认推荐基线

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'common',
      dynamicImports: 'preserve',
      logOptimization: true,
    },
  },
})
```

适合大多数普通分包项目，先保证共享逻辑稳定，再观察构建日志和体积。

### 组合 2：减少主包依赖，同时不想只看到 `common.js`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'path',
      sharedPathRoot: 'src',
    },
  },
})
```

适合想保留分包自给自足，同时提升产物可读性的项目。

### 组合 3：总体积优先

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'hoist',
      sharedMode: 'common',
      duplicateWarningBytes: 512 * 1024,
    },
  },
})
```

适合共享依赖多、复制成本高的项目。

### 组合 4：主体稳定，局部定向治理

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'common',
      sharedOverrides: [
        { test: 'components/**', mode: 'path' },
        { test: /legacy\//, mode: 'inline' },
      ],
    },
  },
})
```

适合已有存量项目渐进式优化，而不是一次性全局切换。

## 选型建议

* 先解决“共享模块落位”，再解决“共享模块形态”。
* 除非你明确要规避 `common.js`，否则优先从 `sharedMode: 'common'` 开始。
* 除非你明确更在意总体积，否则优先从 `sharedStrategy: 'duplicate'` 开始。
* 当团队开始争论“为什么这个模块进主包了”，先开 `logOptimization`，再考虑 `forceDuplicatePatterns`。
* 当项目越来越大时，把 `duplicateWarningBytes` 设成团队统一阈值，而不是纯靠人工观察。

## 常见误区

### 误区 1：只改 `sharedMode`，不看 `sharedStrategy`

`sharedMode` 决定的是“产物长什么样”，不是“产物放哪”。如果你想解决的是“为什么又回到主包了”，重点不在 `sharedMode`，而在 `sharedStrategy` 和真实导入图。

### 误区 2：把 `inline` 当成通用优化手段

`inline` 只是减少共享文件数量，不代表整体更优。很多时候它会增加重复体积，只适合有明确约束时使用。

### 误区 3：忽略独立分包的隔离语义

`weapp.chunks` 主要面向主包和普通分包之间的共享治理。独立分包是独立构建上下文，不要期待它复用普通分包的共享产物。

## 关联阅读

* [共享 Chunk 策略指南](/guide/chunks)
* [分包指南](/guide/subpackage)
* [分包配置](/config/subpackages.md)
* [库模式配置](/config/lib.md)

---

---
url: /config/npm.md
description: weapp-vite 会把运行时依赖构建到小程序 npm 目录，并允许你按主包、插件、分包精细控制依赖落位、缓存与底层构建参数。
---

# npm 配置 {#config-npm}

`weapp-vite` 内建了“小程序 npm 依赖落位”能力。它不仅仅是“把依赖打进 `miniprogram_npm`”，还允许你精细控制：

* 主包放哪些依赖
* 插件产物放哪些依赖
* 哪些依赖下沉到特定分包
* 单个 npm 包构建时用什么底层 Vite 配置

\[\[toc]]

## 默认依赖分类规则

默认情况下：

* `dependencies` 与 `devDependencies` 都优先进入 Vite 的正常打包流程
* 只有“明确的小程序包”或你显式指定的包，才会进入小程序 npm 构建

这里的“明确的小程序包”通常指包自身带有 `miniprogram` 字段，例如：

* `tdesign-miniprogram`
* `@vant/weapp`

如果你仍想沿用旧规则，也可以切回 `legacy` 模式，让根 `package.json.dependencies` 默认进入 `miniprogram_npm`。

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

* **类型**：
  ```ts
  {
    enable?: boolean
    cache?: boolean
    strategy?: 'explicit' | 'legacy'
    include?: (string | RegExp)[]
    mainPackage?: {
      dependencies?: false | (string | RegExp)[]
    }
    pluginPackage?: {
      dependencies?: false | (string | RegExp)[]
    }
    subPackages?: Record<string, {
      dependencies?: (string | RegExp)[]
    }>
    buildOptions?: (options: NpmBuildOptions, pkgMeta: BuildNpmPackageMeta) => NpmBuildOptions | undefined
    alipayNpmMode?: 'miniprogram_npm' | 'node_modules'
  }
  ```

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

export default defineConfig({
  weapp: {
    npm: {
      enable: true,
      cache: true,
      strategy: 'explicit',
      include: ['dayjs'],
      mainPackage: {
        dependencies: false,
      },
      pluginPackage: {
        dependencies: ['dayjs'],
      },
      subPackages: {
        'packages/order': {
          dependencies: [/^tdesign-miniprogram/, 'dayjs'],
        },
      },
      buildOptions(options, { name }) {
        if (name === 'dayjs') {
          return {
            ...options,
            build: {
              ...options.build,
              minify: false,
              sourcemap: true,
            },
          }
        }
        return options
      },
      alipayNpmMode: 'node_modules',
    },
  },
})
```

## 字段说明

### `enable`

* **类型**：`boolean`

是否启用内建 npm 构建。

关闭后：

* `weapp-vite` 不再自动构建小程序 npm 目录
* 若源码里仍保留 `require('pkg')` / 包路径引用，则需要你自己处理，例如改为开发者工具手动构建 npm

### `cache`

* **类型**：`boolean`

是否启用 npm 构建缓存。

默认缓存目录：

* `node_modules/weapp-vite/.cache/`

适用建议：

* 日常开发保留 `true`
* 如果怀疑 npm 构建结果陈旧，再临时设 `false` 或手动清缓存

### `strategy`

* **类型**：`'explicit' | 'legacy'`

控制 npm 构建候选集的默认分类方式。

行为：

* `explicit`：默认值。`dependencies` / `devDependencies` 都先按普通依赖走 Vite 打包；只有小程序包或显式命中的包才进入 npm 构建
* `legacy`：兼容旧行为。根 `package.json.dependencies` 默认作为 npm 构建候选

### `include`

* **类型**：`(string | RegExp)[] | undefined`

额外指定哪些包要进入 npm 构建候选集。

说明：

* 字符串命中包名时，也会覆盖其子路径导入
* `include` 只决定“哪些包进入 npm 构建”
* 最终落到主包 / 插件 / 分包，仍由下面的 `mainPackage.dependencies`、`pluginPackage.dependencies`、`subPackages` 决定

### `mainPackage.dependencies`

* **类型**：`false | (string | RegExp)[] | undefined`

控制主包里的 npm 依赖范围。

行为：

* `undefined`：默认按当前 npm 候选集处理
* `false`：不输出主包 npm 目录
* 数组：只输出命中的依赖

### `pluginPackage.dependencies`

* **类型**：`false | (string | RegExp)[] | undefined`

控制插件产物里的 npm 依赖范围。

仅在以下前提下有意义：

* 配置了 `weapp.pluginRoot`
* 当前走到了插件构建链路

### `subPackages`

* **类型**：`Record<string, { dependencies?: (string | RegExp)[] }>`

控制特定分包内的 npm 依赖落位。

适合：

* 把只在某个分包使用的依赖下沉到该分包
* 减少主包体积

### `buildOptions`

* **类型**：`(options, pkgMeta) => options | undefined`

允许你在“构建单个 npm 包”的那一层覆写底层 Vite 配置。

常见场景：

* 给个别依赖关闭压缩
* 给个别依赖开启 sourcemap
* 调整构建 target

> \[!TIP]
> 这里操作的是“npm 包内部构建用的 Vite 配置对象”。若你需要理解其中 `build.*` 字段的完整语义，请直接看 [Vite 中文官方配置文档](https://cn.vite.dev/config/)。

### `alipayNpmMode`

* **类型**：`'miniprogram_npm' | 'node_modules'`

用于控制支付宝平台的本地 npm 输出目录风格。

默认是：

* `node_modules`

如果你的历史链路或团队约定需要走微信风格目录，可切到：

* `miniprogram_npm`

## 常见落位策略

### 主包尽量瘦身

```ts
export default defineConfig({
  weapp: {
    npm: {
      mainPackage: {
        dependencies: false,
      },
      subPackages: {
        'packages/order': {
          dependencies: ['dayjs'],
        },
      },
    },
  },
})
```

适合把明确只在分包用到的依赖下沉出去。

### 默认内联，仅指定包进入 npm 构建

```ts
export default defineConfig({
  weapp: {
    npm: {
      include: ['dayjs'],
      subPackages: {
        'packages/order': {
          dependencies: ['dayjs'],
        },
      },
    },
  },
})
```

适合让普通依赖默认内联，只有指定包进入 `miniprogram_npm`。

### 插件单独携带 npm

```ts
export default defineConfig({
  weapp: {
    srcRoot: 'miniprogram',
    pluginRoot: 'plugin',
    npm: {
      pluginPackage: {
        dependencies: ['dayjs'],
      },
      mainPackage: {
        dependencies: false,
      },
    },
  },
})
```

适合主应用和插件同仓维护，但只希望插件产物包含指定 npm 包。

## 与顶层 `build.*` 的边界

顶层 Vite `build.*` 影响的是主项目构建。

`weapp.npm.buildOptions` 影响的是：

* 小程序 npm 依赖包自己的内部构建

两者不要混淆。

更多原生字段请看：

* [Vite 中文官方配置文档 · build](https://cn.vite.dev/config/build-options)

## 常见问题

### npm 构建内容没更新

优先尝试：

1. 把 `cache` 设为 `false`
2. 清理 `node_modules/weapp-vite/.cache/`
3. 重新构建

### 分包体积过大

优先检查：

* `mainPackage.dependencies`
* `subPackages.<root>.dependencies`

### 为什么 `dependencies` 里的包没有自动进入 `miniprogram_npm`？

因为默认 `strategy` 是 `explicit`：

* 普通依赖会优先被 Vite 内联打包
* 只有小程序包或 `npm.include` / `mainPackage.dependencies` / `pluginPackage.dependencies` / `subPackages.<root>.dependencies` 显式命中的包，才会进入 npm 构建

如果你要恢复旧行为，请改成：

```ts
export default defineConfig({
  weapp: {
    npm: {
      strategy: 'legacy',
    },
  },
})
```

### 支付宝平台目录不符合预期

优先检查：

* `weapp.platform`
* `weapp.npm.alipayNpmMode`

***

如果你继续处理分包边界，请回看 [分包配置](./subpackages.md)。如果你要处理库模式，则继续看 [库模式配置](./lib.md)。

---

---
url: /config/lib.md
description: weapp-vite 的 lib 模式用于构建小程序组件库或业务模块库，支持多入口、路径保持、组件 JSON 生成与 DTS 输出。
---

# 库模式配置 {#lib-config}

`weapp.lib` 用于把项目切换到“小程序库模式”。

启用后，`weapp-vite` 不再按应用模式去生成 `app.json`、页面路由和整套应用产物，而是只围绕你声明的入口输出：

* 组件
* 业务模块
* 类型文件

\[\[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 | WeappLibDtsOptions
  }
  ```

```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`

* **类型**：`string | string[] | Record<string, string>`

必填。支持：

* 单入口
* 多入口数组
* 具名入口对象

### `root`

* **类型**：`string`

库源码根目录。默认沿用 `weapp.srcRoot`。

### `outDir`

* **类型**：`string`

库产物输出目录。默认沿用顶层 `build.outDir`。

### `preservePath`

* **类型**：`boolean`

是否保留源码相对路径。默认一般更适合组件库场景。

### `fileName`

* **类型**：`string | ((ctx) => string)`

自定义入口输出文件名或路径。

适合：

* 统一输出成 `${name}/index`
* 精确控制多入口发布目录结构

### `componentJson`

* **类型**：`boolean | 'auto' | ((ctx) => Record<string, any>)`

控制是否自动生成组件 JSON。

行为建议：

* `false`：完全手动维护
* `true`：始终生成
* `'auto'`：缺少 JSON 且看起来像组件入口时自动生成
* `function`：按入口动态返回 JSON 内容

## `weapp.lib.dts` {#weapp-lib-dts}

* **类型**：`boolean | WeappLibDtsOptions`

用于控制声明文件输出。

`WeappLibDtsOptions` 主要包括：

```ts
{
  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>
  }
}
```

示例：

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: ['components/button/index.vue'],
      dts: {
        mode: 'vue-tsc',
        vueTsc: {
          compilerOptions: {
            declarationMap: true,
          },
        },
      },
    },
  },
})
```

### `mode` 怎么选

* `internal`：默认模式，成本更低，适合大多数场景
* `vue-tsc`：更贴近 Vue 生态类型链路，适合你明确依赖 `vue-tsc` 行为时使用

## 常见组合

### 保留源码路径

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: ['components/button/index.vue'],
      preservePath: true,
    },
  },
})
```

适合源目录结构本身就想作为发布结构保留。

### 统一输出成 `[name]/index`

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: {
        button: 'components/button/index.vue',
        card: 'components/card/index.vue',
      },
      preservePath: false,
      fileName: ({ name }) => `${name}/index`,
    },
  },
})
```

适合构建稳定、统一的发布目录。

## 与顶层 `build.*` 的边界

`weapp.lib` 负责的是“进入库模式以及小程序库语义”。

但这些底层构建项仍然属于 Vite / Rolldown 顶层配置：

* `build.rolldownOptions.external`
* `build.target`
* `build.minify`
* `build.sourcemap`

例如发布 npm 组件库时 external 掉 `wevu`：

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: ['components/button/index.vue'],
    },
  },
  build: {
    rolldownOptions: {
      external: [/^wevu(?:\\/.*)?$/],
    },
  },
})
```

更多原生字段说明请看：

* [Vite 中文官方配置文档 · build](https://cn.vite.dev/config/build-options)

## 常见问题

### 为什么多入口产物互相覆盖

优先检查：

* `preservePath`
* `fileName`

是否把多个入口映射到了同一个输出路径。

### `componentJson: 'auto'` 没生成 JSON

说明当前入口没有被识别成“适合自动生成组件 JSON”的组件入口。此时改成：

* `true`
* 或函数形式显式返回 JSON

### 库模式还能用共享 chunk 吗

可以。多入口共享模块时，仍然会受到 [共享 Chunk 配置](./chunks.md) 的影响。

***

如果你要继续处理顶层生成参数，请看 [Vite 中文官方配置文档](https://cn.vite.dev/config/)。如果你接下来要做代码生成骨架，请继续看 [生成脚手架配置](./generate.md)。

---

---
url: /config/generate.md
description: >-
  Weapp-vite generate 用于快速生成页面、组件和 App 基础文件。本页列出 weapp.generate
  的字段，方便你把生成目录、文件名、后缀和模板内容对齐到团队习惯。**这些配置仅影响 CLI 生成器，不影响构建流程…
---

# 生成脚手架配置 {#generate-config}

`wv 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 wv g src/components/Avatar
pnpm wv g src/pages/home -p
pnpm wv g src -a
```

* **CLI 会覆盖已有文件吗？** 不会，生成命令只对全新文件生效，若目标文件已存在会提示冲突。
* **如何生成带注释的 JSON？** 把 `extensions.json` 设为 `jsonc` 即可，然后在模板里写注释/占位内容。
* **模板如何复用？** 用 `templates.shared` 提供全局基础模板，再在 `component`、`page`、`app` 里按需覆写。

***

接下来，可结合 [基础目录与资源收集](./paths.md#paths-config) 调整生成目标目录，或阅读 [共享配置](/config/shared.md) 在生成后自动注册组件与路由。

---

---
url: /config/web.md
description: weapp-vite 可选集成浏览器端运行时 @weapp-vite/web，用于预览、兼容验证、截图联调与 AI 调试。
---

# Web 运行时配置 experimental {#web-config}

`weapp.web` 用于接入浏览器端运行时（`@weapp-vite/web`），让你在 Web 环境里做这些事：

* 快速预览页面结构和样式
* 调试模板编译与运行时表达式
* 做兼容验证
* 在 AI 联调、截图、截图对比前先跑一轮浏览器链路

> \[!WARNING]
> `weapp.web` 仍是实验能力。它适合开发和调试，不应作为小程序真机或 DevTools 验收的唯一依据。

\[\[toc]]

## `weapp.web` {#weapp-web}

* **类型**：
  ```ts
  {
    enable?: boolean
    root?: string
    srcDir?: string
    outDir?: string
    pluginOptions?: Partial<Omit<WeappWebPluginOptions, 'srcDir'>>
    vite?: InlineConfig
  }
  ```

```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,
          port: 5173,
        },
      },
    },
  },
})
```

## 字段说明

### `enable`

* **类型**：`boolean`

控制是否启用 Web 运行时。

通常只要配置了 `weapp.web` 且 `enable !== false`，它就会生效。

### `root`

* **类型**：`string`

Web 项目根目录，通常是 `index.html` 所在目录。

### `srcDir`

* **类型**：`string`

Web 运行时侧使用的小程序源码目录。默认会尽量与 `weapp.srcRoot` 保持一致。

### `outDir`

* **类型**：`string`

Web 产物输出目录，默认一般是 `dist/web`。

### `pluginOptions`

* **类型**：`Partial<Omit<WeappWebPluginOptions, 'srcDir'>>`

透传给 `@weapp-vite/web` 插件层。

常见字段包括：

* `wxss`
* `form`
* `runtime`

其中比较关键的是：

* `runtime.executionMode`
  * `compat`
  * `safe`
  * `strict`
* `runtime.warnings.level`
  * `warn`
  * `error`
  * `off`
* `runtime.warnings.dedupe`

### `vite`

* **类型**：`InlineConfig`

允许你给 Web 运行时单独合并一份 Vite 配置。

常见场景：

* 单独配 Web 的 `server.port`
* 单独配 `resolve.alias`
* 单独加浏览器调试插件

> \[!TIP]
> `weapp.web.vite` 里的字段完全遵循 Vite 原生语义。完整说明请看 [Vite 中文官方配置文档](https://cn.vite.dev/config/)。

## 什么时候适合开启

* 你想更快观察模板和交互，而不是每次都回到开发者工具
* 你在做 AI 联调，希望把“截图前的预检”搬到浏览器环境
* 你在查兼容问题，想先缩小到“编译问题”还是“平台问题”

## 和截图 / AI 联调的关系

如果你的目标是增强 AI 对项目的可操作性，`weapp.web` 很适合当第一层调试面：

* 先在 Web 侧打开页面
* 再配合浏览器截图或截图对比能力做快速回归
* 最后再回 DevTools / 真机验证平台差异

这能显著减少“每次截图都必须依赖小程序 IDE”的成本。

## 与 Vite 顶层配置的边界

这组配置只描述“Web 运行时这条附加链路”。

如果你要配置这些原生字段：

* `server`
* `resolve`
* `plugins`
* `css`
* `build`

请直接参考：

* [Vite 中文官方配置文档](https://cn.vite.dev/config/)

***

如果你接下来要处理截图联调、MCP、日志桥接，请回看 [共享配置](./shared.md)。如果你要处理多入口发布，则继续看 [库模式配置](./lib.md)。

---

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


---

---
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: /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

## 覆盖结论

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

## 不兼容规模

* 支付宝侧不兼容（按小程序基准命名调用失败）方法：283
* 抖音侧不兼容（按小程序基准命名调用失败）方法：351

## 不兼容示例（前 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）
* `checkIsSupportFacialRecognition` -> 目标 `checkIsSupportFacialRecognition`（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）

### 抖音不兼容示例

* `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）
* `checkIsSupportFacialRecognition` -> 目标 `checkIsSupportFacialRecognition`（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）

---

---
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/base.md
description: '@wevu/api 的 API 全量清单页，聚焦基础能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 基础

---

---
url: /packages/weapi/wx-method-list/route.md
description: '@wevu/api 的 API 全量清单页，聚焦路由能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 路由

---

---
url: /packages/weapi/wx-method-list/navigate.md
description: '@wevu/api 的 API 全量清单页，聚焦跳转能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 跳转

---

---
url: /packages/weapi/wx-method-list/chattool.md
description: '@wevu/api 的 API 全量清单页，聚焦聊天工具能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 聊天工具

---

---
url: /packages/weapi/wx-method-list/share.md
description: '@wevu/api 的 API 全量清单页，聚焦转发能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 转发

---

---
url: /packages/weapi/wx-method-list/ui.md
description: '@wevu/api 的 API 全量清单页，聚焦界面能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 界面

---

---
url: /packages/weapi/wx-method-list/network.md
description: '@wevu/api 的 API 全量清单页，聚焦网络能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 网络

---

---
url: /packages/weapi/wx-method-list/payment.md
description: '@wevu/api 的 API 全量清单页，聚焦支付能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 支付

---

---
url: /packages/weapi/wx-method-list/storage.md
description: '@wevu/api 的 API 全量清单页，聚焦数据缓存能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 数据缓存

---

---
url: /packages/weapi/wx-method-list/data-analysis.md
description: '@wevu/api 的 API 全量清单页，聚焦数据分析能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 数据分析

---

---
url: /packages/weapi/wx-method-list/canvas.md
description: '@wevu/api 的 API 全量清单页，聚焦画布能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 画布

---

---
url: /packages/weapi/wx-method-list/media.md
description: '@wevu/api 的 API 全量清单页，聚焦媒体能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 媒体

---

---
url: /packages/weapi/wx-method-list/location.md
description: '@wevu/api 的 API 全量清单页，聚焦位置能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 位置

---

---
url: /packages/weapi/wx-method-list/file.md
description: '@wevu/api 的 API 全量清单页，聚焦文件能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 文件

---

---
url: /packages/weapi/wx-method-list/open-api.md
description: '@wevu/api 的 API 全量清单页，聚焦开放接口能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 开放接口

---

---
url: /packages/weapi/wx-method-list/device.md
description: '@wevu/api 的 API 全量清单页，聚焦设备能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 设备

---

---
url: /packages/weapi/wx-method-list/ai.md
description: '@wevu/api 的 API 全量清单页，聚焦AI能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · AI

---

---
url: /packages/weapi/wx-method-list/worker.md
description: '@wevu/api 的 API 全量清单页，聚焦Worker能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · Worker

---

---
url: /packages/weapi/wx-method-list/wxml.md
description: '@wevu/api 的 API 全量清单页，聚焦WXML能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · WXML

---

---
url: /packages/weapi/wx-method-list/ext.md
description: '@wevu/api 的 API 全量清单页，聚焦第三方平台能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

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

---

---
url: /packages/weapi/wx-method-list/ad.md
description: '@wevu/api 的 API 全量清单页，聚焦广告能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · 广告

---

---
url: /packages/weapi/wx-method-list/xr-frame.md
description: '@wevu/api 的 API 全量清单页，聚焦XR-FRAME能力分类，便于快速检索微信小程序相关接口与组件 API。'
---

# API 全量清单 · XR-FRAME

---

---
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/base.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦基础能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 基础

---

---
url: /packages/weapi/alipay-compat-matrix/route.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦路由能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 路由

---

---
url: /packages/weapi/alipay-compat-matrix/navigate.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦跳转能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 跳转

---

---
url: /packages/weapi/alipay-compat-matrix/chattool.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦聊天工具能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 聊天工具

---

---
url: /packages/weapi/alipay-compat-matrix/share.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦转发能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 转发

---

---
url: /packages/weapi/alipay-compat-matrix/ui.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦界面能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 界面

---

---
url: /packages/weapi/alipay-compat-matrix/network.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦网络能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 网络

---

---
url: /packages/weapi/alipay-compat-matrix/payment.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦支付能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 支付

---

---
url: /packages/weapi/alipay-compat-matrix/storage.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦数据缓存能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 数据缓存

---

---
url: /packages/weapi/alipay-compat-matrix/data-analysis.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦数据分析能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 数据分析

---

---
url: /packages/weapi/alipay-compat-matrix/canvas.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦画布能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 画布

---

---
url: /packages/weapi/alipay-compat-matrix/media.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦媒体能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 媒体

---

---
url: /packages/weapi/alipay-compat-matrix/location.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦位置能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 位置

---

---
url: /packages/weapi/alipay-compat-matrix/file.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦文件能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 文件

---

---
url: /packages/weapi/alipay-compat-matrix/open-api.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦开放接口能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 开放接口

---

---
url: /packages/weapi/alipay-compat-matrix/device.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦设备能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 设备

---

---
url: /packages/weapi/alipay-compat-matrix/ai.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦AI能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · AI

---

---
url: /packages/weapi/alipay-compat-matrix/worker.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦Worker能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · Worker

---

---
url: /packages/weapi/alipay-compat-matrix/wxml.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦WXML能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · WXML

---

---
url: /packages/weapi/alipay-compat-matrix/ext.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦第三方平台能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 第三方平台

---

---
url: /packages/weapi/alipay-compat-matrix/ad.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦广告能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · 广告

---

---
url: /packages/weapi/alipay-compat-matrix/xr-frame.md
description: '@wevu/api 的支付宝兼容矩阵页，聚焦XR-FRAME能力分类，帮助快速查看支付宝小程序与微信 API 的兼容情况。'
---

# 支付宝兼容矩阵 · XR-FRAME

---

---
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/base.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦基础能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 基础

---

---
url: /packages/weapi/douyin-compat-matrix/route.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦路由能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 路由

---

---
url: /packages/weapi/douyin-compat-matrix/navigate.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦跳转能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 跳转

---

---
url: /packages/weapi/douyin-compat-matrix/chattool.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦聊天工具能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 聊天工具

---

---
url: /packages/weapi/douyin-compat-matrix/share.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦转发能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 转发

---

---
url: /packages/weapi/douyin-compat-matrix/ui.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦界面能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 界面

---

---
url: /packages/weapi/douyin-compat-matrix/network.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦网络能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 网络

---

---
url: /packages/weapi/douyin-compat-matrix/payment.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦支付能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 支付

---

---
url: /packages/weapi/douyin-compat-matrix/storage.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦数据缓存能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 数据缓存

---

---
url: /packages/weapi/douyin-compat-matrix/data-analysis.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦数据分析能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 数据分析

---

---
url: /packages/weapi/douyin-compat-matrix/canvas.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦画布能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 画布

---

---
url: /packages/weapi/douyin-compat-matrix/media.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦媒体能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 媒体

---

---
url: /packages/weapi/douyin-compat-matrix/location.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦位置能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 位置

---

---
url: /packages/weapi/douyin-compat-matrix/file.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦文件能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 文件

---

---
url: /packages/weapi/douyin-compat-matrix/open-api.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦开放接口能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 开放接口

---

---
url: /packages/weapi/douyin-compat-matrix/device.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦设备能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 设备

---

---
url: /packages/weapi/douyin-compat-matrix/ai.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦AI能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · AI

---

---
url: /packages/weapi/douyin-compat-matrix/worker.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦Worker能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · Worker

---

---
url: /packages/weapi/douyin-compat-matrix/wxml.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦WXML能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · WXML

---

---
url: /packages/weapi/douyin-compat-matrix/ext.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦第三方平台能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 第三方平台

---

---
url: /packages/weapi/douyin-compat-matrix/ad.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦广告能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · 广告

---

---
url: /packages/weapi/douyin-compat-matrix/xr-frame.md
description: '@wevu/api 的抖音兼容矩阵页，聚焦XR-FRAME能力分类，帮助快速查看抖音小程序与微信 API 的兼容情况。'
---

# 抖音兼容矩阵 · XR-FRAME

---

---
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: /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: /packages.md
description: >-
  weapp-vite 不只是一个构建器，packages 下还提供脚手架、IDE CLI、MCP、跨端 API、Web 运行时、Volar
  与编译底座等能力。
---

# 周边包总览

`weapp-vite` 不只是一个构建器。围绕“创建项目、开发构建、IDE 自动化、运行时、AI 协作、编辑器提示”这条链路，仓库里的多个包会一起工作。

做技术选型时，建议先看本页，再按需进入对应子页面。

## 选型建议（先看这个）

* 新建项目：优先用 `create-weapp-vite`
* 新建项目后，希望把推荐的 AI skills 一并装好：用 `create-weapp-vite` 的 skills 安装选项
* 想让新项目默认带上 AI 工作流约束：用 `create-weapp-vite` 生成的 `AGENTS.md`
* 在 CI/脚本里调用微信开发者工具：用 `weapp-ide-cli`
* 想做小程序运行时截图：优先用 `wv screenshot` 或 `weapp screenshot`
* 想做截图对比 / visual regression：优先用 `wv compare` 或 `weapp compare`
* 想把 DevTools 里的小程序日志桥接回 AI 终端：优先用 `wv ide logs`，底层能力由 `weapp-ide-cli` 提供
* 想让 AI 助手直接理解并操作仓库：用 `@weapp-vite/mcp`，或直接执行 `wv mcp`
* 想先把类型支持文件、自动路由类型和自动导入组件类型生成出来：先运行 `wv prepare`
* 需要“打包后执行配置文件”：用 `rolldown-require`
* 想追踪 Vite 插件耗时瓶颈：用 `vite-plugin-performance`
* 想在非 Vite 场景复用 Wevu 编译能力：用 `@wevu/compiler`
* 想统一多端小程序 API 调用风格：用 `@wevu/api`
* 想在浏览器里做小程序语法预览、调试与兼容验证：用 `@weapp-vite/web`（实验）
* 想增强 `<json>` 配置块智能提示：用 `@weapp-vite/volar`

## 包能力矩阵

| 包名                      | 定位                                     | 适用场景                                           | 文档入口                                                                   |
| ------------------------- | ---------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------- |
| `create-weapp-vite`       | 官方脚手架                               | 快速创建模板项目、统一模板版本、可选安装 AI skills | [/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/)
* 学习路线与整套心智模型：见 [教程](/handbook/)
* AI 协作入口：见 [AI 协作指南](/guide/ai) 与 [AI 学习入口](/ai)

## 说明

* `rolldown-require-bench` 主要用于基准测试，不建议直接作为业务依赖。
* `@weapp-vite/web` 仍偏实验用途，适合技术验证、浏览器预览与 Web 侧调试。
* `@weapp-vite/mcp` 已被 `weapp-vite` CLI 集成，通常直接使用 `wv mcp` 即可；如果你希望 AI 更稳定命中截图与截图对比，也可以直接调用 `take_weapp_screenshot` 与 `compare_weapp_screenshot`。

---

---
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 或自动化脚本里做非交互创建
* 你希望项目初始化后，顺手把推荐的 AI skills 与 `AGENTS.md` 一起就位

## 快速开始

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

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

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

如果你选择跳过，也可以在项目创建完成后手动执行该命令。

同时，脚手架还会在项目根目录生成 `AGENTS.md`，把当前模板推荐的 AI 工作流、命令入口与约束一起写进去。

如果你想先了解这些 AI skills 分别适合什么任务，可以阅读 [AI Skills 使用指南](/guide/skills)；如果要把 issue 修复、文档同步、DevTools e2e 或迁移任务串成流程，可以阅读 [AI 任务工作流](/guide/ai-workflows)。

### 非交互模式

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

# 显式安装推荐 skills
pnpm create weapp-vite my-app wevu --install-skills

# 显式跳过推荐 skills 安装
pnpm create weapp-vite my-app wevu --no-install-skills
```

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

> **注意**：非交互模式下，如果你没有显式传 `--install-skills`，默认不会自动安装 AI skills；交互模式下默认值是“是”。

## CLI 参数

命令格式：

```bash
create-weapp-vite [targetDir] [templateName] [--install-skills] [--no-install-skills]
```

参数说明：

| 参数                  | 说明                                   |
| --------------------- | -------------------------------------- |
| `targetDir`           | 目标目录；交互模式默认 `my-app`        |
| `templateName`        | 模板名；非交互模式缺省时默认 `default` |
| `--install-skills`    | 非交互模式下显式安装推荐的 AI skills   |
| `--no-install-skills` | 非交互模式下显式跳过 AI skills 安装    |

交互流程会依次处理：

1. 目标目录
2. 是否覆盖已有目录
3. 模板选择
4. 是否安装推荐的 AI skills

## 可编程 API

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

await createProject('my-app', TemplateName.wevu)
await createProject('my-app', TemplateName.wevu, { installSkills: true })
```

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

| 模板名         | 说明                         |
| -------------- | ---------------------------- |
| `default`      | 默认原生小程序模板           |
| `plugin`       | 微信小程序插件模板           |
| `lib`          | 组件库模板（lib 模式）       |
| `wevu`         | Wevu + Vue SFC 模板          |
| `wevu-tdesign` | Wevu + TDesign + TailwindCSS |
| `tailwindcss`  | 原生小程序 + TailwindCSS     |
| `vant`         | Vant + TailwindCSS           |
| `tdesign`      | TDesign + TailwindCSS        |

## 初始化后会做什么

* 复制对应模板目录
* 自动整理 `gitignore` / `.gitignore`
* 对齐 `weapp-vite`、`wevu`、`@wevu/api` 等依赖版本
* 在项目根目录生成 `AGENTS.md`
* 按需执行 `npx skills add sonofmagic/skills`

如果 AI skills 安装失败，脚手架不会回滚项目创建，而是输出警告，并提示你稍后手动执行推荐命令。

## 与主文档的关系

* 工程创建后，日常开发请转到 [指引](/guide/) 与 [配置](/config/)。
* AI 协作、skills 与 MCP 接入请转到 [AI 协作指南](/guide/ai)、[AI Skills 使用指南](/guide/skills) 与 [@weapp-vite/mcp](/packages/mcp)。

---

---
url: /packages/weapp-ide-cli.md
description: weapp-ide-cli 是微信开发者工具 CLI 的增强封装，提供命令透传、automator 子命令、配置管理与多语言输出。
---

# weapp-ide-cli

`weapp-ide-cli` 是对微信开发者工具官方命令行的增强封装：

* 保留官方命令语义（透传）
* 增强路径/参数兼容
* 提供 automator 子命令
* 提供可持久化配置（`~/.weapp-ide-cli/config.json`）
* 默认中文提示，支持切换英文

在 `weapp-vite` 项目里，你通常不必单独记忆两套命令。`weapp-vite` 会在未命中自身命令时自动透传到 `weapp-ide-cli`，所以 `preview`、`upload`、`automator` 等能力也可以直接从 `weapp-vite` 入口调用。

如果你的目标是把 DevTools 里的小程序日志持续桥接到终端，当前更推荐直接使用 `wv ide logs`。`weapp-ide-cli` 负责底层连接与日志订阅，`weapp-vite` 则补充了 AI 终端自动检测、默认策略与常驻命令封装。

如果你在做 AI 验收，建议把下面这组路由当成默认约定：

* 提到截图、页面快照、runtime screenshot：优先用 `weapp screenshot`
* 提到截图对比、diff、baseline、视觉回归：优先用 `weapp compare`
* 提到 DevTools 日志桥接：优先用 `wv ide logs`

> 使用前请在微信开发者工具开启：`设置 -> 安全设置 -> 服务端口`。

## 安装

```bash
pnpm add -g weapp-ide-cli
# 或 npm install -g weapp-ide-cli
```

`weapp` 与 `weapp-ide-cli` 为等价入口。

## 快速开始

```bash
# 打开当前目录项目
weapp open -p

# 打开指定项目
weapp open --project ./dist/build/mp-weixin

# 运行时截图
weapp screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/index.png --json

# 运行时截图对比
weapp compare --project ./dist/build/mp-weixin --page pages/index/index --baseline .screenshots/baseline/index.png --current-output .tmp/current.png --diff-output .tmp/index.diff.png --max-diff-pixels 100 --json
```

## 命令大全

### 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>

其中 `weapp cloud` 为云开发命令族入口，可继续透传官方子命令，例如：

```bash
weapp cloud env list
weapp cloud functions list
weapp cloud functions info --name hello
weapp cloud functions deploy --name hello
weapp cloud functions inc-deploy --name hello
weapp cloud functions download --name hello
```

缓存清理示例：

```bash
weapp cache --clean compile
weapp cache --clean network
weapp cache --clean all
```

支持的缓存类型：

* `storage`
* `file`
* `compile`
* `auth`
* `network`
* `session`
* `all`

### 2) automator 增强命令

| 命令                             | 说明                      |
| -------------------------------- | ------------------------- |
| `weapp screenshot`               | 截图（base64 / 文件输出） |
| `weapp compare`                  | 截图对比（pixelmatch）    |
| `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
weapp compare --help
weapp compare --baseline .screenshots/baseline/home.png --max-diff-pixels 100 --json
```

#### `weapp screenshot` 选项

| 参数                   | 说明                   |
| ---------------------- | ---------------------- |
| `-p, --project <path>` | 项目路径，默认当前目录 |
| `-o, --output <path>`  | 截图输出文件           |
| `--page <path>`        | 截图前先跳转页面       |
| `-t, --timeout <ms>`   | 连接超时，默认 `30000` |
| `--json`               | JSON 输出              |
| `--lang <lang>`        | 语言切换：`zh` / `en`  |

输出规则：

* 不传 `--output` 时，默认把 base64 输出到 stdout
* 传入 `--output` 时，会把截图写到文件，并在 `--json` 结果里返回路径

#### `weapp compare` 选项

| 参数                        | 说明                             |
| --------------------------- | -------------------------------- |
| `-p, --project <path>`      | 项目路径，默认当前目录           |
| `--baseline <path>`         | baseline 图片路径，必填          |
| `--current-output <path>`   | 保存当前截图                     |
| `--diff-output <path>`      | 保存 diff 图                     |
| `--page <path>`             | 对比前先跳转页面                 |
| `--threshold <number>`      | pixelmatch threshold，默认 `0.1` |
| `--max-diff-pixels <count>` | 最大允许差异像素数               |
| `--max-diff-ratio <number>` | 最大允许差异占比，范围 `0-1`     |
| `-t, --timeout <ms>`        | 连接超时，默认 `30000`           |
| `--json`                    | JSON 输出                        |
| `--lang <lang>`             | 语言切换：`zh` / `en`            |

对比规则：

* 必须提供 `--baseline`
* 至少提供 `--max-diff-pixels` 或 `--max-diff-ratio` 之一
* baseline 与当前截图尺寸不一致时直接失败
* 对比失败时命令退出码会变为非 `0`

### 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 ...` |

首次使用前，请确保已全局安装 `minidev`。如果命令不存在，CLI 会给出安装提示。

### 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)
```

### 6) opened-session helper

除了官方 CLI 透传，`weapp-ide-cli` 现在也提供面向已打开 DevTools 会话的 Tool 域 helper，可优先复用当前会话完成以下操作：

* 查询当前 Tool 信息
* 触发重新编译
* 清理 DevTools 缓存
* 获取、设置、刷新 ticket
* 获取测试账号列表

如果你更希望直接在终端里操作这些会话信息，优先使用 `weapp-vite` 的高层入口：

* `wv ide info`
* `wv ide test-accounts`
* `wv ide ticket`
* `wv ide ticket:set --ticket <value>`
* `wv ide ticket:refresh`

`weapp-ide-cli` 更偏底层 helper 与官方能力对齐，`wv ide` 更适合日常开发调试。

## 语言切换

默认中文。可通过以下方式切换英文：

```bash
# 单次命令
weapp help navigate --lang en

# 持久化配置
weapp config lang en

# 环境变量
WEAPP_IDE_CLI_LANG=en weapp open -p
```

## 路径与脚本兼容

* `-p` 会被自动替换为 `--project`
* 相对路径会自动解析为绝对路径
* `--qr-output`、`--result-output`、`--info-output` 在缺省值场景下会默认写到当前工作目录
* 若未显式传路径参数，CLI 会自动注入当前终端目录，方便脚本化调用

## 参数前置校验（增强）

在调用官方 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` 必须为正整数

## CI / 非交互场景

推荐在 CI 或非交互脚本里显式传入：

```bash
weapp build-npm -p ./dist/build/mp-weixin --non-interactive
```

登录重试相关参数：

| 参数                         | 说明                                      |
| ---------------------------- | ----------------------------------------- |
| `--non-interactive`          | 非交互模式；登录失效时直接失败            |
| `--login-retry=<strategy>`   | 登录重试策略：`never` / `once` / `always` |
| `--login-retry-timeout=<ms>` | 交互重试等待超时，默认 `30000`            |

自动启用非交互模式的场景：

* `CI=true`
* `stdin` 不是 TTY

## 平台支持

| 平台            | 支持情况 | 默认查找路径                                               |
| --------------- | -------- | ---------------------------------------------------------- |
| macOS           | ✅       | `/Applications/wechatwebdevtools.app/Contents/MacOS/cli`   |
| Windows         | ✅       | `C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat` |
| Linux（社区版） | ⚠️       | 通过 `PATH` 搜索 `wechat-devtools-cli`                     |

## 参考

* 微信 CLI 文档：<https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html>
* 微信自动化文档：<https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/miniprogram.html>
* `weapp-vite` CLI 命令参考：[/guide/cli](/guide/cli)
* `weapp.forwardConsole` 配置：[/config/shared#weapp-forwardconsole](/config/shared#weapp-forwardconsole)

---

---
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: /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: /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: /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/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/mcp.md
description: '@weapp-vite/mcp 是 weapp-vite 官方 MCP 服务实现，面向 AI 助手提供源码检索、命令执行与文档资源能力。'
---

# @weapp-vite/mcp

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

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

## 推荐使用方式

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

`init` 会生成并写入对应客户端配置。当前支持的客户端名称是：

* `codex`
* `claude-code`
* `cursor`

如果你只想预览配置，不直接写入：

```bash
wv mcp print codex
```

写入完成后，建议执行：

```bash
wv mcp doctor codex
```

如果你已经启动了 `streamable-http` MCP 服务，也可以直接生成 HTTP 配置。未传 `--url` 时，CLI 会尝试从当前 workspace 的 `weapp.mcp` 配置推导地址：

```bash
wv mcp init codex --transport http
wv mcp init claude-code --transport http
wv mcp init cursor --transport http
wv mcp init codex --transport http --url http://127.0.0.1:3088/mcp
```

仍然需要手动起服务时：

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

## 何时使用

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

## 安装

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

## 启动方式

不在仓库目录执行时，可选追加 `--workspace-root <repo-root>`。

当前默认写入位置：

1. `Codex`: `~/.codex/config.toml`
2. `Claude Code`: 项目根目录 `.mcp.json`
3. `Cursor`: 项目根目录 `.cursor/mcp.json`

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

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

## 主要能力

### Tools

| Tool                       | 作用                                       | 关键输入                                                |
| -------------------------- | ------------------------------------------ | ------------------------------------------------------- |
| `workspace_catalog`        | 输出暴露包目录、版本、脚本清单             | 无                                                      |
| `list_source_files`        | 列出包内文件（默认 `src`）                 | `packageId`、`directory`、`maxResults`                  |
| `read_source_file`         | 读取源码文件，支持行区间裁剪               | `packageId`、`filePath`、`startLine`、`endLine`         |
| `search_source_code`       | 在源码里做关键词检索                       | `query`、`packageId`、`directory`                       |
| `run_package_script`       | 在指定包目录执行 `pnpm run <script>`       | `packageId`、`script`、`args`                           |
| `run_weapp_vite_cli`       | 调用 `weapp-vite` CLI                      | `subCommand`、`projectPath`、`platform`、`args`         |
| `take_weapp_screenshot`    | 显式截图工具，封装 `wv screenshot --json`  | `projectPath`、`page`、`outputPath`                     |
| `compare_weapp_screenshot` | 显式截图对比工具，封装 `wv compare --json` | `projectPath`、`baselinePath`、`page`、`diffOutputPath` |
| `run_repo_command`         | 执行仓库级白名单命令                       | `command`、`args`、`cwdRelative`                        |

### DevTools Runtime Tools

这组工具直接复用微信开发者工具 automator 会话，适合真实小程序运行时排查。常见调用顺序是先连接，再路由、截图、查结构、读日志。

| Tool                         | 作用                                                                         |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `weapp_devtools_connect`     | 确认 DevTools automator 会话可用，并返回当前页面与系统信息                   |
| `weapp_devtools_route`       | 执行 `navigateTo` / `redirectTo` / `reLaunch` / `switchTab` / `navigateBack` |
| `weapp_devtools_active_page` | 读取当前页面路径、查询参数、尺寸、滚动位置，可选返回页面 data                |
| `weapp_devtools_page_stack`  | 读取当前页面栈                                                               |
| `weapp_devtools_capture`     | 截取当前小程序视口，返回 base64 或保存图片                                   |
| `weapp_devtools_host_api`    | 调用 `wx.*` 宿主 API                                                         |
| `weapp_devtools_console`     | 读取 MCP 会话捕获的 console/exception 日志                                   |

### Runtime Inspection Tools

这组工具用于检查或操作当前页面、节点和组件实例。它们比纯截图更适合定位“结构在不在、状态对不对、事件有没有触发”。

| Tool                                                                                                                                                | 作用                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `weapp_runtime_find_node` / `weapp_runtime_find_nodes` / `weapp_runtime_wait_node`                                                                  | 查询或等待页面元素                          |
| `weapp_runtime_wait`                                                                                                                                | 在当前页面等待指定毫秒数                    |
| `weapp_runtime_page_state` / `weapp_runtime_update_page_state` / `weapp_runtime_invoke_page`                                                        | 读取页面 data、调用 `setData`、调用页面方法 |
| `weapp_runtime_tap_node` / `weapp_runtime_input_node`                                                                                               | 点击节点、向输入节点输入文本                |
| `weapp_runtime_component_state` / `weapp_runtime_update_component_state` / `weapp_runtime_invoke_component`                                         | 读取/更新组件 data、调用组件方法            |
| `weapp_runtime_find_child` / `weapp_runtime_find_children`                                                                                          | 在组件或节点内部继续查找元素                |
| `weapp_runtime_node_markup` / `weapp_runtime_node_styles` / `weapp_runtime_node_attrs` / `weapp_runtime_scroll_node` / `weapp_runtime_measure_node` | 读取节点 WXML、样式、属性、滚动或尺寸信息   |

### Resources

| Resource                                    | 说明                         |
| ------------------------------------------- | ---------------------------- |
| `weapp-vite://workspace/catalog`            | 工作区包目录、版本、脚本索引 |
| `weapp-vite://docs/{package}/README.md`     | 暴露包的 README              |
| `weapp-vite://docs/{package}/CHANGELOG.md`  | 暴露包的 CHANGELOG           |
| `weapp-vite://source/{package}?path={path}` | 读取指定源码文件             |

### Prompts

| Prompt                            | 说明                                  |
| --------------------------------- | ------------------------------------- |
| `plan-weapp-vite-change`          | 生成 weapp-vite / wevu 改造计划提示词 |
| `debug-wevu-runtime`              | 生成 wevu runtime 排查提示词          |
| `inspect-mini-program-page`       | 连接 DevTools 并检查页面渲染状态      |
| `recover-mini-program-connection` | 恢复 DevTools automator 连接          |

## AI 友好的截图工具

为了让 AI 在自然语言里更稳定地命中 mini-program runtime 能力，`@weapp-vite/mcp` 额外提供：

* `take_weapp_screenshot`
  * 面向“截图 / 页面快照 / runtime screenshot”
* `compare_weapp_screenshot`
  * 面向“截图对比 / diff / baseline / 视觉回归 / 像素对比”

这两个工具本质上分别封装了 `wv screenshot --json` 与 `wv compare --json`，但对 AI 更容易命中，也更适合在 prompt 里直接点名。

### `take_weapp_screenshot` 输入参数

| 参数          | 说明                                                                      |
| ------------- | ------------------------------------------------------------------------- |
| `projectPath` | 相对 workspace 根路径，通常是 `dist/build/mp-weixin` 或具体小程序项目目录 |
| `page`        | 可选；截图前先跳转到指定页面                                              |
| `outputPath`  | 可选；截图输出路径，建议写入 `.tmp/`                                      |
| `timeoutMs`   | 可选；命令超时                                                            |

### `compare_weapp_screenshot` 输入参数

| 参数                | 说明                                                                      |
| ------------------- | ------------------------------------------------------------------------- |
| `projectPath`       | 相对 workspace 根路径，通常是 `dist/build/mp-weixin` 或具体小程序项目目录 |
| `baselinePath`      | 相对 workspace 根路径的 baseline 图片路径                                 |
| `page`              | 可选；对比前先跳转页面                                                    |
| `currentOutputPath` | 可选；保存当前截图                                                        |
| `diffOutputPath`    | 可选；保存 diff 图                                                        |
| `threshold`         | 可选；pixelmatch threshold，范围 `0-1`                                    |
| `maxDiffPixels`     | 可选；最大允许差异像素数                                                  |
| `maxDiffRatio`      | 可选；最大允许差异占比，范围 `0-1`                                        |
| `timeoutMs`         | 可选；命令超时                                                            |

> **注意**：对比类工作流里，建议显式传入 `diffOutputPath`，这样 AI 在失败时能直接产出 diff 图用于复盘。

## 推荐提示词写法

如果你希望 AI 不要退化成浏览器截图，而是直接使用小程序运行时能力，建议在提示词里直接写：

```text
提到截图时优先使用 take_weapp_screenshot。
提到截图对比、baseline、diff、视觉回归时优先使用 compare_weapp_screenshot。
先读取 node_modules/weapp-vite/dist/docs/index.md 与 node_modules/weapp-vite/dist/docs/mcp.md。
```

如果项目是通过 `create-weapp-vite` 初始化的，根目录里的 `AGENTS.md` 通常也已经内置了这类 AI 意图路由规则。

## 安全约束

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)
3. [CLI 命令参考](/guide/cli)

---

---
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/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/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: /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/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: /wevu/api.md
description: Wevu API 完整速查页，按 Vue 迁移兼容性、能力类型与运行作用域筛选公开能力。
---


---

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

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

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

## 入口与组件定义

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

**类型签名：** `typeof import('wevu')['createApp']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**Vue 差异：** Vue Web 创建并挂载 DOM 应用；Wevu 创建的是小程序 App 注册描述，不接收根 DOM 容器，通常每个 App 入口只调用一次。

**示例：** 见 [本组示例](/wevu/api/core#example-core-entry)。

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

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

**类型签名：** `typeof import('wevu')['defineComponent']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-entry)。

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

### 本组示例 {#example-core-entry}

App 入口负责全局初始化，页面和组件继续通过 `defineComponent()` 组织实例状态。

```ts
import { createApp, defineComponent, onShow, ref } from 'wevu'

createApp({
  setup() {
    return { startedAt: Date.now() }
  },
})

export default defineComponent({
  setup() {
    const visits = ref(0)
    onShow(() => visits.value += 1)
    return { visits }
  },
})
```

## 应用实例

### `app.mount()` {#app-mount}

**类型签名：** `RuntimeApp['mount']`

**Vue 差异：** Vue 接收 DOM 容器；Wevu 接收可选的小程序 `MiniProgramAdapter`，并返回 `RuntimeInstance`。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

该方法建立响应式状态与小程序 `setData` 之间的适配。常规小程序入口由 `createApp()` 自动注册，只有测试或自定义适配器场景通常需要显式调用。

### `app.unmount()` {#app-unmount}

**类型签名：** `RuntimeApp['unmount']`

**Vue 兼容说明：** 都用于停止应用并执行清理，但 Wevu 不涉及 DOM 根节点移除。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

重复调用是安全的；已执行的应用级清理不会再次运行。

### `app.onUnmount()` {#app-onunmount}

**类型签名：** `RuntimeApp['onUnmount']`

**Vue 兼容说明：** 调用方式与 Vue 一致；Wevu 用它管理小程序应用级插件和资源清理。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

传入值必须是函数。应用已经卸载时，新登记的清理函数会立即执行。

### `app.use()` {#app-use}

**类型签名：** `RuntimeApp['use']`

**Vue 兼容说明：** 支持函数插件和带 `install()` 的对象插件，并忽略同一插件的重复安装；插件接收的是 Wevu `RuntimeApp`。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

插件中的 hook 仍需在同步初始化阶段注册，不能在 `await` 之后补注册生命周期。

### `app.provide()` {#app-provide}

**类型签名：** `RuntimeApp['provide']`

**Vue 兼容说明：** 调用方式与 Vue 一致；依赖通过 Wevu 的页面/组件上下文链传递，而不是 DOM 组件树。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

返回应用实例，可与 `app.use()` 链式调用。

### `app.config` {#app-config}

**类型定义：** `AppConfig`

**Vue 差异：** Wevu 当前只公开 `globalProperties`，不提供 Vue Web 的错误处理器、编译器选项、性能标记和选项合并策略。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

不要假设 Vue `app.config` 的其他字段在 Wevu 中存在。

### `app.config.globalProperties` {#app-config-globalproperties}

**类型定义：** `Record<string, any>`

**Vue 兼容说明：** 用于向组件公开共享属性；最终访问发生在 Wevu 组件公共代理上。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

业务状态仍应优先放入 store 或 provide/inject，避免把该对象当成无边界全局状态容器。

### `app.version` {#app-version}

**运行时值：** `string`

**Vue 兼容说明：** 与 Vue 一样用于读取当前框架版本，值对应 Wevu 包版本。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

该字段为只读版本信息，不用于运行时能力检测。

### `version` {#version}

**运行时值：** `string`

**Vue 兼容说明：** `wevu` 根入口直接导出版本字符串，与 `app.version` 保持一致。

**示例：** 见 [本组示例](/wevu/api/core#example-app-instance)。

适合在诊断信息中展示，不要根据字符串比较切换核心业务逻辑。

### 本组示例 {#example-app-instance}

应用实例适合承载插件安装、全局依赖和应用级清理。

```ts
import { createApp, version } from 'wevu'

const app = createApp({})

app
  .use(runtimeApp => runtimeApp.provide('apiBase', '/api'))
  .onUnmount(() => console.info('dispose app resources'))

console.info(version, app.version)
```

## Script Setup 宏

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

**类型签名：** `typeof import('wevu')['defineProps']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

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

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

**类型签名：** `typeof import('wevu')['withDefaults']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

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

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

**类型签名：** `typeof import('wevu')['defineEmits']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

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

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

**类型签名：** `typeof import('wevu')['defineSlots']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

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

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

**类型签名：** `typeof import('wevu')['defineExpose']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

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

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

**类型签名：** `typeof import('wevu')['defineModel']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

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

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

**类型签名：** `typeof import('wevu')['defineOptions']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

* 类型入口：`MiniProgramComponentOptions`
* 用途：在 `<script setup>` 中定义组件配置项。
* Behavior 说明：可直接声明 `behaviors`。当条目来自原生 `Behavior()` 返回值时，编译阶段会保留该表达式并继续后续转换。
* 字段分层：
  * 放进 `options` 的是原生 `ComponentOptions` 字段，例如 `multipleSlots`、`styleIsolation`、`virtualHost`
  * 组件顶层字段例如 `externalClasses`、`behaviors`、`relations`，直接写在 `defineOptions({ ... })` 顶层

示例：

```vue
<script setup lang="ts">
defineOptions({
  externalClasses: ['custom-class'],
  options: {
    virtualHost: true,
    styleIsolation: 'apply-shared',
  },
})
</script>
```

### `definePageMeta()` {#definepagemeta}

**类型签名：** `typeof import('wevu')['definePageMeta']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

* 类型入口：`PageMeta` / `PageLayoutMeta`
* 用途：在 `<script setup>` 中声明页面级元信息。
* 说明：常用于声明页面 `layout`，与 Weapp-vite 的自动路由、`routeRules.layout` 和运行时 `setPageLayout()` 保持同一套页面壳心智。

示例：

```vue
<script setup lang="ts">
definePageMeta({
  layout: 'default',
})
</script>
```

### `defineAppSetup()` {#defineappsetup}

**类型签名：** `typeof import('wevu')['defineAppSetup']`

**运行时说明：** 这是 `<script setup>` 编译期宏，无需从 `wevu` 导入，也不能作为普通运行时函数动态调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

* 类型入口：`RuntimeApp`
* 用途：声明 App 级 setup 初始化逻辑。
* 说明：适合把插件安装、全局 provide、全局 router 初始化等 App 级逻辑收敛到一个同步入口。

### `defineAppJson()` {#defineappjson}

**类型签名：** `typeof import('weapp-vite/json')['defineAppJson']`

**运行时说明：** 在 `app.vue` 中作为顶层编译宏使用时，配置会被提取并合并到 `app.json`，运行时零开销。

**示例：** 见 [本组示例](/wevu/api/core#example-json-macros)。

支持直接对象或接收编译上下文的函数；一个 App SFC 应只保留一套 App JSON 声明。

### `definePageJson()` {#definepagejson}

**类型签名：** `typeof import('weapp-vite/json')['definePageJson']`

**运行时说明：** 在页面 SFC 中提取为页面 JSON，可与 `definePageMeta()` 分别声明宿主配置和布局元信息。

**示例：** 见 [本组示例](/wevu/api/core#example-json-macros)。

常用于导航栏、下拉刷新和 `usingComponents` 等页面配置。

### `defineComponentJson()` {#definecomponentjson}

**类型签名：** `typeof import('weapp-vite/json')['defineComponentJson']`

**运行时说明：** 在组件 SFC 中提取为组件 JSON，并参与原生组件注册与选项合并。

**示例：** 见 [本组示例](/wevu/api/core#example-json-macros)。

组件角色只使用该宏，不要与页面或 App JSON 宏混用。

### `defineSitemapJson()` {#definesitemapjson}

**类型签名：** `typeof import('weapp-vite/json')['defineSitemapJson']`

**编译期说明：** 这是 `weapp-vite/json` 导出的类型安全配置辅助函数，不是 Vue SFC 自动提取宏。

**示例：** 见 [本组示例](/wevu/api/core#example-json-macros)。

它返回原配置，适合在独立 sitemap 配置模块中获得结构类型提示。

### `defineThemeJson()` {#definethemejson}

**类型签名：** `typeof import('weapp-vite/json')['defineThemeJson']`

**编译期说明：** 这是 `weapp-vite/json` 导出的主题配置辅助函数，不是 Vue SFC 自动提取宏。

**示例：** 见 [本组示例](/wevu/api/core#example-json-macros)。

它用于约束 theme 配置结构，本身不注册 Wevu 运行时能力。

### 本组示例 {#example-json-macros}

页面 SFC 中直接使用对应角色的 JSON 宏，无需保留额外 `<json>` 块。

```vue
<script setup lang="ts">
definePageJson({
  navigationBarTitleText: '订单',
  enablePullDownRefresh: true,
})

definePageMeta({ layout: 'default' })
</script>
```

### `use()` {#use}

**类型签名：** `typeof import('wevu')['use']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

* 类型入口：`WevuPlugin`
* 用途：安装 Wevu 插件。
* 说明：可在 App setup 或受控初始化逻辑中使用；插件如果需要注册 hook，仍必须保持同步注册。

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

**类型签名：** `typeof import('wevu')['mergeModels']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

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

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

**类型签名：** `typeof import('wevu')['useModel']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-macros)。

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

### 本组示例 {#example-core-macros}

相关宏可以在一个组件中共同声明类型、默认值、事件和 model。

```vue
<script setup lang="ts">
interface Props { title?: string }

defineOptions({ options: { virtualHost: true } })
const props = withDefaults(defineProps<Props>(), { title: '未命名' })
const emit = defineEmits<{ submit: [title: string] }>()
const model = defineModel<number>({ default: 0 })

defineExpose({ submit: () => emit('submit', props.title) })
</script>
```

## 模板工具

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

**类型签名：** `typeof import('wevu')['useAttrs']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-template)。

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

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

**类型签名：** `typeof import('wevu')['useSlots']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-template)。

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

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

**类型签名：** `typeof import('wevu')['useTemplateRef']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-template)。

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

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

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

### `useNativeRouter()` {#usenativerouter}

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

### `useNativePageRouter()` {#usenativepagerouter}

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

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

**类型签名：** `typeof import('wevu')['normalizeClass']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-template)。

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

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

**类型签名：** `typeof import('wevu')['normalizeStyle']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/core#example-core-template)。

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

### 本组示例 {#example-core-template}

原生实例和模板 ref 只在方法中使用，不要把它们返回为模板可序列化状态。

```vue
<script setup lang="ts">
import { normalizeClass, useAttrs, useNativeInstance, useTemplateRef } from 'wevu'

const attrs = useAttrs()
const panel = useTemplateRef('panel')
const native = useNativeInstance()
const panelClass = normalizeClass(['panel', { highlighted: attrs.highlighted }])

function inspectPanel() {
  console.log(panel.value, native)
}
</script>
```

---

---
url: /wevu/api/options-api.md
description: Wevu 支持的 Vue 风格与小程序原生 Options API 清单，以及迁移时需要注意的语义差异。
---

# Options API

Wevu 接受 Vue 风格选项，同时保留小程序 `Component` 的宿主选项。名称相同不代表运行时语义完全相同：组件注册、生命周期时机、props 规范化和更新最终都受小程序宿主约束。

## Vue 风格选项

### `props` {#props}

**类型签名：** `DefineComponentOptions['props']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**Vue 差异：** 名称沿用 Vue Options API，但 Wevu 最终生成小程序 `Component()` 配置，没有 DOM、Virtual DOM 或浏览器组件实例；生命周期应使用 Wevu/宿主对应项。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-vue)。

支持数组、对象和类型声明，并在注册阶段转换为小程序 `properties`。

### `emits` {#emits}

**类型签名：** `DefineComponentOptions['emits']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**Vue 差异：** 名称沿用 Vue Options API，但 Wevu 最终生成小程序 `Component()` 配置，没有 DOM、Virtual DOM 或浏览器组件实例；生命周期应使用 Wevu/宿主对应项。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-vue)。

用于声明组件事件；实际派发通过小程序组件事件系统完成。

### `data` {#data}

**类型签名：** `DefineComponentOptions['data']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**Vue 差异：** 名称沿用 Vue Options API，但 Wevu 最终生成小程序 `Component()` 配置，没有 DOM、Virtual DOM 或浏览器组件实例；生命周期应使用 Wevu/宿主对应项。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-vue)。

支持对象或返回初始状态的函数，推荐使用函数形式。

### `setup` {#setup}

**类型签名：** `DefineComponentOptions['setup']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**Vue 差异：** 名称沿用 Vue Options API，但 Wevu 最终生成小程序 `Component()` 配置，没有 DOM、Virtual DOM 或浏览器组件实例；生命周期应使用 Wevu/宿主对应项。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-vue)。

在 Wevu setup 上下文中执行。默认在组件 `attached` 阶段运行，与 Vue 组件创建时机存在差异。

### `computed` {#computed}

**类型签名：** `DefineComponentOptions['computed']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**Vue 差异：** 名称沿用 Vue Options API，但 Wevu 最终生成小程序 `Component()` 配置，没有 DOM、Virtual DOM 或浏览器组件实例；生命周期应使用 Wevu/宿主对应项。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-vue)。

参与 Wevu 响应式快照和 `setData` 差量更新，不是 Vue DOM 渲染器的 computed 调度链路。

### `methods` {#methods}

**类型签名：** `DefineComponentOptions['methods']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**Vue 差异：** 名称沿用 Vue Options API，但 Wevu 最终生成小程序 `Component()` 配置，没有 DOM、Virtual DOM 或浏览器组件实例；生命周期应使用 Wevu/宿主对应项。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-vue)。

方法会绑定到小程序公开实例，并可供模板事件处理器调用。

### `watch` {#watch}

**类型签名：** `DefineComponentOptions['watch']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**Vue 差异：** 名称沿用 Vue Options API，但 Wevu 最终生成小程序 `Component()` 配置，没有 DOM、Virtual DOM 或浏览器组件实例；生命周期应使用 Wevu/宿主对应项。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-vue)。

监听 data、props 或 computed 路径；调度和深度监听能力以 [Reactivity API](/wevu/api/reactivity#watch) 为准。

### 本组示例 {#example-options-vue}

Vue 风格选项最终仍由小程序 `Component()` 注册和调度。

```ts
import { defineComponent } from 'wevu'

export default defineComponent({
  props: { initial: { type: Number, default: 0 } },
  data() { return { count: this.initial } },
  computed: { doubled() { return this.count * 2 } },
  methods: { increment() { this.count += 1 } },
  watch: { count(value) { console.log('count', value) } },
})
```

## 小程序宿主选项

### `properties` {#properties}

**类型签名：** `DefineComponentOptions['properties']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

原生小程序属性声明。新代码优先使用 `props`，需要宿主级 observer 或原生类型行为时使用本选项。

### `behaviors` {#behaviors}

**类型签名：** `DefineComponentOptions['behaviors']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

透传小程序 behaviors 配置。

### `lifetimes` {#lifetimes}

**类型签名：** `DefineComponentOptions['lifetimes']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

透传组件生命周期；对应 Hook 映射见 [Lifecycle API](/wevu/api/lifecycle#小程序原生生命周期映射说明)。

### `pageLifetimes` {#pagelifetimes}

**类型签名：** `DefineComponentOptions['pageLifetimes']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

透传组件所在页面的生命周期。

### `externalClasses` {#externalclasses}

**类型签名：** `DefineComponentOptions['externalClasses']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

声明组件可接收的外部样式类。

### `options` {#options}

**类型签名：** `DefineComponentOptions['options']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

透传小程序组件选项，例如 `virtualHost`。

### `observers` {#observers}

**类型签名：** `DefineComponentOptions['observers']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

透传小程序数据字段监听器。

### `relations` {#relations}

**类型签名：** `DefineComponentOptions['relations']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

透传小程序组件关系定义。

### `features` {#features}

**类型签名：** `DefineComponentOptions['features']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

按需开启页面事件桥接，避免为未使用的页面事件生成处理函数。

### `setData` {#setdata}

**类型签名：** `DefineComponentOptions['setData']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

配置快照、diff 和 `setData` payload 策略。

### `setupLifecycle` {#setuplifecycle}

**类型签名：** `DefineComponentOptions['setupLifecycle']`

**运行时说明：** 该选项最终注册到小程序 `Component()` 定义；页面与组件共享注册模型，但宿主只会调用当前实例支持的字段。

**示例：** 见 [本组示例](/wevu/api/options-api#example-options-host)。

选择 `setup` 在 `created` 或 `attached` 阶段执行，默认值为 `attached`。

### 本组示例 {#example-options-host}

宿主选项直接对应 `Component()` 字段，不要按 Vue Web 选项解释。

```ts
import { defineComponent } from 'wevu'

export default defineComponent({
  properties: { status: { type: String, value: 'idle' } },
  options: { multipleSlots: true, styleIsolation: 'apply-shared' },
  lifetimes: { attached() { console.log('attached') } },
  pageLifetimes: { show() { console.log('page show') } },
  externalClasses: ['custom-class'],
})
```

---

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

# Reactivity API（响应式与调度）

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

## 状态创建与派生

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

**类型签名：** `typeof import('wevu')['ref']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-state)。

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

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

**类型签名：** `typeof import('wevu')['customRef']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-state)。

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

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

**类型签名：** `typeof import('wevu')['reactive']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-state)。

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

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

**类型签名：** `typeof import('wevu')['shallowRef']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-state)。

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

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

**类型签名：** `typeof import('wevu')['shallowReactive']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-state)。

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

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

**类型签名：** `typeof import('wevu')['readonly']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-state)。

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

### `shallowReadonly()` {#shallowreadonly}

**类型签名：** `typeof import('wevu')['shallowReadonly']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-state)。

* 类型入口：`Readonly<T>`
* 用途：创建浅层只读代理。
* 说明：仅保护顶层字段；嵌套对象仍保持原始语义。

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

**类型签名：** `typeof import('wevu')['computed']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-state)。

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

### 本组示例 {#example-reactivity-state}

组合深层状态、独立 Ref 和派生值时，只把可序列化数据交给模板。

```vue
<script setup lang="ts">
import { computed, reactive, readonly, ref, shallowRef } from 'wevu'

const count = ref(0)
const form = reactive({ price: 20, quantity: 1 })
const sdk = shallowRef<{ refresh: () => void }>()
const total = computed(() => form.price * form.quantity)
const publicForm = readonly(form)
</script>
```

## 监听与副作用

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

**类型签名：** `typeof import('wevu')['watch']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

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

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

**类型签名：** `typeof import('wevu')['watchEffect']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

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

### `watchPostEffect()` {#watchposteffect}

**类型签名：** `typeof import('wevu')['watchPostEffect']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

* 类型入口：`WatchStopHandle`
* 用途：以 post flush 语义注册自动依赖副作用。
* 说明：用于希望等待当前更新批次之后再执行的副作用；业务侧仍要避免在高频页面滚动里写重逻辑。

### `watchSyncEffect()` {#watchsynceffect}

**类型签名：** `typeof import('wevu')['watchSyncEffect']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

* 类型入口：`WatchStopHandle`
* 用途：以 sync flush 语义注册自动依赖副作用。
* 说明：适合极少数需要同步响应状态变化的组合式工具；普通业务优先使用 `watchEffect()`。

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

**类型签名：** `typeof import('wevu')['effect']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

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

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

**类型签名：** `typeof import('wevu')['effectScope']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

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

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

**类型签名：** `typeof import('wevu')['getCurrentScope']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

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

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

**类型签名：** `typeof import('wevu')['onScopeDispose']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

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

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

**类型签名：** `typeof import('wevu')['stop']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-effects)。

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

### 本组示例 {#example-reactivity-effects}

把相关监听放进同一 scope，可以在页面卸载或业务结束时统一停止。

```ts
import { effectScope, onScopeDispose, ref, watch, watchEffect } from 'wevu'

const count = ref(0)
const scope = effectScope()

scope.run(() => {
  const stopWatch = watch(count, value => console.log(value))
  watchEffect(() => documentTitle(count.value))
  onScopeDispose(stopWatch)
})

scope.stop()
```

## Ref / Proxy 工具

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

**类型签名：** `typeof import('wevu')['toRef']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-ref-tools)。

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

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

**类型签名：** `typeof import('wevu')['toRefs']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-ref-tools)。

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

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

**类型签名：** `typeof import('wevu')['unref']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-ref-tools)。

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

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

**类型签名：** `typeof import('wevu')['toValue']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-ref-tools)。

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

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

**类型签名：** `typeof import('wevu')['triggerRef']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-ref-tools)。

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

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

**类型签名：** `typeof import('wevu')['toRaw']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-ref-tools)。

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

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

**类型签名：** `typeof import('wevu')['markRaw']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-ref-tools)。

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

### 本组示例 {#example-reactivity-ref-tools}

工具函数让组合式函数同时接受普通值、Ref 或 getter。

```ts
import { reactive, shallowRef, toRaw, toRef, toRefs, toValue, triggerRef } from 'wevu'

const state = reactive({ count: 0, name: 'Ada' })
const count = toRef(state, 'count')
const fields = toRefs(state)
const config = shallowRef({ enabled: true })

config.value.enabled = false
triggerRef(config)
console.log(toValue(count), fields.name.value, toRaw(state))
```

## 响应式判定

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

**类型签名：** `typeof import('wevu')['isRef']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-checks)。

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

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

**类型签名：** `typeof import('wevu')['isReactive']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-checks)。

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

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

**类型签名：** `typeof import('wevu')['isShallowRef']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-checks)。

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

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

**类型签名：** `typeof import('wevu')['isShallowReactive']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-checks)。

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

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

**类型签名：** `typeof import('wevu')['isRaw']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-checks)。

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

### `isReadonly()` {#isreadonly}

**类型签名：** `typeof import('wevu')['isReadonly']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-checks)。

* 类型入口：`boolean`
* 用途：判断值是否来自 `readonly()` 或 `shallowReadonly()`。

### `isProxy()` {#isproxy}

**类型签名：** `typeof import('wevu')['isProxy']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-checks)。

* 类型入口：`boolean`
* 用途：判断值是否为 Wevu 响应式/只读代理。

### 本组示例 {#example-reactivity-checks}

判定函数适合库边界和调试，不应代替清晰的数据建模。

```ts
import { isProxy, isRaw, isReactive, isReadonly, isRef, markRaw, reactive, readonly, ref } from 'wevu'

const count = ref(0)
const state = reactive({ count: 0 })
const locked = readonly(state)
const sdk = markRaw({ version: 1 })

console.log(isRef(count), isReactive(state), isReadonly(locked))
console.log(isProxy(state), isRaw(sdk))
```

## 批处理与调度

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

**类型签名：** `typeof import('wevu')['nextTick']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-scheduling)。

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

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

**类型签名：** `typeof import('wevu')['batch']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-scheduling)。

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

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

**类型签名：** `typeof import('wevu')['startBatch']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-scheduling)。

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

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

**类型签名：** `typeof import('wevu')['endBatch']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-scheduling)。

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

### `traverse()` {#traverse}

**类型签名：** `typeof import('wevu')['traverse']`

**运行时说明：** 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 `setData` 更新；模板状态必须保持可序列化。

**示例：** 见 [本组示例](/wevu/api/reactivity#example-reactivity-scheduling)。

* 类型入口：`unknown`
* 用途：显式遍历响应式值及其嵌套成员，建立深层依赖。
* 说明：主要用于组合式工具和调试能力；普通业务的深层监听优先使用 `watch()` 的 `deep` 选项。

### 本组示例 {#example-reactivity-scheduling}

业务代码优先使用 `batch()`；手动批处理必须用 `finally` 保证配对结束。

```ts
import { batch, endBatch, nextTick, ref, startBatch } from 'wevu'

const count = ref(0)
batch(() => {
  count.value += 1
  count.value += 1
})
await nextTick()

startBatch()
try {
  count.value += 1
}
finally {
  endBatch()
}
```

## 内部能力说明

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

---

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

# Lifecycle API（生命周期）

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

## App 生命周期 Hook

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

**类型签名：** `typeof import('wevu')['onLaunch']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-app)。

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

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

**类型签名：** `typeof import('wevu')['onShow']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-app)。

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

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

**类型签名：** `typeof import('wevu')['onHide']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-app)。

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

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

**类型签名：** `typeof import('wevu')['onError']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-app)。

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

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

**类型签名：** `typeof import('wevu')['onPageNotFound']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-app)。

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

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

**类型签名：** `typeof import('wevu')['onUnhandledRejection']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-app)。

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

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

**类型签名：** `typeof import('wevu')['onThemeChange']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-app)。

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

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

**类型签名：** `typeof import('wevu')['onMemoryWarning']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-app)。

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

### 本组示例 {#example-lifecycle-app}

App hook 同样必须在同步 `setup()` 中注册。

```ts
import { createApp, onError, onLaunch, onMemoryWarning, onShow } from 'wevu'

createApp({
  setup() {
    onLaunch(options => console.log('launch', options))
    onShow(options => console.log('show', options))
    onError(error => console.error(error))
    onMemoryWarning(({ level }) => console.warn('memory', level))
  },
})
```

## 页面生命周期 Hook

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

**类型签名：** `typeof import('wevu')['onLoad']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-page)。

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

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

**类型签名：** `typeof import('wevu')['onReady']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-page)。

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

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

**类型签名：** `typeof import('wevu')['onUnload']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-page)。

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

### 本组示例 {#example-lifecycle-page}

先同步注册 hook，再在回调内部执行异步工作。

```vue
<script setup lang="ts">
import { onLoad, onReady, onUnload } from 'wevu'

let timer: ReturnType<typeof setInterval> | undefined

onLoad(query => console.log('query', query))
onReady(() => {
  timer = setInterval(() => {}, 1000)
})
onUnload(() => {
  if (timer) {
    clearInterval(timer)
  }
})
</script>
```

## 页面事件 Hook

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

**类型签名：** `typeof import('wevu')['onPullDownRefresh']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-events)。

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

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

**类型签名：** `typeof import('wevu')['onReachBottom']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-events)。

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

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

**类型签名：** `typeof import('wevu')['onPageScroll']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-events)。

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

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

**类型签名：** `typeof import('wevu')['onRouteDone']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-events)。

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

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

**类型签名：** `typeof import('wevu')['onTabItemTap']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-events)。

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

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

**类型签名：** `typeof import('wevu')['onResize']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-events)。

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

### 本组示例 {#example-lifecycle-events}

高频滚动回调只更新必要状态，耗时请求放在低频事件中。

```vue
<script setup lang="ts">
import { onPageScroll, onPullDownRefresh, onReachBottom, ref } from 'wevu'

const scrollTop = ref(0)
onPageScroll((event) => {
  scrollTop.value = event.scrollTop
})
onReachBottom(() => loadNextPage())
onPullDownRefresh(async () => {
  await reloadList()
  wx.stopPullDownRefresh()
})
</script>
```

## 返回值型页面 Hook

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

**类型签名：** `typeof import('wevu')['onShareAppMessage']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-return)。

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

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

**类型签名：** `typeof import('wevu')['onShareTimeline']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-return)。

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

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

**类型签名：** `typeof import('wevu')['onAddToFavorites']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-return)。

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

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

**类型签名：** `typeof import('wevu')['onSaveExitState']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-return)。

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

### 本组示例 {#example-lifecycle-return}

返回值直接交给小程序宿主，字段结构应遵循对应平台契约。

```vue
<script setup lang="ts">
import { onAddToFavorites, onShareAppMessage, onShareTimeline } from 'wevu'

onShareAppMessage(() => ({ title: '商品详情', path: '/pages/goods/index?id=42' }))
onShareTimeline(() => ({ title: '商品详情', query: 'id=42' }))
onAddToFavorites(() => ({ title: '商品详情', query: 'id=42' }))
</script>
```

## 组件扩展 Hook

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

**类型签名：** `typeof import('wevu')['onAttached']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-component)。

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

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

**类型签名：** `typeof import('wevu')['onDetached']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-component)。

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

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

**类型签名：** `typeof import('wevu')['onMoved']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-component)。

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

### 本组示例 {#example-lifecycle-component}

组件资源在 attached 后创建，并在 detached 中释放。

```vue
<script setup lang="ts">
import { onAttached, onDetached, onMoved } from 'wevu'

let observer: WechatMiniprogram.IntersectionObserver | undefined

onAttached(() => {
  observer = wx.createIntersectionObserver()
})
onMoved(() => console.log('component moved'))
onDetached(() => {
  observer?.disconnect()
})
</script>
```

## Vue 语义对齐 Hook

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

**类型签名：** `typeof import('wevu')['onBeforeMount']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 没有 DOM mount 阶段；该回调发生在小程序实例已创建、首次宿主渲染提交之前。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onMounted']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 对应宿主 `ready`，不是浏览器 DOM 插入完成；此时才适合执行节点查询。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onBeforeUpdate']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 围绕 Wevu 即将提交的 `setData` 批次触发，而不是 Virtual DOM patch。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onUpdated']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 在当前 `setData` 更新批次完成后触发，不能据此假设浏览器布局或 `requestAnimationFrame` 语义。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onBeforeUnmount']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 对应页面卸载或组件移除前的清理阶段，不涉及 DOM unmount。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onUnmounted']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 对应宿主 `detached`/页面卸载后的销毁阶段。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onActivated']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 映射到页面或组件重新可见的宿主生命周期，不依赖 Vue `<KeepAlive>`。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onDeactivated']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 映射到宿主隐藏阶段，不表示 `<KeepAlive>` 缓存树被停用。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onErrorCaptured']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 捕获 Wevu setup、渲染和宿主生命周期链路中的错误，不具备完整 Vue 组件树错误传播语义。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

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

**类型签名：** `typeof import('wevu')['onServerPrefetch']`

**运行时说明：** 必须在同步 `setup()` 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 `await` 之后注册。

**Vue 差异：** 小程序没有 SSR；为迁移兼容保留该 hook，但运行时不会执行预取。

**示例：** 见 [本组示例](/wevu/api/lifecycle#example-lifecycle-vue)。

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

### 本组示例 {#example-lifecycle-vue}

这些名称接近 Vue，但时机围绕宿主 ready、setData 和 detached。

```vue
<script setup lang="ts">
import { onBeforeUpdate, onMounted, onServerPrefetch, onUnmounted, onUpdated } from 'wevu'

onMounted(() => console.log('宿主 ready，可开始节点查询'))
onBeforeUpdate(() => console.log('setData 提交前'))
onUpdated(() => console.log('setData 批次完成'))
onUnmounted(() => console.log('宿主实例已销毁'))

// 小程序没有 SSR，这个兼容 hook 不会执行。
onServerPrefetch(async () => {})
</script>
```

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

以下是桥接关系说明，不是 `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`。

---

---
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}

**类型签名：** `typeof import('wevu')['getCurrentInstance']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-instance)。

* 用途：获取当前运行时实例。
* 源码：`runtime/hooks.ts`。

### `getCurrentSetupContext()` {#getcurrentsetupcontext}

**类型签名：** `typeof import('wevu')['getCurrentSetupContext']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-instance)。

* 用途：获取当前 setup context。
* 源码：`runtime/hooks.ts`。

### 本组示例 {#example-setup-instance}

Wevu 上下文可参与组合逻辑，原生实例只在命令式方法里使用。

```vue
<script setup lang="ts">
import { getCurrentInstance, getCurrentSetupContext, useNativeInstance } from 'wevu'

const instance = getCurrentInstance()
const context = getCurrentSetupContext()
const native = useNativeInstance()

function submit() {
  context?.emit('submit', instance?.setupState)
  native?.triggerEvent('native-submit')
}
</script>
```

## 依赖注入 API

### `provide()` {#provide}

**类型签名：** `typeof import('wevu')['provide']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-provide)。

* 用途：在当前组件树提供依赖。
* 源码：`runtime/provide.ts`。

### `inject()` {#inject}

**类型签名：** `typeof import('wevu')['inject']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-provide)。

* 用途：从上层读取依赖。
* 源码：`runtime/provide.ts`。

### `provideGlobal()` / `injectGlobal()`（Deprecated） {#provideglobal}

**类型签名：** `typeof import('wevu')['provideGlobal']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-provide)。

* 用途：已弃用的全局 provide/inject 兼容入口。
* 说明：当前更推荐优先使用 `provide()` / `inject()`；无实例上下文时，它们本身就会回退到全局存储。
* 源码：`runtime/provide.ts`。

> \[!WARNING]
> 这组 API 仅为兼容旧代码而保留，不建议在新代码中继续使用。
> 优先使用 `provide()` / `inject()`；需要稳定的跨页面全局共享时，优先考虑 store。

### 本组示例 {#example-setup-provide}

页面或上层组件提供响应式依赖，下层组件按同一个 key 注入。

```ts
import type { InjectionKey, Ref } from 'wevu'
import { inject, provide, ref } from 'wevu'

const ThemeKey: InjectionKey<Ref<'light' | 'dark'>> = Symbol('theme')

// 上层同步提供。
provide(ThemeKey, ref('light'))

// 下层读取；缺失时使用显式默认值。
const theme = inject(ThemeKey, ref('light'))
```

## Setup 兼容工具 API

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

**类型签名：** `typeof import('wevu')['useNativeInstance']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：获取当前 setup 对应的原生实例。
* 源码：`runtime/vueCompat.ts`。

### `useNativeRouter()` {#usenativerouter}

**类型签名：** `typeof import('wevu')['useNativeRouter']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：获取当前组件路径语义的 Router 对象。
* 行为：优先使用 `this.router`；不可用时回退 `this.pageRouter`；低版本基础库（`< 2.16.1`）再回退全局路由方法（`wx`/`my`/`tt`）。
* 类型：可通过声明合并 `WevuTypedRouterRouteMap.entries` 收窄 `url` 字面量；可选 `tabBarEntries` 进一步收窄 `switchTab`（`weapp-vite autoRoutes` 会自动注入 `entries`）。
* 源码：`runtime/vueCompat.ts`。

### `useNativePageRouter()` {#usenativepagerouter}

**类型签名：** `typeof import('wevu')['useNativePageRouter']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：获取当前页面路径语义的 Router 对象。
* 行为：优先使用 `this.pageRouter`；不可用时回退 `this.router`；低版本基础库（`< 2.16.1`）再回退全局路由方法（`wx`/`my`/`tt`）。
* 类型：与 `useNativeRouter()` 共享 `WevuTypedRouterRouteMap.entries / tabBarEntries` 收窄能力。
* 源码：`runtime/vueCompat.ts`。

### Router 语义与兼容建议

`Router` 能力在微信基础库 `2.16.1+` 才有原生对象。`wevu` 在低版本会自动降级到全局路由方法，所以建议你明确区分“路径语义”与“兼容语义”。

| 场景           | 推荐 API                | 相对路径基准                               |
| -------------- | ----------------------- | ------------------------------------------ |
| 页面内跳转     | `useNativePageRouter()` | 当前页面路径（更稳定）                     |
| 组件内组件路径 | `useNativeRouter()`     | 当前组件路径                               |
| 组件内页面路径 | `useNativePageRouter()` | 组件所在页面路径                           |
| 低版本降级路径 | 自动回退                | 回退为全局 `wx/my/tt` 语义（按当前激活页） |

**实践建议：**

* 需要跨版本稳定时，优先使用 `useNativePageRouter()`（尤其是页面方法被延迟调用、跨页调用时）。
* 当你明确要“相对组件目录”导航时，使用 `useNativeRouter()`。
* 对低版本必须严格一致的跳转，优先使用绝对路径（如 `/pages/foo/index`），避免依赖相对路径基准。
* 若开启 `autoRoutes`，可结合路由联合类型减少拼写错误（见 `/guide/auto-routes`）。

### `useBindModel()` {#usebindmodel}

**类型签名：** `typeof import('wevu')['useBindModel']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：创建绑定 payload（`value + onXxx`）辅助函数。
* 源码：`runtime/vueCompat.ts`。

### `useChangeModel()` {#usechangemodel}

**类型签名：** `typeof import('wevu')['useChangeModel']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：创建默认使用 `change` 事件的 model 绑定辅助函数。
* 适合：TDesign、Vant 等第三方小程序组件库中大量使用 `change` 事件的表单场景。
* 行为：等价于 `useBindModel({ event: 'change' }).model(...)` 的收敛写法。
* 源码：`runtime/vueCompat.ts`。

示例：

```vue
<script setup lang="ts">
import { reactive, useChangeModel } from 'wevu'

const formState = reactive({
  name: '',
  budget: 0,
})
const changeModel = useChangeModel()

const nameModel = changeModel<string>('formState.name')
const budgetModel = changeModel<number>('formState.budget', {
  parser: event => Number(event?.detail?.value ?? 0),
})
</script>

<template>
  <t-input v-bind="nameModel" />
  <t-slider v-bind="budgetModel" />
</template>
```

### `useIntersectionObserver()` {#useintersectionobserver}

**类型签名：** `typeof import('wevu')['useIntersectionObserver']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：在 `setup()` 中创建 `IntersectionObserver`，并在卸载时自动 `disconnect()`。
* 建议：优先用它替代 `onPageScroll + setData` 的可见性轮询逻辑。
* 源码：`runtime/intersectionObserver.ts`。

### `useElementIntersectionObserver()` {#useelementintersectionobserver}

**类型签名：** `typeof import('wevu')['useElementIntersectionObserver']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：声明式观察当前页面/组件内某个 selector 的可见性，并在卸载时自动断开。
* 适合：商品卡片曝光、懒加载、可见区域统计。
* 说明：`selector`、`enabled`、`observerOptions` 支持普通值、Ref 或 getter；当 selector 或 enabled 变化时会自动重新 observe。
* 源码：`runtime/elementIntersectionObserver.ts`。

示例：

```vue
<script setup lang="ts">
import { ref, useElementIntersectionObserver } from 'wevu'

const visible = ref(false)

useElementIntersectionObserver({
  selector: '#goods-card',
  relativeToViewport: { bottom: 80 },
  onObserve(result: any) {
    visible.value = Number(result?.intersectionRatio ?? 0) > 0
  },
})
</script>
```

### `useSelectorQuery()` {#useselectorquery}

**类型签名：** `typeof import('wevu')['useSelectorQuery']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：创建绑定当前原生实例的 `SelectorQuery` 工厂。
* 适合：需要直接调用小程序 `select()` / `selectAll()` / `exec()` 的高级节点查询。
* 源码：`runtime/selectorQuery.ts`。

### `useBoundingClientRect()` {#useboundingclientrect}

**类型签名：** `typeof import('wevu')['useBoundingClientRect']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：创建节点布局查询函数。
* 说明：默认查询单个节点；传入 `{ all: true }` 时返回节点数组。
* 源码：`runtime/selectorQuery.ts`。

### `useSelectorFields()` {#useselectorfields}

**类型签名：** `typeof import('wevu')['useSelectorFields']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：按小程序 `fields()` 语义读取节点字段。
* 说明：必须显式传入 `fields`，例如 `{ size: true, dataset: true }`。
* 源码：`runtime/selectorQuery.ts`。

### `useScrollOffset()` {#usescrolloffset}

**类型签名：** `typeof import('wevu')['useScrollOffset']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：读取 scroll-view 等可滚动节点的滚动位置。
* 说明：默认查询单个节点；传入 `{ all: true }` 时返回节点数组。
* 源码：`runtime/selectorQuery.ts`。

### `useDisposables()` {#usedisposables}

**类型签名：** `typeof import('wevu')['useDisposables']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：创建一个自动随页面/组件卸载执行的清理袋。
* 适合：定时器、请求任务、事件退订函数、`disconnect()` / `abort()` / `stop()` 一类资源清理。
* 源码：`runtime/disposables.ts`。

### `usePageLayout()` / `setPageLayout()` {#usepagelayout}

**类型签名：** `typeof import('wevu')['usePageLayout']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：读取或切换当前页面的 layout 状态。
* 说明：这是 `wevu` 根入口的页面运行时辅助能力，常与 Weapp-vite 的 `routeRules.layout`、`definePageMeta({ layout })` 配合。
* 源码：`runtime/pageLayout.ts`。

### `usePageStack()` / `getCurrentPageStackSnapshot()` {#usepagestack}

**类型签名：** `typeof import('wevu')['usePageStack']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：读取当前小程序页面栈快照。
* 返回：`currentRoute`、`stackLength`、`canGoBack` 与 `refresh()`。
* 适合：自定义导航栏返回按钮、页面层级提示、页面栈相关 UI。
* 说明：`getCurrentPageStackSnapshot()` 可在非响应式场景读取一次性快照；`usePageStack()` 必须在 `setup()` 同步阶段调用。
* 源码：`runtime/pageEnvironment.ts`。

### `useNavigationBarMetrics()` / `getNavigationBarMetrics()` {#usenavigationbarmetrics}

**类型签名：** `typeof import('wevu')['useNavigationBarMetrics']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：计算自定义导航栏需要的状态栏、导航栏和总高度。
* 返回：`statusBarHeight`、`navigationBarHeight`、`navigationHeight` 与 `refresh()`。
* 适合：自定义导航栏布局、沉浸式页面顶部安全区。
* 说明：读取 `getSystemInfoSync()` 与 `getMenuButtonBoundingClientRect()`；不可用时使用默认高度兜底。
* 源码：`runtime/pageEnvironment.ts`。

### `usePageScrollThrottle()` {#usepagescrollthrottle}

**类型签名：** `typeof import('wevu')['usePageScrollThrottle']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：在 `onPageScroll()` 基础上提供节流包装，并在卸载时自动清理。
* 适合：吸顶状态、滚动进度、轻量联动，而不是每次滚动都直接 `setData`。
* 源码：`runtime/pageScroll.ts`。

### `useUpdatePerformanceListener()` {#useupdateperformancelistener}

**类型签名：** `typeof import('wevu')['useUpdatePerformanceListener']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：注册原生 `setUpdatePerformanceListener` 监听，并在卸载时自动移除。
* 适合：排查页面/组件更新耗时与更新结果。
* 源码：`runtime/updatePerformance.ts`。

### `useAsyncPullDownRefresh()` {#useasyncpulldownrefresh}

**类型签名：** `typeof import('wevu')['useAsyncPullDownRefresh']`

**运行时说明：** 返回值或回调直接连接当前小程序宿主实例，不应把原生实例、查询器或观察器暴露为模板可序列化状态。

**示例：** 见 [本组示例](/wevu/api/setup-context#example-setup-host-tools)。

* 用途：注册异步下拉刷新回调，并在回调结束后自动停止宿主下拉刷新状态。
* 适合：页面刷新逻辑需要 `await` 请求、错误处理和统一 `stopPullDownRefresh()` 的场景。
* 说明：默认调用 `wpi.stopPullDownRefresh()`；可通过 `stopPullDownRefresh` 注入自定义停止函数，便于测试或平台差异适配。
* 源码：`runtime/pullDownRefresh.ts`。

示例：

```vue
<script setup lang="ts">
import { ref, useAsyncPullDownRefresh } from 'wevu'

const loading = ref(false)

async function reload() {
  loading.value = true
  try {
    await fetchList()
  }
  finally {
    loading.value = false
  }
}

useAsyncPullDownRefresh(reload, {
  onError(error) {
    console.warn('refresh failed:', error)
  },
})
</script>
```

### 本组示例 {#example-setup-host-tools}

节点查询、页面栈和自动清理工具可以在同一 setup 中组合。

```vue
<script setup lang="ts">
import { onReady, ref, useBoundingClientRect, useDisposables, usePageStack } from 'wevu'

const rect = ref<WechatMiniprogram.BoundingClientRectCallbackResult>()
const queryRect = useBoundingClientRect('#hero')
const disposables = useDisposables()
const pageStack = usePageStack()

onReady(async () => {
  rect.value = await queryRect()
})
disposables.add(() => console.log('cleanup', pageStack.value.length))
</script>
```

---

---
url: /wevu/api/store.md
description: 本页覆盖 wevu/store 的入口函数、Store 实例 API、Manager、Options Store 配置及公开类型。
---

# Store API（状态管理）

以下条目来源于 `packages-runtime/wevu/src/store/index.ts` 的模块导出，以及 `defineStore()` 返回实例和 `createStore()` 返回 Manager 的公共契约。

> Wevu Store 对齐 Pinia 的主要使用心智，但不是 Pinia 的完整实现。`createStore()`、Manager 安装行为、订阅时机和小程序响应式更新均以本页契约为准。

## 核心函数

### `defineStore()` {#definestore}

**类型签名：** `typeof import('wevu/store')['defineStore']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-entry)。

* 类型入口：`DefineStoreOptions`
* 用途：定义 store（setup 风格或 option 风格）。

### `createStore()` {#createstore}

**类型签名：** `typeof import('wevu/store')['createStore']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**示例：** 见 [本组示例](/wevu/api/store#example-store-entry)。

* 类型入口：`StoreManager`
* 用途：创建 store 管理器（可用于作用域隔离和测试隔离）。

### `storeToRefs()` {#storetorefs}

**类型签名：** `typeof import('wevu/store')['storeToRefs']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-entry)。

* 类型入口：`StoreToRefsResult`
* 用途：将 store 状态转换为 refs，避免解构丢失响应性。

### 本组示例 {#example-store-entry}

Setup Store 优先返回 Ref、computed 和 Action；状态解构使用 `storeToRefs()`。

```ts
import { computed, createStore, defineStore, ref, storeToRefs } from 'wevu'

const manager = createStore()
const useCounter = defineStore('counter', () => {
  const count = ref(0)
  const doubled = computed(() => count.value * 2)
  const increment = () => count.value += 1
  return { count, doubled, increment }
})

const counter = useCounter(manager)
const { count, doubled } = storeToRefs(counter)
```

## Store 实例 API

### `$id` {#store-id}

**类型签名：** `ReturnType<ReturnType<typeof defineStore>>['$id']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-instance)。

* 用途：读取 `defineStore()` 声明的 Store 标识。
* 适用：Setup Store 与 Options Store。

### `$state` {#store-state}

**类型签名：** `ReturnType<ReturnType<typeof defineStore>>['$state']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-instance)。

* 用途：读取或浅合并替换 Options Store 的响应式 state。
* 适用：仅 Options Store 的公共类型包含 `$state`；Setup Store 应直接使用 setup 返回的 state/ref。

### `$patch()` {#store-patch}

**类型签名：** `ReturnType<ReturnType<typeof defineStore>>['$patch']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-instance)。

* 用途：通过部分对象或回调函数批量修改状态。
* 订阅类型：分别触发 `patch object` 或 `patch function`。

### `$reset()` {#store-reset}

**类型签名：** `ReturnType<ReturnType<typeof defineStore>>['$reset']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-instance)。

* 用途：恢复 Store 创建时保存的初始状态快照。
* 适用：Setup Store 与 Options Store；Setup Store 中不可写的 computed/readonly ref 会被跳过。

### `$subscribe()` {#store-subscribe}

**类型签名：** `ReturnType<ReturnType<typeof defineStore>>['$subscribe']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-instance)。

* 用途：订阅 Store 状态变化，回调接收 mutation 信息和当前状态。
* 返回值：取消订阅函数。
* 选项：支持 `{ detached: true }`，用于跨页面生命周期保留订阅。

### `$onAction()` {#store-onaction}

**类型签名：** `ReturnType<ReturnType<typeof defineStore>>['$onAction']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-instance)。

* 用途：订阅 Action 调用，可通过 `after()` 和 `onError()` 监听成功结果或错误。
* 返回值：取消订阅函数。

### 本组示例 {#example-store-instance}

实例 API 可以批量更新、重置并观察 mutation 与 Action 结果。

```ts
const stopState = counter.$subscribe((mutation, state) => {
  console.log(mutation.type, state.count)
})
const stopAction = counter.$onAction(({ name, after, onError }) => {
  after(result => console.log(name, result))
  onError(error => console.error(name, error))
})

counter.$patch({ count: 2 })
counter.$patch((state) => {
  state.count += 1
})
counter.$reset()
stopState()
stopAction()
```

## Store Manager API

### `manager.install()` {#storemanager-install}

**类型签名：** `StoreManager['install']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** Pinia 通过 `app.use(pinia)` 注入 Vue App；Wevu 小程序没有同等插件挂载阶段，`install()` 仅保留兼容入口。

**示例：** 见 [本组示例](/wevu/api/store#example-store-manager)。

* 用途：保留与插件安装心智一致的接口。
* 差异：小程序环境不需要注册全局插件入口，当前实现不执行额外逻辑。

### `manager.use()` {#storemanager-use}

**类型签名：** `StoreManager['use']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-manager)。

* 用途：注册 Store 插件；每个新建 Store 会调用插件并传入 `{ store }`。
* 返回值：当前 `StoreManager`，支持链式调用。

### 本组示例 {#example-store-manager}

Manager 插件只影响之后创建的 Store，适合隔离测试和注入横切能力。

```ts
import { createStore, defineStore } from 'wevu'

const manager = createStore()
manager.use(({ store }) => {
  console.log('created store', store.$id)
})
manager.install()

const useSession = defineStore('session', { state: () => ({ token: '' }) })
const session = useSession(manager)
```

## Options Store 配置

### `state` {#options-state}

**类型签名：** `DefineStoreOptions<State, Getters, Actions>['state']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-options)。

* 类型：`() => Record<string, any>`。
* 用途：返回每个 Store 的初始响应式状态。

### `getters` {#options-getters}

**类型签名：** `DefineStoreOptions<State, Getters, Actions>['getters']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-options)。

* 用途：声明派生状态；getter 可接收 state，并可通过 `this` 访问 state、其他 getters 和 actions。

### `actions` {#options-actions}

**类型签名：** `DefineStoreOptions<State, Getters, Actions>['actions']`

**运行时说明：** 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 `storeToRefs()`。

**Vue/Pinia 差异：** API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

**示例：** 见 [本组示例](/wevu/api/store#example-store-options)。

* 用途：声明 Store 方法；Action 内的 `this` 指向 Store 实例，并会触发 `$onAction()` 订阅。

### 本组示例 {#example-store-options}

Options Store 的 getter 和 Action 可通过 `this` 访问同一个 Store。

```ts
import { defineStore } from 'wevu'

export const useCart = defineStore('cart', {
  state: () => ({ count: 0, price: 20 }),
  getters: { total: state => state.count * state.price },
  actions: {
    add(quantity = 1) { this.count += quantity },
    clear() { this.count = 0 },
  },
})
```

## Store 类型

### `StoreManager` {#storemanager}

**类型签名：**

```ts
interface StoreManager {
  install: (app: any) => void
  _stores: Map<string, any>
  use: (plugin: (context: { store: any }) => void) => StoreManager
  _plugins: Array<(context: { store: any }) => void>
}
```

**运行时说明：** 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/store` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/store#example-store-types)。

* 用途：store 根管理器类型。

### `DefineStoreOptions` {#definestoreoptions}

**类型签名：**

```ts
interface DefineStoreOptions<
  S extends Record<string, any>,
  G extends GetterTree<S>,
  A extends Record<string, any>,
> {
  state: () => S
  getters?: G & Record<string, (state: S) => any> & ThisType<S & StoreGetters<G> & A>
  actions?: A & ThisType<S & StoreGetters<G> & A>
}
```

**运行时说明：** 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/store` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/store#example-store-types)。

* 用途：定义 option 风格 store 的类型约束。

### `StoreToRefsResult` {#storetorefsresult}

**类型签名：**

```ts
type StoreToRefsResult<T extends Record<string, any>> = {
  [K in keyof T]:
  T[K] extends (...args: any[]) => any
    ? T[K]
    : T[K] extends Ref<infer V>
      ? Ref<V>
      : Ref<T[K]>
}
```

**运行时说明：** 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/store` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/store#example-store-types)。

* 用途：`storeToRefs()` 返回结果类型。

### `ActionContext` {#actioncontext}

**类型签名：**

```ts
interface ActionContext<TStore = any> {
  name: string
  store: TStore
  args: any[]
  after: (cb: (result: any) => void) => void
  onError: (cb: (error: any) => void) => void
}
```

**运行时说明：** 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/store` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/store#example-store-types)。

* 用途：`$onAction` 回调上下文。

### `ActionSubscriber` {#actionsubscriber}

**类型签名：**

```ts
interface ActionSubscriber<TStore = any> {
  (context: ActionContext<TStore>): void
}
```

**运行时说明：** 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/store` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/store#example-store-types)。

* 用途：action 订阅回调签名。

### `SubscriptionCallback` {#subscriptioncallback}

**类型签名：**

```ts
interface SubscriptionCallback<S = any> {
  (mutation: { type: MutationType, storeId: string }, state: S): void
}
```

**运行时说明：** 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/store` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/store#example-store-types)。

* 用途：状态变更订阅回调签名。

### `StoreSubscribeOptions` {#storesubscribeoptions}

**类型签名：**

```ts
interface StoreSubscribeOptions {
  /**
   * @description 是否在卸载后仍保留订阅（适用于跨页面生命周期的订阅）
   */
  detached?: boolean
}
```

**运行时说明：** 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/store` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/store#example-store-types)。

* 用途：`$subscribe` 的订阅选项类型。

### `MutationType` {#mutationtype}

**类型签名：**

```ts
type MutationType = 'patch object' | 'patch function' | 'direct'
```

**运行时说明：** 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/store` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/store#example-store-types)。

* 用途：store mutation 类型（`'patch object' | 'patch function' | 'direct'`）。

### 本组示例 {#example-store-types}

公开类型适合约束插件、订阅器和 Action 观察工具。

```ts
import type { ActionSubscriber, StoreManager, SubscriptionCallback } from 'wevu'

const logMutation: SubscriptionCallback<{ count: number }> = (mutation, state) => {
  console.log(mutation.storeId, mutation.type, state.count)
}

const logAction: ActionSubscriber = ({ name, args }) => console.log(name, args)
declare const manager: StoreManager
manager.use(({ store }) => {
  store.$subscribe(logMutation)
  store.$onAction(logAction)
})
```

---

---
url: /wevu/api/runtime-bridge.md
description: 本页仅展示面向业务与配置层的 Wevu 运行时 API。框架内部桥接函数不会在文档中展开。
---

# Runtime Bridge API（运行时配置）

本页聚焦可在业务工程中直接使用的运行时能力。内部注册与调度函数已从文档目录中移除。

## 全局默认值

### `setWevuDefaults()` {#setwevudefaults}

**类型签名：** `typeof import('wevu')['setWevuDefaults']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/runtime-bridge#example-runtime-defaults)。

* 类型入口：`WevuDefaults`
* 用途：配置 `createApp/defineComponent` 的默认行为。

### `resetWevuDefaults()` {#resetwevudefaults}

**类型签名：** `typeof import('wevu')['resetWevuDefaults']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/runtime-bridge#example-runtime-defaults)。

* 类型入口：`void`
* 用途：重置默认配置。
* 场景：测试隔离、开发调试。

### 本组示例 {#example-runtime-defaults}

全局默认值按 App 和 Component 分开配置，测试后应重置。

```ts
import { resetWevuDefaults, setWevuDefaults } from 'wevu'

setWevuDefaults({
  component: {
    setData: { autoSetDataPick: true },
    options: { multipleSlots: true },
  },
})

afterEach(() => resetWevuDefaults())
```

## setData 排除标记

### `markNoSetData()` {#marknosetdata}

**类型签名：** `typeof import('wevu')['markNoSetData']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/runtime-bridge#example-runtime-no-setdata)。

* 类型入口：`<T>(value: T) => T`
* 用途：标记对象不参与 `setData` 快照同步。

### `isNoSetData()` {#isnosetdata}

**类型签名：** `typeof import('wevu')['isNoSetData']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/runtime-bridge#example-runtime-no-setdata)。

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

### 本组示例 {#example-runtime-no-setdata}

原生实例和 SDK 对象不应进入模板快照，可以显式排除。

```ts
import { isNoSetData, markNoSetData, reactive } from 'wevu'

const player = markNoSetData(wx.createVideoContext('player'))
const state = reactive({ title: '视频详情', player })

console.log(isNoSetData(state.player))
```

## 调试记录

### `addMutationRecorder()` {#addmutationrecorder}

**类型签名：** `typeof import('wevu')['addMutationRecorder']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/runtime-bridge#example-runtime-mutations)。

* 类型入口：`MutationRecord`
* 用途：注册状态 mutation 记录器。

### `removeMutationRecorder()` {#removemutationrecorder}

**类型签名：** `typeof import('wevu')['removeMutationRecorder']`

**运行时说明：** 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 `setup()` 中调用。

**示例：** 见 [本组示例](/wevu/api/runtime-bridge#example-runtime-mutations)。

* 类型入口：`MutationRecord`
* 用途：移除状态 mutation 记录器。

### 本组示例 {#example-runtime-mutations}

Recorder 用同一个函数引用注册和移除，避免调试监听残留。

```ts
import type { MutationRecord } from 'wevu'
import { addMutationRecorder, removeMutationRecorder } from 'wevu'

const recorder = (record: MutationRecord) => console.log(record)
addMutationRecorder(recorder)

// 调试结束或实例卸载时清理。
removeMutationRecorder(recorder)
```

## 页面布局桥接

### `setPageLayout()` / `usePageLayout()` {#pagelayout}

* 类型入口：`PageLayoutState` / `WevuPageLayoutMap`
* 用途：在运行时读取或切换页面 layout。
* 说明：通常由 Weapp-vite 的 `definePageMeta({ layout })`、`routeRules.layout` 先确定初始 layout；业务侧只在需要运行时切换页面壳时调用。

### `registerPageLayoutBridge()` / `unregisterPageLayoutBridge()` {#pagelayoutbridge}

* 类型入口：`LayoutBridgeInstance`
* 用途：注册页面 layout 桥接实例。
* 说明：主要给 Weapp-vite layout 运行时与框架集成使用，业务工程通常不需要直接调用。

### `registerRuntimeLayoutHosts()` / `unregisterRuntimeLayoutHosts()` {#layouthosts}

* 类型入口：`LayoutHostBinding`
* 用途：注册 layout host 映射，供页面运行时定位当前页面壳。
* 说明：属于框架集成层 API；业务侧优先使用 `setPageLayout()`。

### `useLayoutBridge()` / `useLayoutHosts()` {#uselayoutbridge}

* 类型入口：`LayoutBridgeInstance` / `LayoutHostBinding`
* 用途：读取当前 layout bridge 或 host 绑定。
* 说明：用于 layout 组件、调试页和框架扩展，不建议普通页面直接依赖。

### `resolveLayoutBridge()` {#resolvelayoutbridge}

* 类型入口：`LayoutBridgeInstance`
* 用途：解析当前页面已注册的 layout bridge。
* 适合：需要在业务 hook 中统一访问 layout 内部宿主能力时，先定位承载宿主组件的 layout 上下文。
* 说明：普通业务页面优先使用更直接的 `resolveLayoutHost()`；只有需要自己调用 `selectComponent()` 或做兼容兜底时再使用 bridge。

### `resolveLayoutHost()` / `waitForLayoutHost()` {#resolvelayouthost}

* 类型入口：`LayoutHostResolveOptions`
* 用途：按 `layout-host` key 解析 layout 内暴露的宿主组件实例。
* 适合：Toast、Dialog、全局反馈层、抽屉等天然属于 layout 的组件。
* 说明：`resolveLayoutHost()` 同步返回当前可用实例；`waitForLayoutHost()` 会按短间隔重试，适合页面初次进入时等待 layout 宿主完成挂载。

示例：

```vue
<script setup lang="ts">
import { resolveLayoutHost } from 'wevu'

interface ToastHost {
  show: (options: { message: string }) => void
}

function showSuccess() {
  const toast = resolveLayoutHost<ToastHost>('layout-toast')
  toast?.show({ message: '操作成功' })
}
</script>
```

## 子路径边界

* `wevu/compiler` 不是 `wevu` 根入口的一部分，主要给编译工具使用。
* `wevu/router` 也不是运行时桥接页的一部分；若你需要 `createRouter()` / `useRouter()`，请直接看 [/wevu/router](/wevu/router)。
* `wevu/fetch` 与 `wevu/web-apis` 是网络/Web API 兼容入口；分别看 [/wevu/fetch](/wevu/fetch) 与 Web runtime 相关说明。

---

---
url: /wevu/api/router.md
description: wevu/router 完整 API 参考，覆盖入口函数、Router 实例、导航守卫、动态路由和公开类型。
---

# Wevu Router API

本页对应 `wevu/router` 的公开导出，以及 `createRouter()` 返回实例的公共契约。Wevu Router 对齐 Vue Router 的主要使用心智，但最终导航仍受小程序页面栈、tabBar 和宿主 API 约束。

```ts
import { createRouter, useRoute, useRouter } from 'wevu/router'
```

## Router 入口

### `createRouter()` {#createrouter}

**类型签名：** `typeof import('wevu/router')['createRouter']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 不选择 Web History 实现；配置重点是路由记录、tabBar、params 策略和宿主导航失败处理。

**示例：** 见 [本组示例](/wevu/api/router#example-router-entry)。

创建并注册默认 Router。选项支持路由记录、tabBar 路径、params 模式、重定向上限、query codec 和导航失败策略。

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

**类型签名：** `typeof import('wevu/router')['useRouter']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-entry)。

读取当前已创建的 Router；调用前必须先执行 `createRouter()`。

### `useRoute()` {#useroute}

**类型签名：** `typeof import('wevu/router')['useRoute']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 返回值随小程序页面生命周期和导航完成事件同步，不依赖浏览器 URL/history 监听。

**示例：** 见 [本组示例](/wevu/api/router#example-router-entry)。

在 `setup()` 同步阶段读取只读的当前路由状态，并随页面生命周期和导航完成事件更新。

### 本组示例 {#example-router-entry}

App 初始化阶段只创建一个 Router，页面在同步 setup 中读取它。

```ts
import { createRouter, useRoute, useRouter } from 'wevu/router'

createRouter({
  routes: [{ name: 'home', path: '/pages/home/index' }],
  tabBarEntries: ['/pages/home/index'],
})

const router = useRouter()
const route = useRoute()
console.log(router.currentRoute, route.fullPath)
```

## 原生 Router

### `useNativeRouter()` {#usenativerouter}

**类型签名：** `typeof import('wevu/router')['useNativeRouter']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**示例：** 见 [本组示例](/wevu/api/router#example-router-native)。

获取当前组件路径语义的原生 Router，直接暴露小程序导航能力。

### `useNativePageRouter()` {#usenativepagerouter}

**类型签名：** `typeof import('wevu/router')['useNativePageRouter']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**示例：** 见 [本组示例](/wevu/api/router#example-router-native)。

获取当前页面路径语义的原生 Router，适合页面级相对导航。

### 本组示例 {#example-router-native}

原生 Router 适合直接调用宿主能力；高层业务导航优先使用 `wevu/router`。

```ts
import { useNativePageRouter, useNativeRouter } from 'wevu/router'

const componentRouter = useNativeRouter()
const pageRouter = useNativePageRouter()

componentRouter.navigateTo({ url: '../detail/index?id=42' })
pageRouter.redirectTo({ url: '/pages/home/index' })
```

## 解析与导航失败

### `resolveRouteLocation()` {#resolveroutelocation}

**类型签名：** `typeof import('wevu/router')['resolveRouteLocation']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**示例：** 见 [本组示例](/wevu/api/router#example-router-resolution)。

将字符串或位置对象解析为标准路由位置，可传入当前路径处理相对地址。

### `parseQuery()` {#parsequery}

**类型签名：** `typeof import('wevu/router')['parseQuery']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**示例：** 见 [本组示例](/wevu/api/router#example-router-resolution)。

把 query 字符串解析为 `LocationQuery`。

### `stringifyQuery()` {#stringifyquery}

**类型签名：** `typeof import('wevu/router')['stringifyQuery']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**示例：** 见 [本组示例](/wevu/api/router#example-router-resolution)。

把 `LocationQueryRaw` 序列化为 query 字符串。

### `createNavigationFailure()` {#createnavigationfailure}

**类型签名：** `typeof import('wevu/router')['createNavigationFailure']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**示例：** 见 [本组示例](/wevu/api/router#example-router-resolution)。

创建带失败类型、目标位置、来源位置和原始原因的导航失败对象。

### `isNavigationFailure()` {#isnavigationfailure}

**类型签名：** `typeof import('wevu/router')['isNavigationFailure']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-resolution)。

判断异常或导航结果是否为 Wevu 导航失败，也可按失败类型过滤。

### `NavigationFailureType` {#navigationfailuretype}

**类型签名：** `typeof import('wevu/router')['NavigationFailureType']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-resolution)。

运行时失败类型常量，包含 `unknown`、`aborted`、`cancelled` 和 `duplicated`。

### 本组示例 {#example-router-resolution}

解析与失败判断可以脱离实际跳转，用于日志、预览和统一错误处理。

```ts
import { isNavigationFailure, parseQuery, resolveRouteLocation, stringifyQuery } from 'wevu/router'

const query = parseQuery('?tag=wevu&page=2')
const search = stringifyQuery({ tag: 'wevu', page: 2 })
const target = resolveRouteLocation({ path: '/pages/list/index', query })

try {
  await router.push(target)
}
catch (error) {
  if (isNavigationFailure(error)) {
    report(error.type)
  }
}
console.log(search)
```

## Router 实例

### `router.nativeRouter` {#router-nativerouter}

**类型签名：** `RouterNavigation['nativeRouter']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-instance)。

Router 内部使用的原生 `SetupContextRouter`。

### `router.options` {#router-options}

**类型签名：** `RouterNavigation['options']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-instance)。

创建 Router 时使用的只读、规范化选项快照。

### `router.currentRoute` {#router-currentroute}

**类型签名：** `RouterNavigation['currentRoute']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-instance)。

当前只读路由位置，包含 path、query、params、matched 和 redirectedFrom 等信息。

### `router.install()` {#router-install}

**类型签名：** `RouterNavigation['install']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** Vue Router 安装组件与全局属性；Wevu 只注册默认 Router，并在宿主对象支持时写入 `$router`。

**示例：** 见 [本组示例](/wevu/api/router#example-router-instance)。

注册当前 Router，并在 App 支持 `globalProperties` 时写入 `$router`。

### `router.resolve()` {#router-resolve}

**类型签名：** `RouterNavigation['resolve']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-instance)。

基于当前路由和 Router 配置解析目标位置，不执行实际跳转。

### `router.isReady()` {#router-isready}

**类型签名：** `RouterNavigation['isReady']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-instance)。

返回 Router 就绪 Promise；当前小程序实现创建后即可就绪。

### 本组示例 {#example-router-instance}

先 `resolve()` 检查目标，再根据当前页面栈决定是否执行导航。

```ts
import { useRouter } from 'wevu/router'

const router = useRouter()
await router.isReady()

const target = router.resolve({ name: 'detail', params: { id: 42 } })
console.log(router.options, router.currentRoute, target.href)
router.install()
```

## 导航方法

### `router.push()` {#router-push}

**类型签名：** `RouterNavigation['push']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-navigation)。

执行前进导航，通常映射到 `navigateTo`，也会处理 tabBar、守卫、重定向和失败分类。

### `router.replace()` {#router-replace}

**类型签名：** `RouterNavigation['replace']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-navigation)。

替换当前页面，通常映射到 `redirectTo`。

### `router.back()` {#router-back}

**类型签名：** `RouterNavigation['back']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 返回操作受当前小程序页面栈深度限制，不存在浏览器跨站 history。

**示例：** 见 [本组示例](/wevu/api/router#example-router-navigation)。

按指定层数返回；默认返回一层。

### `router.go()` {#router-go}

**类型签名：** `RouterNavigation['go']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** Vue Router 可正向或反向移动 history；Wevu 只能把负数映射为 `navigateBack`，正数无法前进。

**示例：** 见 [本组示例](/wevu/api/router#example-router-navigation)。

使用相对层数操作页面栈；小程序环境只支持可映射的返回语义。

### `router.forward()` {#router-forward}

**类型签名：** `RouterNavigation['forward']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 浏览器可沿 history 前进；小程序没有 forward 栈，该方法会返回 `aborted` 导航失败。

**示例：** 见 [本组示例](/wevu/api/router#example-router-navigation)。

保留 Vue Router 心智的前进入口；小程序没有浏览器 forward 栈，通常返回 `aborted` 失败。

### 本组示例 {#example-router-navigation}

小程序没有浏览器 forward 栈，正向导航和返回需要使用不同方法。

```ts
import { useRouter } from 'wevu/router'

const router = useRouter()
await router.push({ name: 'detail', params: { id: 42 } })
await router.replace('/pages/detail/index?id=43')
await router.back()

// go(-2) 可映射为 navigateBack；forward() 会返回 aborted 失败。
await router.go(-2)
```

## 动态路由

### `router.hasRoute()` {#router-hasroute}

**类型签名：** `RouterNavigation['hasRoute']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-dynamic)。

按名称判断路由记录是否存在。

### `router.getRoutes()` {#router-getroutes}

**类型签名：** `RouterNavigation['getRoutes']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-dynamic)。

返回当前规范化路由记录列表。

### `router.addRoute()` {#router-addroute}

**类型签名：** `RouterNavigation['addRoute']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-dynamic)。

新增顶层或子路由记录，返回移除该记录的函数。

### `router.removeRoute()` {#router-removeroute}

**类型签名：** `RouterNavigation['removeRoute']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-dynamic)。

按名称移除路由记录。

### `router.clearRoutes()` {#router-clearroutes}

**类型签名：** `RouterNavigation['clearRoutes']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-dynamic)。

清空动态路由注册表。

### 本组示例 {#example-router-dynamic}

动态注册返回清理函数，组件卸载时应主动移除临时路由。

```ts
import { onUnmounted } from 'wevu'
import { useRouter } from 'wevu/router'

const router = useRouter()
const remove = router.addRoute({ name: 'preview', path: '/pages/preview/index' })

console.log(router.hasRoute('preview'), router.getRoutes())
onUnmounted(remove)
```

## 导航守卫

### `router.beforeEach()` {#router-beforeeach}

**类型签名：** `RouterNavigation['beforeEach']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-guards)。

注册全局前置守卫，返回取消注册函数。

### `router.beforeResolve()` {#router-beforeresolve}

**类型签名：** `RouterNavigation['beforeResolve']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-guards)。

注册导航确认前守卫，运行在 `beforeEach` 和路由记录 `beforeEnter` 之后。

### `router.afterEach()` {#router-aftereach}

**类型签名：** `RouterNavigation['afterEach']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-guards)。

注册导航完成回调，可读取失败对象和小程序导航上下文。

### `router.onError()` {#router-onerror}

**类型签名：** `RouterNavigation['onError']`

**运行时说明：** 解析和守卫在 JavaScript 层执行，真正跳转仍由小程序 Router 完成，因此页面栈、tabBar 和宿主失败回调是最终边界。

**Vue Router 差异：** 调用形式接近 Vue Router，但导航最终映射到 `navigateTo`、`redirectTo`、`switchTab`、`reLaunch` 或 `navigateBack`，受页面栈和 tabBar 约束。

**示例：** 见 [本组示例](/wevu/api/router#example-router-guards)。

注册异常型导航失败处理器，返回取消注册函数。

### 本组示例 {#example-router-guards}

守卫按 beforeEach、路由 beforeEnter、beforeResolve 的顺序运行。

```ts
import { onUnmounted } from 'wevu'
import { useRouter } from 'wevu/router'

const router = useRouter()
const removeGuard = router.beforeEach((to) => {
  if (to?.meta?.requiresLogin) {
    return { name: 'login' }
  }
})
const removeAfter = router.afterEach((to, from, failure) => report({ to, from, failure }))
const removeError = router.onError((error, context) => report({ error, context }))

onUnmounted(() => {
  removeGuard()
  removeAfter()
  removeError()
})
```

## 兼容边界

* `forward()`、hash-only 导航和页面栈行为受小程序宿主限制。
* `useRoute()` 必须在 `setup()` 同步阶段调用，不能放在 `await` 之后。
* `useNativeRouter()` / `useNativePageRouter()` 直接面向宿主能力；高阶导航优先使用 `createRouter()` / `useRouter()`。
* 所有公开类型见 [Wevu Router 类型参考](/wevu/api/router-types)。
* 详细示例和迁移建议见 [wevu/router 使用指南](/wevu/router)。

---

---
url: /wevu/api/router-types.md
description: wevu/router 的公开 TypeScript 类型，覆盖位置、参数、守卫、失败、路由记录和小程序宿主 Router。
---

# Wevu Router 类型

以下类型均从 `wevu/router` 导出。运行时函数和 Router 实例方法见 [Wevu Router API](/wevu/api/router)。

## 位置与参数类型

### `RouterNavigation` {#type-routernavigation}

**类型签名：**

```ts
interface RouterNavigation {
  readonly nativeRouter: SetupContextRouter
  readonly options: Readonly<UseRouterOptions>
  readonly currentRoute: Readonly<RouteLocationNormalizedLoaded>
  install: (app?: unknown) => void
  resolve: (to: RouteLocationRaw) => RouteLocationNormalizedLoaded
  isReady: () => Promise<void>
  push: (to: RouteLocationRaw) => Promise<void | NavigationFailure>
  replace: (to: RouteLocationRaw) => Promise<void | NavigationFailure>
  back: (delta?: number) => Promise<void | NavigationFailure>
  go: (delta: number) => Promise<void | NavigationFailure>
  forward: () => Promise<void | NavigationFailure>
  hasRoute: (name: string) => boolean
  getRoutes: () => readonly RouteRecordRaw[]
  addRoute: AddRoute
  removeRoute: (name: string) => void
  clearRoutes: () => void
  beforeEach: (guard: NavigationGuard) => () => void
  beforeResolve: (guard: NavigationGuard) => () => void
  afterEach: (hook: NavigationAfterEach) => () => void
  onError: (handler: NavigationErrorHandler) => () => void
}
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

`createRouter()` 返回的完整 Router 实例类型。

### `UseRouterOptions` {#type-userouteroptions}

**类型签名：**

```ts
interface UseRouterOptions {
  tabBarEntries?: readonly (TypedRouterTabBarUrl | string)[]
  /**
   * Vue Router 对齐入口：推荐使用 `routes`
   */
  routes?: readonly RouteRecordInput[]
  /**
   * 兼容入口：支持对象 map 或路由记录数组
   */
  namedRoutes?: NamedRoutes
  paramsMode?: RouteParamsMode
  maxRedirects?: number
  parseQuery?: RouteQueryParser
  stringifyQuery?: RouteQueryStringifier
  /**
   * 异常型导航失败时是否以 Promise reject 抛出失败对象。
   *
   * - `true`：更贴近 Vue Router 心智（默认）
   * - `false`：始终以返回值形式携带失败对象
   */
  rejectOnError?: boolean
}
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

Router 创建选项，包含 routes、tabBar、params、query codec 和失败策略。

### `AddRoute` {#type-addroute}

**类型签名：**

```ts
interface AddRoute {
  (route: RouteRecordRaw): () => void
  (parentName: string, route: RouteRecordRaw): () => void
}
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

`router.addRoute()` 的重载函数类型。

### `RouteLocationRaw` {#type-routelocationraw}

**类型签名：**

```ts
type RouteLocationRaw = string | {
  path?: string
  fullPath?: string
  query?: LocationQueryRaw
  hash?: string
  name?: string
  params?: RouteParamsRaw
}
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

导航方法接受的字符串或未规范化位置对象。

### `RouteLocationNormalizedLoaded` {#type-routelocationnormalizedloaded}

**类型签名：**

```ts
interface RouteLocationNormalizedLoaded {
  path: string
  fullPath: string
  query: LocationQuery
  hash: string
  name?: string
  meta?: RouteMeta
  href?: string
  matched?: readonly RouteRecordMatched[]
  redirectedFrom?: RouteLocationRedirectedFrom
  params: RouteParams
}
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

已解析并加载的当前路由位置。

### `RouteLocationRedirectedFrom` {#type-routelocationredirectedfrom}

**类型签名：**

```ts
interface RouteLocationRedirectedFrom {
  path: string
  fullPath: string
  query: LocationQuery
  hash: string
  name?: string
  meta?: RouteMeta
  href?: string
  matched?: readonly RouteRecordMatched[]
  params: RouteParams
}
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

重定向前原始位置的只读快照结构。

### `LocationQuery` {#type-locationquery}

**类型签名：**

```ts
type LocationQuery = Record<string, LocationQueryValue | LocationQueryValue[]>
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

规范化后的 query 对象。

### `LocationQueryRaw` {#type-locationqueryraw}

**类型签名：**

```ts
type LocationQueryRaw = Record<string, LocationQueryValueRaw | LocationQueryValueRaw[]>
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

导航输入可接受的原始 query 对象。

### `LocationQueryValue` {#type-locationqueryvalue}

**类型签名：**

```ts
type LocationQueryValue = string | null
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

规范化 query 的单值类型。

### `LocationQueryValueRaw` {#type-locationqueryvalueraw}

**类型签名：**

```ts
type LocationQueryValueRaw = LocationQueryValue | number | boolean | undefined
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

原始 query 可接受的单值类型。

### `RouteParams` {#type-routeparams}

**类型签名：**

```ts
type RouteParams = Record<string, RouteParamValue | RouteParamValue[]>
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

规范化后的命名路由 params 对象。

### `RouteParamsRaw` {#type-routeparamsraw}

**类型签名：**

```ts
type RouteParamsRaw = Record<string, RouteParamValueRaw | RouteParamValueRaw[]>
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

命名路由输入可接受的原始 params 对象。

### `RouteParamValue` {#type-routeparamvalue}

**类型签名：**

```ts
type RouteParamValue = string
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

规范化 params 的字符串值类型。

### `RouteParamValueRaw` {#type-routeparamvalueraw}

**类型签名：**

```ts
type RouteParamValueRaw = RouteParamValue | number | boolean | null | undefined
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

原始 params 可接受的单值类型。

### `RouteParamsMode` {#type-routeparamsmode}

**类型签名：**

```ts
type RouteParamsMode = 'loose' | 'strict'
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

params 缺失或多余时采用的 `loose` 或 `strict` 策略。

### `RouteQueryParser` {#type-routequeryparser}

**类型签名：**

```ts
type RouteQueryParser = (search: string) => LocationQueryRaw | LocationQuery
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

自定义 query 解析函数签名。

### `RouteQueryStringifier` {#type-routequerystringifier}

**类型签名：**

```ts
type RouteQueryStringifier = (query: LocationQueryRaw | LocationQuery) => string
```

**运行时说明：** 该类型用于约束 位置与参数类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-location)。

自定义 query 序列化函数签名。

### 本组示例 {#example-router-types-location}

用公开类型约束业务导航函数，避免手写字符串结构。

```ts
import type { RouteLocationRaw, RouteParamsRaw, UseRouterOptions } from 'wevu/router'

const params: RouteParamsRaw = { id: 42 }
const target: RouteLocationRaw = { name: 'detail', params }
const options: UseRouterOptions = {
  routes: [{ name: 'detail', path: '/pages/detail/:id' }],
}
```

## 守卫与失败类型

### `NavigationFailure` {#type-navigationfailure}

**类型签名：**

```ts
interface NavigationFailure extends Error {
  readonly __wevuNavigationFailure: true
  readonly type: NavigationFailureTypeValue
  readonly to?: RouteLocationNormalizedLoaded
  readonly from?: RouteLocationNormalizedLoaded
  readonly cause?: unknown
}
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

带类型、目标、来源和 cause 的导航失败对象。

### `NavigationFailureTypeValue` {#type-navigationfailuretypevalue}

**类型签名：**

```ts
type NavigationFailureTypeValue = (typeof NavigationFailureType)[keyof typeof NavigationFailureType]
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

`NavigationFailureType` 所有运行时值的联合类型。

### `NavigationMode` {#type-navigationmode}

**类型签名：**

```ts
type NavigationMode = 'push' | 'replace' | 'back'
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

导航执行模式：`push`、`replace` 或 `back`。

### `NavigationRedirect` {#type-navigationredirect}

**类型签名：**

```ts
interface NavigationRedirect {
  to: RouteLocationRaw
  replace?: boolean
}
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

守卫或路由记录返回的重定向描述。

### `NavigationGuard` {#type-navigationguard}

**类型签名：**

```ts
type NavigationGuard = (
  to: RouteLocationNormalizedLoaded | undefined,
  from: RouteLocationNormalizedLoaded,
  context?: NavigationGuardContext,
) => NavigationGuardResult | Promise<NavigationGuardResult>
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

前置守卫函数签名。

### `NavigationGuardResult` {#type-navigationguardresult}

**类型签名：**

```ts
type NavigationGuardResult = void | boolean | NavigationFailure | RouteLocationRaw | NavigationRedirect
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

守卫可返回的继续、取消、失败位置或重定向结果。

### `NavigationGuardContext` {#type-navigationguardcontext}

**类型签名：**

```ts
interface NavigationGuardContext {
  readonly mode: NavigationMode
  readonly to?: RouteLocationNormalizedLoaded
  readonly from: RouteLocationNormalizedLoaded
  readonly nativeRouter: SetupContextRouter
}
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

前置守卫获得的小程序导航上下文。

### `NavigationAfterEach` {#type-navigationaftereach}

**类型签名：**

```ts
type NavigationAfterEach = (
  to: RouteLocationNormalizedLoaded | undefined,
  from: RouteLocationNormalizedLoaded,
  failure?: NavigationFailure,
  context?: NavigationAfterEachContext,
) => void | Promise<void>
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

导航完成回调签名。

### `NavigationAfterEachContext` {#type-navigationaftereachcontext}

**类型签名：**

```ts
interface NavigationAfterEachContext {
  readonly mode: NavigationMode
  readonly to?: RouteLocationNormalizedLoaded
  readonly from: RouteLocationNormalizedLoaded
  readonly nativeRouter: SetupContextRouter
  readonly failure?: NavigationFailure
}
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

导航完成时的模式、位置、原生 Router 和失败信息。

### `NavigationErrorHandler` {#type-navigationerrorhandler}

**类型签名：**

```ts
type NavigationErrorHandler = (
  error: unknown,
  context: NavigationErrorContext,
) => void | Promise<void>
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

异常型导航失败处理函数签名。

### `NavigationErrorContext` {#type-navigationerrorcontext}

**类型签名：**

```ts
interface NavigationErrorContext {
  readonly mode: NavigationMode
  readonly to?: RouteLocationNormalizedLoaded
  readonly from: RouteLocationNormalizedLoaded
  readonly nativeRouter: SetupContextRouter
  readonly failure: NavigationFailure
}
```

**运行时说明：** 该类型用于约束 守卫与失败类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-guards)。

错误处理器获得的导航上下文。

### 本组示例 {#example-router-types-guards}

守卫类型会同时约束目标、来源、上下文和返回值。

```ts
import type { NavigationAfterEach, NavigationGuard, NavigationGuardContext } from 'wevu/router'

const guard: NavigationGuard = (to, from, context?: NavigationGuardContext) => {
  if (context?.mode === 'back') {
    return true
  }
  return to?.meta?.disabled ? false : undefined
}

const afterEach: NavigationAfterEach = (to, from, failure) => {
  console.log(to, from, failure)
}
```

## 路由记录类型

### `NamedRouteRecord` {#type-namedrouterecord}

**类型签名：**

```ts
interface NamedRouteRecord {
  name: string
  path: string
}
```

**运行时说明：** 该类型用于约束 路由记录类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-records)。

最小命名路由记录，包含 name 和 path。

### `NamedRoutes` {#type-namedroutes}

**类型签名：**

```ts
type NamedRoutes = Readonly<Record<string, string>> | readonly RouteRecordRaw[]
```

**运行时说明：** 该类型用于约束 路由记录类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-records)。

命名路由对象 map 或路由记录数组。

### `RouteMeta` {#type-routemeta}

**类型签名：**

```ts
type RouteMeta = Record<string, unknown>
```

**运行时说明：** 该类型用于约束 路由记录类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-records)。

路由记录自定义元信息。

### `RouteRecordInput` {#type-routerecordinput}

**类型签名：**

```ts
interface RouteRecordInput {
  name?: string
  path: string
  meta?: RouteMeta
  alias?: string | readonly string[]
  children?: readonly RouteRecordInput[]
  beforeEnter?: NavigationGuard | readonly NavigationGuard[]
  redirect?: RouteRecordRedirect
}
```

**运行时说明：** 该类型用于约束 路由记录类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-records)。

创建 Router 或添加动态路由时接受的记录结构。

### `RouteRecordRaw` {#type-routerecordraw}

**类型签名：**

```ts
interface RouteRecordRaw extends Omit<RouteRecordInput, 'name' | 'children'>, NamedRouteRecord {
  children?: readonly RouteRecordRaw[]
}
```

**运行时说明：** 该类型用于约束 路由记录类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-records)。

具有必填 name 的规范化公开路由记录。

### `RouteRecordMatched` {#type-routerecordmatched}

**类型签名：**

```ts
interface RouteRecordMatched {
  name: string
  path: string
  aliasPath?: string
  meta?: RouteMeta
}
```

**运行时说明：** 该类型用于约束 路由记录类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-records)。

当前路由 `matched` 中的匹配记录快照。

### `RouteRecordRedirect` {#type-routerecordredirect}

**类型签名：**

```ts
type RouteRecordRedirect = RouteLocationRaw | NavigationRedirect | ((
  to: RouteLocationNormalizedLoaded,
  from: RouteLocationNormalizedLoaded,
) => RouteLocationRaw | NavigationRedirect | Promise<RouteLocationRaw | NavigationRedirect>)
```

**运行时说明：** 该类型用于约束 路由记录类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**Vue Router 差异：** 类型名称对齐 Vue Router 的常用概念，但字段只表达小程序路径、query、params、页面栈和原生 Router 能力，不包含浏览器 history/hash 状态。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-records)。

路由记录的静态或函数式重定向类型。

### 本组示例 {#example-router-types-records}

路由记录可以组合 meta、alias、children、守卫和重定向。

```ts
import type { RouteRecordInput } from 'wevu/router'

const routes: RouteRecordInput[] = [{
  name: 'profile',
  path: '/pages/profile/:id',
  alias: '/profile/:id',
  meta: { requiresLogin: true },
  children: [{ name: 'profile-settings', path: 'settings' }],
}]
```

## 小程序 Router 类型

### `SetupContextRouter` {#type-setupcontextrouter}

**类型签名：**

```ts
interface SetupContextRouter {
  switchTab: (option: MiniProgramRouterSwitchTabOption) => ReturnType<MiniProgramRouter['switchTab']>
  reLaunch: (option: MiniProgramRouterReLaunchOption) => ReturnType<MiniProgramRouter['reLaunch']>
  redirectTo: (option: MiniProgramRouterRedirectToOption) => ReturnType<MiniProgramRouter['redirectTo']>
  navigateTo: (option: MiniProgramRouterNavigateToOption) => ReturnType<MiniProgramRouter['navigateTo']>
  navigateBack: MiniProgramRouter['navigateBack']
}
```

**运行时说明：** 该类型用于约束 小程序 Router 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-native)。

Wevu `setup()` 上下文提供的原生小程序 Router。

### `RouterNavigateToOption` {#type-routernavigatetooption}

**类型签名：**

```ts
type RouterNavigateToOption = MiniProgramRouterNavigateToOption
```

**运行时说明：** 该类型用于约束 小程序 Router 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-native)。

类型安全的 `navigateTo` 选项。

### `RouterRedirectToOption` {#type-routerredirecttooption}

**类型签名：**

```ts
type RouterRedirectToOption = MiniProgramRouterRedirectToOption
```

**运行时说明：** 该类型用于约束 小程序 Router 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-native)。

类型安全的 `redirectTo` 选项。

### `RouterReLaunchOption` {#type-routerrelaunchoption}

**类型签名：**

```ts
type RouterReLaunchOption = MiniProgramRouterReLaunchOption
```

**运行时说明：** 该类型用于约束 小程序 Router 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-native)。

类型安全的 `reLaunch` 选项。

### `RouterSwitchTabOption` {#type-routerswitchtaboption}

**类型签名：**

```ts
type RouterSwitchTabOption = MiniProgramRouterSwitchTabOption
```

**运行时说明：** 该类型用于约束 小程序 Router 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-native)。

类型安全的 `switchTab` 选项。

### `TypedRouterUrl` {#type-typedrouterurl}

**类型签名：**

```ts
type TypedRouterUrl = RouterUrl<ResolveTypedRouterEntries>
```

**运行时说明：** 该类型用于约束 小程序 Router 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-native)。

由项目路由类型映射推导出的页面 URL。

### `TypedRouterTabBarUrl` {#type-typedroutertabbarurl}

**类型签名：**

```ts
type TypedRouterTabBarUrl = RouterPathUrl<ResolveTypedRouterTabBarEntries>
```

**运行时说明：** 该类型用于约束 小程序 Router 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-native)。

由项目路由类型映射推导出的 tabBar URL。

### `WevuTypedRouterRouteMap` {#type-wevutypedrouterroutemap}

**类型签名：**

```ts
interface WevuTypedRouterRouteMap {}
```

**运行时说明：** 该类型用于约束 小程序 Router 类型 的公开契约，不会在运行时产生额外对象；应从 `wevu/router` 以 `import type` 导入。

**示例：** 见 [本组示例](/wevu/api/router-types#example-router-types-native)。

供项目声明合并扩展的类型路由映射。

### 本组示例 {#example-router-types-native}

项目可以通过声明合并收窄原生 Router 接受的 URL。

```ts
import type { TypedRouterUrl, WevuTypedRouterRouteMap } from 'wevu/router'

declare module 'wevu/router' {
  interface WevuTypedRouterRouteMap {
    entries: '/pages/home/index' | '/pages/detail/index'
    tabBarEntries: '/pages/home/index'
  }
}

const url: TypedRouterUrl<WevuTypedRouterRouteMap> = '/pages/detail/index'
```

---

---
url: /wevu/api/types.md
description: 本页仅保留业务开发最常用的公开类型。内部运行时类型不会在文档中展开。
---

# Type Reference（类型总览）

本页提供最常用的公开类型速查，避免把内部实现类型暴露为常规 API。

## 组件与应用

### `RuntimeApp` {#runtimeapp}

`createApp()` 的返回类型，公开 `mount/use/provide/onUnmount/unmount/config/version`。它不是 Vue DOM App 的完整类型，不包含 `component/directive/mixin/runWithContext`。

### `AppConfig` {#appconfig}

Wevu 应用配置类型，当前公开 `globalProperties: Record<string, any>`。

### `WevuPlugin` {#wevuplugin}

插件可以是 `(app, ...options) => any` 函数，也可以是带 `install(app, ...options)` 的对象。

### `CreateAppOptions` {#createappoptions}

`createApp()` 的参数类型。

### `DefineComponentOptions` {#definecomponentoptions}

`defineComponent()` 的参数类型。

### `ComponentDefinition` {#componentdefinition}

`defineComponent()` 返回定义结构类型。

### `SetupContext` {#setupcontext}

`setup(props, ctx)` 中 `ctx` 的类型。

### `RuntimeInstance` {#runtimeinstance}

页面/组件运行时实例类型。

### `MiniProgram*` / `HostMiniProgram*` {#miniprogram-types}

小程序宿主中立类型与底层宿主类型别名，例如 `MiniProgramRouter`、`MiniProgramSelectorQuery`、`MiniProgramIntersectionObserver`、`MiniProgramBoundingClientRectResult`、`HostMiniProgramPageScrollOption`。

推荐业务代码优先使用 `MiniProgram*` 命名；只有在明确需要表达底层宿主来源时再使用 `HostMiniProgram*`。

## 响应式与监听

### `PropType<T>` {#proptype}

用于给运行时 props 构造器附加 TypeScript 值类型，语义与 Vue `PropType<T>` 对齐。

### `MaybeRef<T>` {#mayberef}

表示普通值、`Ref`、`ShallowRef` 或可写计算值，适合声明可接受响应式输入的组合式函数。

### `Ref` {#ref-type}

基础响应式引用类型。

### `ShallowRef` {#shallowref-type}

浅层响应式引用类型。

### `WatchOptions` {#watchoptions}

`watch/watchEffect` 配置类型。

### `WatchStopHandle` {#watchstophandle}

watch 停止句柄类型。

### `MaybeRefOrGetter` {#maybereforgetter}

可接收值、Ref 或 getter 的联合类型。

### `ExtractPropTypes<T>` {#extractproptypes}

从 Wevu `ComponentPropsOptions` 推导组件内部可见的 props 类型。

### `ExtractPublicPropTypes<T>` {#extractpublicproptypes}

从 Wevu props 配置推导父组件可传入的公开 props 类型。

### `ComponentCustomProps` {#componentcustomprops}

沿用 Vue 的组件自定义 props 扩展类型，可通过模块增强补充跨组件属性。

## Store

### `StoreManager` {#storemanager}

store 根管理器类型。

### `DefineStoreOptions` {#definestoreoptions}

defineStore 选项类型。

### `StoreToRefsResult` {#storetorefsresult}

`storeToRefs()` 返回类型。

### `MutationType` {#mutationtype}

store mutation 类型。

## 运行时配置

### `WevuDefaults` {#wevudefaults}

`setWevuDefaults()` 配置类型。

### `ModelBinding` {#modelbinding}

`defineModel/useModel/useBindModel` 相关绑定类型。

### `ModelBindingOptions` / `ModelBindingPayload` {#modelbindingpayload}

`useBindModel()`、`useChangeModel()` 生成 value + handler payload 时使用的参数与返回类型。

### `TriggerEventOptions` {#triggereventoptions}

事件触发选项类型。

### `UseElementIntersectionObserverOptions` {#useelementintersectionobserveroptions}

`useElementIntersectionObserver()` 的参数类型。

### `UseBoundingClientRectOptions` / `UseSelectorFieldsOptions` / `UseScrollOffsetOptions` {#selector-query-options}

节点查询相关组合式 API 的参数类型。

### `PageStackSnapshot` / `UsePageStackOptions` {#pagestack-types}

页面栈快照和 `usePageStack()` 配置类型。

### `NavigationBarMetrics` / `UseNavigationBarMetricsOptions` {#navigationbar-types}

自定义导航栏尺寸快照和 `useNavigationBarMetrics()` 配置类型。

### `UseAsyncPullDownRefreshOptions` {#async-pulldown-types}

`useAsyncPullDownRefresh()` 的错误处理和停止刷新函数配置类型。

## 说明

更多底层与内部类型仍可在类型声明文件中找到，但不属于推荐直接依赖的公共 API 文档范围。

---

---
url: /wevu.md
description: >-
  Wevu 是面向小程序的轻量运行时，为 weapp-vite 的 Vue SFC 与组合式开发提供响应式、生命周期、Store 与最小化 setData
  更新能力。
---

# Wevu 概览

`wevu` 是一个面向小程序（以微信小程序为主）的轻量运行时。可以把它看作“把 Vue 3 的响应式心智模型带到小程序里”，但不引入 Virtual DOM，而是用快照 diff 来尽量减少 `setData` 的更新量。

:::warning 安装方式
`wevu` 在 `weapp-vite` 项目里通常建议安装在 `devDependencies` 中：

```sh
pnpm add -D wevu
```

这样更符合当前 `weapp-vite` 的产物策略与模板默认值。若你是在非 `weapp-vite` 场景单独消费 `wevu`，再根据自己的发布方式决定依赖落位。
:::

## 1. Wevu 主要提供什么

它主要提供：

* Vue 3 风格的响应式（`ref` / `reactive` / `computed` / `watch`）
* 基于快照 diff 的最小化 `setData` 更新
* 类 Pinia 的 Store（状态管理）

Wevu 不改变小程序“数据驱动 + 模板渲染”的基本模型：你仍然写 WXML/WXSS（或配合 Weapp-vite 用 Vue SFC 编写模板/样式/配置），但业务逻辑可以用熟悉的 Composition API 组织起来。

## 2. 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`
* “项目应该先看哪一层文档？” → 先看 `/guide/` 和 `/config/`；那里解决的是编译与工程问题，不是运行时问题。

如果你是在 `weapp-vite` 项目里让 AI 协助修改 Wevu 代码，建议再加一个前置顺序：

1. 先读项目根目录 `AGENTS.md`
2. 再读 `node_modules/weapp-vite/dist/docs/wevu-authoring.md`
3. 最后才进入具体的 `pages/components/stores`

这样 AI 更容易先遵守小程序运行时约束，而不是直接套用 Vue Web 的默认写法。

## 3. Wevu 不是什么

* 它不是浏览器 DOM 运行时，也不是把 Vue 3 完整搬进小程序。
* 它不依赖 Virtual DOM，而是围绕小程序的 `setData` 模型做响应式与快照 diff。
* 它也不替代 `weapp-vite` 的编译能力。SFC、WXML、JSON、WXSS 的转换仍然由编译侧负责。

## 4. 诞生的小故事

这段背景不影响你上手，但能帮助你理解 Wevu 为什么会长成现在这样：

* 最初想叫 `wevue`，但 npm 包名已被占用，后来才收敛成现在的 `wevu`。
* 在给 `weapp-vite` 补齐 Vue SFC 支持时，调研过社区现有方案，但无论编译链还是运行时语义，都很难直接贴合小程序场景。
* 最后选择围绕小程序本身的运行模型重新组织这套能力：借鉴 Vue 3 的响应式心智，但不照搬浏览器渲染栈，而是把重点放在 `setData`、页面生命周期和小程序平台约束上。

如果你把 Wevu 理解成“面向小程序约束重新取舍过的一套 Vue 风格运行时”，通常会比把它理解成“Vue 3 的缩小版”更准确。

## 5. 你会用到的能力

* **响应式与调度**：与 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/router` 导入；`wevu/compiler` 仅供 Weapp-vite 等编译侧工具使用（非稳定业务 API）。
:::

## 6. 其他子路径导出

除了 `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 类型系统使用的入口

## 7. 开发产物与源码调试

`wevu` 默认入口指向压缩后的生产产物，用来降低小程序包体积。发布包里也会同时包含一份未压缩并带 sourcemap 的开发产物：

* 支持 `development` export condition 的构建器会在开发模式下优先解析到 `dist/dev/*`。
* 需要手动切换时，可以把 `wevu` alias 到 `wevu/dev`，也可以把 `wevu/router` alias 到 `wevu/dev/router` 等同名开发入口。
* 生产构建应继续使用默认入口，避免 `dist/dev/*` 进入正式小程序包。

例如只在本地排查 Wevu 运行时源码时，可以临时改成：

```ts
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      'wevu/router': 'wevu/dev/router',
      'wevu/store': 'wevu/dev/store',
      'wevu': 'wevu/dev',
    },
  },
})
```

排查结束后移除 alias，让正式构建回到默认压缩产物。

## 8. 已弃用 API 提示

当前源码里已明确标记为弃用、但仍保留导出的公开 API 主要是：

* `provideGlobal()` / `injectGlobal()`

它们仅为兼容旧代码保留。新代码请优先使用：

* `provide()` / `inject()`：局部依赖注入
* `defineStore()` / `createStore()`：稳定全局共享状态

> **注意**：`useRouter()` 不属于 `wevu` 根入口；如果你要使用高阶导航，请从 [`wevu/router`](/wevu/router) 导入。

## 9. 编译侧桥接（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。

## 10. 推荐学习顺序（按“最短上手 → 深入理解”）

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/)
* [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)

## 10. 速查表

| 主题            | 结论                                         |
| --------------- | -------------------------------------------- |
| `wevu` 是什么   | 小程序运行时层                               |
| `wevu` 不是什么 | 浏览器 DOM Runtime / 完整 Vue Web Runtime    |
| API 从哪导入    | 基础 API 从 `wevu`，高阶路由从 `wevu/router` |
| 当前已弃用 API  | `provideGlobal()` / `injectGlobal()`         |

## 11. 扩展阅读

* [为什么没有使用 @vue/runtime-core 的 createRenderer 来实现](/wevu/why-not-runtime-core-create-renderer)
* [Wevu 中的 setData 什么时候触发？](/wevu/when-setdata-triggers)

## 12. 参考资源

| 主题       | 推荐入口                                  |
| ---------- | ----------------------------------------- |
| API 首页   | [Wevu API](/wevu/api/)                    |
| 高阶导航   | [wevu/router](/wevu/router)               |
| Vue SFC    | [wevu/vue-sfc](/wevu/vue-sfc/)            |
| 兼容性说明 | [wevu/compatibility](/wevu/compatibility) |

---

---
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 安装位置
在 `weapp-vite` 项目里，`wevu` 通常建议安装在 `devDependencies` 中，因此上面的示例使用了 `-D` / `--save-dev`。

这是当前 `weapp-vite + wevu` 模板与常见工程实践的推荐组合；如果你是在非 `weapp-vite` 场景单独消费 `wevu`，应按自己的发布方式决定依赖落位。
:::

:::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: /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`）。

两者的处理路径可以简单理解为：

* `props`：先由 Wevu 归一化，再生成最终注册给原生 `Component()` 的 `properties`
* `properties`：作为原生字段直接保留参与注册，不再按 Vue 风格 `props` 规则重新转换

如果同时声明了 `props` 和 `properties`，当前实现会优先保留显式传入的 `properties`。

SFC 中静态可识别的组件函数 prop 绑定默认会进入 `setData` 快照，例如声明 `props: { callback: Function }` 后通过 `:callback="callback"` 传递。动态绑定或手写组件无法被编译器精确标记时，可使用组件级 `allowFunctionProps: true` 全量放行；需要恢复严格过滤时，可设置 `allowFunctionProps: false`。

如果你使用 Weapp-vite 的 SFC 编译产物，通常会走 `createWevuComponent(options)`（见下节），并直接携带小程序 `properties`。

#### defineProps 泛型到 properties 的映射

`<script setup>` 的 `defineProps<T>()` 会先被 Vue 编译器推导成 runtime `props`，再由 Wevu 归一化为小程序 `properties`。

完整链路可以这样理解：

1. 你在 SFC 中写 `defineProps<T>()`
2. Vue 编译器先把它变成运行时可识别的 `props` 选项
3. Weapp-vite / Wevu 编译产物调用 `createWevuComponent(options)`
4. `createWevuComponent()` 再把 `props` 归一化成原生 `properties`
5. 最终调用原生 `Component()` 完成组件注册

也就是说，SFC 场景下你写的是 Vue 风格 `defineProps`，但真正落到小程序运行时的仍然是原生 `properties`。

如果编译产物里已经显式带了 `properties`，那么会直接保留这份 `properties` 去注册，不再回退到 `props` 归一化结果。

归一化规则（对齐小程序 `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/wevu#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()` 不会向上查找“祖先组件”；组件内注入只能命中“当前实例提供的值”，否则回落到全局存储。
:::

> \[!WARNING]
> `provideGlobal()` / `injectGlobal()` 仅为兼容旧代码保留，不建议在新项目中继续扩散。
> 若需要全局共享，优先评估 store；若只是当前 setup/实例上下文内共享，优先使用 `provide()` / `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: /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`；若显式传了 `properties`，则保留这份原生定义，不再使用 `props` 生成结果。                                                                                                                    |
| `relations`        | `defineComponent({ relations: { ... } })`                                                                                         | 原样透传。                                                                                                                                                                                                                               |

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

## props 和 properties：相同点与区别

两者本质上都在描述“组件对外暴露的输入契约”：

* 父组件都可以通过属性把值传进来。
* 子组件里都可以通过 `setup(props)` / `ctx.props` 读取。
* 最终都会落到小程序组件实例的 `properties` 上参与更新。

也就是说，`props` 和 `properties` 在“能不能接收入参”这件事上并不是两套独立机制，而是同一层能力的两种声明方式。

### 相同点

* 都用于声明组件可接收的输入参数。
* 都会参与父传子更新，值变化后可在组件内拿到最新结果。
* 都支持类型、默认值等入参约束能力。
* 都能在 Wevu 组件中被 `setup(props)` 统一消费。

### 不同点

* `props` 是 Wevu / Vue 风格写法，适合新项目和 Vue SFC 心智。
* `properties` 是小程序原生写法，适合迁移已有原生组件，或需要直接复用原生定义时使用。
* `props` 更方便配合 `defineProps`、`withDefaults`、TypeScript 类型推导一起使用。
* `properties` 更贴近原生小程序文档、原生组件库和历史代码结构。
* `props` 在组件注册前会被 Wevu 归一化，最终转换成原生 `properties` 再传给 `Component()`。
* `properties` 本身就是原生字段，Wevu 会直接保留这份定义参与注册，不再按 Vue 风格 `props` 规则重新转换。

### 最终注册到原生时会发生什么

可以把它简单理解成两条路径：

* 写 `props`：`props` -> Wevu `normalizeProps()` -> 原生 `properties` -> `Component()`
* 写 `properties`：原生 `properties` -> Wevu 保留原定义 -> `Component()`

其中 `props` 转换为原生 `properties` 时，主要会做这些归一化：

* `default` 会被转换成原生 `value`
* 多类型 `type: [String, Number]` 会收敛成主 `type` + `optionalTypes`
* 非小程序原生支持的类型会被过滤，必要时降级为 `type: null`
* `required` 这类 Vue runtime `props` 语义不会进入最终的原生 `properties`

而 `properties` 则更接近“原样透传”：

* 你写的 `type`、`value`、`optionalTypes`、`observer` 会直接作为原生组件属性定义使用
* Wevu 不会再把它当成 Vue `props` 重新做一轮规范化
* 如果同时写了 `props` 和 `properties`，会优先采用 `properties`

### 代码示例

`props` 写法：

```ts
import { defineComponent } from 'wevu'

export default defineComponent({
  props: {
    title: String,
    count: {
      type: Number,
      default: 0,
    },
  },
  setup(props) {
    console.log(props.title, props.count)
  },
})
```

`properties` 写法：

```ts
import { defineComponent } from 'wevu'

export default defineComponent({
  properties: {
    title: String,
    count: {
      type: Number,
      value: 0,
    },
  },
  setup(props) {
    console.log(props.title, props.count)
  },
})
```

### 优先级与选择建议

* 新写的 Wevu 组件，推荐优先使用 `props`。
* `<script setup>` 场景，推荐直接使用 `defineProps`。
* 从原生小程序迁移时，如果已有成熟的 `properties` 定义，可以先保留，逐步迁移到 `props`。
* 不建议同时定义 `props` 和 `properties`；如果同时存在，当前实现会优先采用显式传入的 `properties`。

## 函数 prop（显式配置）

小程序运行时可以把函数值放在 data 中并作为组件 property 传递。Wevu 会把 `setup()` 返回的函数提升为 methods，同时由 SFC 编译器标记模板里静态可识别的组件 prop 绑定路径，让这些函数按小程序语义进入 `setData` 快照。

标识符或普通成员路径会被编译器记录为候选路径，例如 `:callback="callback"`。如果需要透传动态函数 prop，例如 `:handler="handlers.save"` 或 `:handler="callbacks[id]"`，请在 `weapp.vue.template.functionPropNames` 中显式声明对应 prop 名称；该配置支持字符串精确匹配和正则表达式匹配：

```ts
export default defineConfig({
  weapp: {
    vue: {
      template: {
        functionPropNames: ['handler', /^on[A-Z]/],
      },
    },
  },
})
```

```ts
defineComponent({
  props: {
    callback: Function,
  },
  setup() {
    function callback(value: string) {
      console.log(value)
    }

    return { callback }
  },
})
```

动态绑定（例如 `v-bind="props"`）和手写非 SFC 组件无法被编译器精确标记；这类场景可设置 `allowFunctionProps: true` 全量放行。需要恢复严格过滤时，可设置 `allowFunctionProps: false`。

## 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: /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: /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 写法的相同点/不同点

迁移相关内容已独立成章节，请阅读：[从原生小程序迁移到 Weapp-vite / Wevu（详细指南）](/wevu/migration/from-native-to-vue-sfc)。如果你只想先保留原生页面并接入 `weapp-vite` 工具链，也从这篇开始判断路线。

---

---
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: /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>
```

这里要注意字段分层：

* `virtualHost`、`multipleSlots`、`styleIsolation` 这类原生 `ComponentOptions` 字段，放在 `options`
* `externalClasses`、`behaviors`、`relations` 这类组件顶层字段，不要塞进 `options`

错误示例：

```vue
<script setup lang="ts">
defineOptions({
  options: {
    externalClasses: ['class'],
  },
})
</script>
```

正确示例：

```vue
<script setup lang="ts">
defineOptions({
  externalClasses: ['class'],
  options: {
    virtualHost: true,
    styleIsolation: 'apply-shared',
  },
})
</script>
```

如果你想把组件宿主节点虚拟化，这就是最直接的写法。若项目里大多数组件都需要 `virtualHost: true`，更推荐在 [/config/wevu](/config/wevu) 里统一配置：

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

export default defineConfig({
  weapp: {
    wevu: {
      defaults: {
        component: {
          options: {
            virtualHost: true,
          },
        },
      },
    },
  },
})
```

补充说明：

* 这个全局默认值只会作用于组件，不会把页面默认改成 `virtualHost: true`
* 页面若确实需要开启，请在页面内显式声明 `options.virtualHost`
* 局部组件自己写的 `options.virtualHost` 优先级高于全局默认值

## `virtualHost` 与样式透传边界

`virtualHost: true` 经常和 `styleIsolation: 'apply-shared'` 一起使用，但这两个配置解决的问题并不一样：

* `virtualHost: true`：隐藏组件宿主节点
* `styleIsolation: 'apply-shared'`：允许页面样式影响组件内部

它们**不会**自动提供 Vue Web 里的“根节点 `class/style` fallthrough”。

也就是说，下面这种写法并不意味着组件内部根节点一定会变红：

```vue
<MyCard class="text-red-500" />
```

如果组件没有显式把外部类名或样式绑定到内部根节点，那么：

* 组件标签上的 `class` 仍然只是挂在组件标签上
* `virtualHost: true` 时宿主节点不可见，这个 `class` 没有可见挂载点
* `styleIsolation: 'apply-shared'` 也不会帮你自动把这个 `class` 合并进内部根节点

### 推荐写法

如果你希望组件支持外部样式，推荐显式设计 API，而不是依赖隐式透传。

写法 1：外部类名

```vue
<script setup lang="ts">
defineOptions({
  externalClasses: ['custom-class'],
})
</script>

<template>
  <view class="card custom-class">
    <slot />
  </view>
</template>
```

父组件：

```vue
<MyCard custom-class="text-red-500 border border-red-500" />
```

写法 2：显式样式 prop

```vue
<script setup lang="ts">
const props = defineProps<{
  rootStyle?: string
}>()
</script>

<template>
  <view class="card" :style="props.rootStyle">
    <slot />
  </view>
</template>
```

父组件：

```vue
<MyCard root-style="color:#2563eb;background:#dbeafe;" />
```

> \[!TIP]
> 如果你确实想沿用组件标签上的 `class`，也可以声明 `externalClasses: ['class']`，但仍然要在内部根节点显式写出 `class` 占位。

页面示例：

```vue
<script setup lang="ts">
import { macroDemoNavBg, macroDemoNavTitle } from './macro.config'

definePageJson(() => ({
  navigationBarTitleText: macroDemoNavTitle,
  navigationBarBackgroundColor: macroDemoNavBg,
  enablePullDownRefresh: true,
}))
</script>
```

---

---
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>="..."`。

## 具名插槽透传 wrapper

如果你在组件里把默认 `<slot />` 继续透传给子组件的具名插槽，例如：

```vue
<IssueCard>
  <template #header>
    <slot />
  </template>
</IssueCard>
```

编译器不能生成 `<slot slot="header" />`，也不能用 `<block slot="header"><slot /></block>` 作为替代。真实 WeChat DevTools 运行时里，`block` 路径会出现宿主 header，但转发进去的内容不会渲染。

微信平台默认产物会使用内部 `virtualHost` 组件作为 wrapper：

```wxml
<weapp-slot-wrapper slot="header">
  <slot />
</weapp-slot-wrapper>
```

如果需要回到旧版 `view` wrapper，可配置 `weapp.vue.template.slotFallbackWrapperStrategy: 'view'`，或显式配置 `slotFallbackWrapper: 'view'`。如果某个组件或某个具名插槽需要换成其他真实节点，可以在组件使用处声明静态 wrapper。组件内配置推荐使用普通 kebab-case 静态属性，避免和 Vue 指令参数语法混淆。

### 当前组件默认 wrapper

```vue
<template>
  <IssueCard slot-wrapper="cover-view">
    <template #header>
      <slot />
    </template>
    <template #footer>
      <slot name="footer" />
    </template>
  </IssueCard>
</template>
```

产物中所有普通具名插槽都会使用 `cover-view`：

```wxml
<IssueCard>
  <cover-view slot="header">
    <slot />
  </cover-view>
  <cover-view slot="footer">
    <slot name="footer" />
  </cover-view>
</IssueCard>
```

### 覆盖指定具名插槽

`slot-wrapper-footer` 只覆盖 `footer`，其他插槽继续使用 `slot-wrapper`。如果是在单个 slot 上临时覆盖，更推荐直接写在对应的 `<template #footer>` 上：

```vue
<template>
  <IssueCard slot-wrapper="cover-view">
    <template #header>
      <slot />
    </template>
    <template #footer slot-wrapper="view">
      <slot name="footer" />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <cover-view slot="header">
    <slot />
  </cover-view>
  <view slot="footer">
    <slot name="footer" />
  </view>
</IssueCard>
```

如果只想覆盖单个 slot，更推荐把配置写在对应的 `<template #xxx>` 上。这个写法最靠近 slot 内容，也最容易在模板里读懂：

```vue
<template>
  <IssueCard slot-wrapper="cover-view">
    <template
      #header
      slot-wrapper="text"
      slot-wrapper-class="slot-header"
      slot-wrapper-style="margin-top: 12px"
    >
      <slot />
    </template>
    <template #footer>
      <slot name="footer" />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <text slot="header" class="slot-header" style="margin-top: 12px">
    <slot />
  </text>
  <cover-view slot="footer">
    <slot name="footer" />
  </cover-view>
</IssueCard>
```

在 `<template #header>` 上配置时，属性仍写 `slot-wrapper` / `slot-wrapper-class` / `slot-wrapper-style` / `slot-single-root-no-wrapper`，不需要再带 `header` 后缀。它比父组件标签上的默认值和 `slot-wrapper-header` 更优先。

### 给生成的 wrapper 加 class/style

普通 `class` / `style` 仍然属于组件本身，不会被转移到编译器生成的 slot wrapper 上。如果要给 wrapper 加样式，需要使用 wrapper 虚拟属性：

```vue
<template>
  <IssueCard slot-wrapper="cover-view">
    <template #header slot-wrapper="cover-view" slot-wrapper-class="slot-default" slot-wrapper-style="padding: 8px">
      <slot />
    </template>
    <template
      #footer
      slot-wrapper="view"
      slot-wrapper-class="slot-footer"
      slot-wrapper-style="margin-top: 12px"
    >
      <slot name="footer" />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <cover-view slot="header" class="slot-default" style="padding: 8px">
    <slot />
  </cover-view>
  <view slot="footer" class="slot-footer" style="margin-top: 12px">
    <slot name="footer" />
  </view>
</IssueCard>
```

动态绑定也支持，但参数名仍然必须是静态的：

```vue
<IssueCard
  :slot-wrapper-class="headerClass"
  :slot-wrapper-style="headerStyle"
>
  <template #header>
    <slot />
  </template>
  <template #footer :slot-wrapper-class="footerClass">
    <slot name="footer" />
  </template>
</IssueCard>
```

指定插槽的 class/style 只覆盖对应属性。上例中 `footer` 在 `<template #footer>` 上覆盖了 class，但仍会继承默认的 `slot-wrapper-style`。

也可以用全局配置按组件和 slot 匹配：

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        slotFallbackWrapper: {
          tag: 'view',
          attrs: {
            class: 'slot-wrapper',
          },
          rules: [
            { component: 'IssueCard', slot: 'header', tag: 'cover-view' },
            { componentName: 'HelloWorld', slot: 'header', tag: 'cover-view' },
            { component: 'IssueCard', slot: 'footer', attrs: { class: 'slot-footer' } },
            { component: /^Van/, slot: ['title', 'label'], tag: 'view' },
          ],
        },
      },
    },
  },
})
```

这里的 `component` 匹配使用处模板标签名，例如 `<IssueCard>`、`<issue-card>` 或 `<van-cell>`；它不是子组件自己的 `name`。如果要按子组件声明名匹配，子组件需要写静态 `defineOptions({ name })`，配置里使用 `componentName`：

```vue
<!-- components/IssueCard.vue -->
<script setup lang="ts">
defineOptions({
  name: 'HelloWorld',
})
</script>
```

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        slotFallbackWrapper: {
          rules: [
            { componentName: 'HelloWorld', slot: 'header', tag: 'cover-view' },
          ],
        },
      },
    },
  },
})
```

`componentName` 需要编译器能解析到被引用的 Vue SFC，适用于 `<script setup>` import 和自动导入 resolver 返回 `sourceType: 'wevu-sfc'` / `.vue resolvedId` 的组件；原生小程序组件继续用 `component` 匹配模板标签名。

### 单根真实节点下推

如果某个插槽内容本身就是单个真实节点，可以用 `slot-single-root-no-wrapper-<slotName>` 尽量避免额外 wrapper：

```vue
<template>
  <IssueCard slot-single-root-no-wrapper-icon>
    <template #icon>
      <image src="/assets/icon.png" />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <image slot="icon" src="/assets/icon.png" />
</IssueCard>
```

如果内容是转发 `<slot />`，仍然会保留 wrapper：

```vue
<template>
  <IssueCard slot-single-root-no-wrapper-header>
    <template #header>
      <slot />
    </template>
  </IssueCard>
</template>
```

产物：

```wxml
<IssueCard>
  <weapp-slot-wrapper slot="header">
    <slot />
  </weapp-slot-wrapper>
</IssueCard>
```

### `block` 和内容承载限制

默认策略不会使用 `block`。如果显式配置 `slotFallbackWrapper: 'block'`，编译器会按原样输出：

```wxml
<IssueCard>
  <block slot="header">
    <slot />
  </block>
</IssueCard>
```

注意：`block` 在转发 `<slot />` 的部分 WeChat DevTools 运行时场景中会丢失内容，因此不作为默认值。显式启用时需要自行确认目标运行时和具体插槽内容可用。

你选择的 wrapper 还必须能承载实际内容。比如：

```vue
<template>
  <IssueCard>
    <template #header slot-wrapper="text">
      <view>Header</view>
    </template>
  </IssueCard>
</template>
```

会生成：

```wxml
<IssueCard>
  <text slot="header">
    <view>Header</view>
  </text>
</IssueCard>
```

`text` 不适合包裹 `<view>` 子节点，需要按宿主规则改用 `view`、`cover-view` 或已验证的自定义组件。

规则汇总：

* `slot-wrapper` 是当前组件所有普通具名插槽的默认 wrapper。
* `slot-wrapper-<slotName>` 只覆盖指定具名插槽。
* `slot-wrapper-class` / `slot-wrapper-style` 会给当前组件所有普通具名插槽 wrapper 加 class/style。
* `slot-wrapper-<slotName>-class` / `slot-wrapper-<slotName>-style` 只覆盖指定具名插槽 wrapper 的 class/style。
* 写在 `<template #slot>` 上的 `slot-wrapper` / `slot-wrapper-class/style` 是对应 slot 的就近覆盖，优先级高于父组件标签上的同名或带 slot 后缀配置。
* `slot-single-root-no-wrapper-<slotName>` 可以让指定插槽在单根真实节点场景下尽量下推 `slot="..."`。
* 全局 `slotFallbackWrapper.rules[].component` 匹配模板标签名，`componentName` 匹配子组件静态 `defineOptions({ name })`。
* `block` 会被编译器拒绝并回退到 `view`。
* 你选择的 wrapper 必须能承载实际内容。

## Vue 模板兼容矩阵

“兼容有说明”表示常见迁移结果一致，但最终执行的是小程序模板而不是浏览器 DOM。只要差异会改变写法、参数或渲染结果，就归入“Vue 差异”。

### 内置指令

#### `v-text` {#directive-v-text}

**兼容有说明。** 编译为小程序文本插值；不经过 DOM `textContent`。

#### `v-html` {#directive-v-html}

**不支持。** 编译器会给出警告并忽略该指令，请使用小程序 `rich-text` 组件渲染受信任节点数据。

#### `v-show` {#directive-v-show}

**兼容有说明。** 编译器把条件拼接到 `style` 的 `display`，节点不会因切换而销毁。

#### `v-if` {#directive-v-if}

**兼容有说明。** 转换为当前平台的条件渲染属性，例如微信的 `wx:if`。

#### `v-else-if` {#directive-v-else-if}

**兼容有说明。** 转换为当前平台的条件分支属性，并要求与前一条件节点保持合法相邻关系。

#### `v-else` {#directive-v-else}

**兼容有说明。** 转换为当前平台的兜底条件分支。

#### `v-for` {#directive-v-for}

**兼容有说明。** 转换为宿主列表指令；编译器会规范化 item、index 和 key，并为运行时表达式补充稳定索引。

#### `v-on` {#directive-v-on}

**Vue 差异。** `@click` 等事件会映射为小程序事件，例如 `tap`；事件修饰符只覆盖宿主可表达的语义。

#### `v-bind` {#directive-v-bind}

**Vue 差异。** 支持 `:prop="value"` 形式的显式绑定，当前不支持 `v-bind="object"` 属性展开。

#### `v-model` {#directive-v-model}

**Vue 差异。** 编译为小程序属性和赋值事件；目标必须是可赋值左值，表单类型、参数和修饰符支持范围见本页前文。

#### `v-slot` {#directive-v-slot}

**Vue 差异。** 普通插槽映射到小程序 slot；明确存在 slot props 的场景才会启用增强 scoped slot/generic 编译。

#### `v-pre` {#directive-v-pre}

**不支持。** 当前模板链路没有跳过局部编译的 Vue `v-pre` 语义。

#### `v-once` {#directive-v-once}

**Vue 差异。** 当前会产生支持不完整警告，并按普通节点继续渲染，不保证只渲染一次。

#### `v-memo` {#directive-v-memo}

**不支持。** 当前没有 Vue `v-memo` 的子树缓存和更新跳过语义。

#### `v-cloak` {#directive-v-cloak}

**Vue 差异。** 编译器忽略该标记；小程序没有浏览器首次编译前模板闪烁这一执行阶段。

#### 自定义指令 {#directive-custom}

**Vue 差异。** 自定义 `v-xxx` 会按小程序模板属性转换，不执行 Vue DOM 指令的 mounted/updated 等元素钩子。

### 特殊元素与内置组件

#### `<component>` {#element-component}

**Vue 差异。** 动态组件必须满足小程序 `usingComponents` 和模板动态组件能力，不能按浏览器运行时任意解析组件。

#### `<slot>` {#element-slot}

**Vue 差异。** 编译为小程序插槽；具名插槽转发会按平台选择 wrapper，避免真实运行时丢失内容。

#### `<template>` {#element-template}

**Vue 差异。** 搭配结构指令时转换为 `block`；带 `name/is/data` 时保留小程序原生 template 语义。

#### `<Transition>` {#element-transition}

**Vue 差异。** 当前仅渲染子节点并给出警告，不注入 Vue CSS/JavaScript 过渡运行时。

#### `<TransitionGroup>` {#element-transition-group}

**不支持。** 当前不提供列表过渡运行时。

#### `<KeepAlive>` {#element-keep-alive}

**Vue 差异。** 当前输出带标记的 `block`，不承诺 Vue 完整的组件实例缓存语义。

#### `<Teleport>` {#element-teleport}

**不支持。** 小程序模板没有 Vue Teleport 的任意目标挂载模型。

#### `<Suspense>` {#element-suspense}

**不支持。** 当前不提供 Vue Suspense 异步依赖边界。

#### `key` {#attribute-key}

**兼容有说明。** 用于稳定列表节点身份，并转换为当前小程序平台的 key 属性；不要依赖浏览器 VNode 的复用细节。

#### `ref` {#attribute-ref}

**Vue 差异。** 编译器登记小程序节点或组件引用，通过 `useTemplateRef()` 异步读取宿主查询结果，不返回 DOM Element。

#### `is` {#attribute-is}

**Vue 差异。** 动态组件受 `usingComponents` 与宿主动态组件能力限制；原生 `<template is="...">` 仍按小程序模板语义处理。

### HTML 标签转换 {#html-tag-mapping}

`weapp.vue.template.htmlTagToWxml` 默认启用以下映射。标签发生改名时，`htmlTagToWxmlTagClass` 默认还会保留原标签名 class，方便迁移 CSS；两项配置都只作用于 Vue SFC 模板。

| Vue 模板标签 | 小程序标签  | Vue 模板标签 | 小程序标签 |
| ------------ | ----------- | ------------ | ---------- |
| `a`          | `navigator` | `article`    | `view`     |
| `aside`      | `view`      | `b`          | `text`     |
| `blockquote` | `view`      | `br`         | `view`     |
| `button`     | `button`    | `code`       | `text`     |
| `dd`         | `view`      | `div`        | `view`     |
| `dl`         | `view`      | `dt`         | `view`     |
| `em`         | `text`      | `figcaption` | `view`     |
| `figure`     | `view`      | `footer`     | `view`     |
| `form`       | `form`      | `h1` - `h6`  | `view`     |
| `header`     | `view`      | `hr`         | `view`     |
| `i`          | `text`      | `img`        | `image`    |
| `input`      | `input`     | `label`      | `label`    |
| `li`         | `view`      | `main`       | `view`     |
| `nav`        | `view`      | `ol`         | `view`     |
| `p`          | `view`      | `pre`        | `view`     |
| `section`    | `view`      | `small`      | `text`     |
| `span`       | `text`      | `strong`     | `text`     |
| `textarea`   | `textarea`  | `u`          | `text`     |
| `ul`         | `view`      |              |            |

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        htmlTagToWxml: { dialog: 'view' },
        htmlTagToWxmlTagClass: true,
      },
    },
  },
})
```

## 延伸阅读

* [class/style 绑定能力](/wevu/vue-sfc/class-style)

---

---
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: /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: /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/api` 是 `wevu` 的子路径入口，本质上透传的是 `@wevu/api`。

这页讨论的是 API 门面与调用语义，不讨论“应该放到 `dependencies` 还是 `devDependencies`”这类工程落位策略；依赖安装位置应以你的实际构建方式和项目模板约定为准。
:::

## 它和 `@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 安装方式
在 `weapp-vite` 项目里，`wevu` 通常建议安装在 `devDependencies` 中：

```sh
pnpm add -D wevu
```

这是 Weapp-vite + Wevu 的常见推荐组合；若你是在其他构建场景单独消费 `wevu/fetch`，应按自己的发布方式决定依赖落位。
:::

## 导出内容

* `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/router.md
description: wevu/router 子路径文档，介绍路径式导航、守卫、失败分类与小程序环境下的边界。
---

# `wevu/router`

`wevu/router` 是 Wevu 提供的独立路由子入口，目标是尽量对齐 Vue Router 的导航心智，同时保持对小程序路由能力边界的明确约束。

如果你只需要拿到原生页面路由对象，请继续使用 `wevu` 主入口里的 `useNativeRouter()` / `useNativePageRouter()`；如果你需要守卫、失败分类、`resolve()` 与更统一的导航封装，请使用 `wevu/router`。

> **注意**：`wevu` 根入口没有 `useRouter()`。`useRouter()` 是 `wevu/router` 子入口的 API。

:::tip 创建与获取

* `createRouter()`：负责创建并注册默认 router 实例
* `useRouter()`：负责获取当前已创建的 router 实例

推荐在应用入口或上层 `setup()` 中先调用一次 `createRouter()`，后续业务代码里再通过 `useRouter()` 读取。
:::

:::warning 安装方式
在 `weapp-vite` 项目里，`wevu` 通常建议安装到 `devDependencies`：

```sh
pnpm add -D wevu
```

如果你是在非 `weapp-vite` 场景单独消费 `wevu/router`，则应按自己的发布方式决定依赖落位。
:::

## 1. 什么时候使用

* 想把页面跳转从“零散 `wx.navigateTo` 调用”升级到统一导航入口
* 想把跳转前判断收敛到 `beforeEach` / `beforeResolve` / `beforeEnter`
* 想获得更接近 Vue Router 的 `resolve()`、`currentRoute` 与失败分类能力

## 2. 最小示例

```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)
```

## 3. 在 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`。

### 3.1 `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()` 才能直接拿到默认实例

## 4. 核心能力

* `useRouter()`：获取当前已创建的路由实例
* `createRouter()`：创建带守卫、失败分类的高阶路由器
* `useRoute()`：读取当前路由快照
* `resolveRouteLocation()`：预解析目标位置
* `parseQuery()` / `stringifyQuery()`：query 处理工具
* `createNavigationFailure()` / `isNavigationFailure()`：失败对象与判定
* `NavigationFailureType`：失败类别枚举

## 5. 常见心智

### 5.1 路径优先

```ts
await router.push('/pages/post/1/index?preview=0')
```

在小程序里，页面物理路径本身就是分包、注册和跳转语义的一部分，所以文档更推荐你直接使用真实页面路径。

### 5.2 守卫用于统一前置判断

```ts
import { createRouter } from 'wevu/router'

const router = createRouter({
  beforeEach(to) {
    if (to.path.startsWith('/pages/private/') && !isLoggedIn()) {
      return '/pages/login/index'
    }
  },
})
```

这样比把跳转限制散落在各个页面里更容易维护。

### 5.3 小程序不支持真正 forward 栈

```ts
const result = await router.forward()
```

这在小程序里通常会返回 `NavigationFailureType.aborted`，属于预期行为，不是 bug。

## 6. 调试与迁移建议

* 用 `resolve()` 提前检查 `href / matched / redirectedFrom`
* 把业务里的零散跳转判断迁移到守卫，而不是继续散落在页面逻辑里
* 优先保留小程序真实路径，不要过早抽象成重度命名路由体系

## 7. 速查表

| 需求                    | 建议 API                            |
| ----------------------- | ----------------------------------- |
| 获取高阶 router 实例    | `useRouter()` from `wevu/router`    |
| 获取当前 route 快照     | `useRoute()`                        |
| 获取页面路径语义 Router | `useNativePageRouter()` from `wevu` |
| 获取组件路径语义 Router | `useNativeRouter()` from `wevu`     |

## 8. 相关页面

* [Wevu Router API 完整参考](/wevu/api/router)
* [wevu/api/setup-context](/wevu/api/setup-context)
* [wevu/api/runtime-bridge](/wevu/api/runtime-bridge)
* [wevu/api-package](/wevu/api-package)

---

---
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 安装方式
在 `weapp-vite` 项目里，`wevu` 通常建议安装在 `devDependencies` 中：

```sh
pnpm add -D wevu
```

若你是在其他 JSX/TSX 工程里单独消费 `wevu/jsx-runtime`，则应按自己的发布方式决定依赖落位。
:::

## 1. 当前定位

* 子路径：`wevu/jsx-runtime`
* 主要导出：`JSX` 命名空间类型
* 作用：补充 `IntrinsicElements`、`GlobalComponents` 与小程序标签的属性推导

## 2. 什么时候需要它

* 你在项目里启用了 TSX / JSX
* 你希望通过 `jsxImportSource: "wevu"` 获得更准确的类型提示
* 你在做底层组件封装、类型实验或自定义编译链适配

如果你的项目主要是 `.vue` SFC 或传统小程序页面，不一定会直接接触这个子路径。

## 3. TypeScript 配置示例

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "wevu"
  }
}
```

当配置为 `jsxImportSource: "wevu"` 时，TypeScript 会解析 `wevu/jsx-runtime` 的类型入口。

## 4. 它解决什么问题

* 让 JSX 环境下的小程序标签有更合理的属性提示
* 让全局组件类型可以合并进 `IntrinsicElements`
* 避免 JSX 类型系统默认回落到不适合 Wevu 的 Web/Vue 语义

## 5. 注意事项

* 这是“类型辅助入口”，不是常规运行时导入入口
* 业务代码日常仍然优先从 `wevu` 主入口导入 API
* 如果你没有启用 JSX/TSX，通常不需要显式导入它

## 6. 相关页面

* [Core API](/wevu/api/core)
* [Vue SFC 基础](/wevu/vue-sfc/basics)

---

---
url: /wevu/compatibility.md
description: 本页用于快速排雷：哪些能力能用、有哪些限制来自小程序环境，以及哪些点最容易踩坑。
---

# 兼容性与注意事项

本页用于快速排雷：哪些能力能用、有哪些限制来自小程序环境，以及哪些点最容易踩坑。

* **运行环境**：Wevu 依赖 `Proxy` / `WeakMap` / `Symbol` 等能力，建议微信小程序基础库 ≥ 3.0.0；模板/样式/配置通常配合 Weapp-vite 构建产物使用。
* **Router 基础库门槛**：`this.router / this.pageRouter` 原生能力从基础库 `2.16.1+` 可用；`useNativeRouter()/useNativePageRouter()` 在低版本会自动回退到全局 `wx/my/tt` 路由方法。若需要跨版本路径基准稳定，优先绝对路径或优先 `useNativePageRouter()`。
* **无 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: /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（已弃用，仅用于兼容/过渡；当前版本仍保留导出）

> \[!WARNING]
> `provideGlobal()` / `injectGlobal()` 不是推荐用法，只是为了兼容旧代码仍然保留。
> 新代码请优先使用 `provide()` / `inject()`，或使用 store 处理全局共享状态。

### 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/migration/from-native-to-vue-sfc.md
description: >-
  这是一份面向实际项目的迁移手册，不是概念介绍。目标是让你在不重写业务的前提下，按需迁移到 Weapp-vite + 原生，或继续升级到 Weapp-vite
  + Wevu + Vue SFC。
---

# 从原生小程序迁移到 Weapp-vite / Wevu（详细指南）

这是一份面向实际项目的迁移手册，不是概念介绍。目标是让你在**不重写业务**的前提下，把原生小程序稳定迁移到 `weapp-vite + 原生`，或在同一条迁移链路上继续升级到 `weapp-vite + Wevu + Vue SFC`。

适用场景：

* 线上已有原生小程序，想先保留 `Page/Component + WXML/WXSS/JSON`，只升级构建、TypeScript、调试、AI 协作和验收链路。
* 线上已有原生小程序，想分批把页面或组件迁移到 `Wevu + Vue SFC`，但不能一次性重写。
* 新项目计划直接采用 Vue SFC 写法，同时保留小程序原生能力。

## 先选迁移目标

不要把“接入 Weapp-vite”误解成“必须立刻 Vue 化”。存量项目通常有两条合理路线：

| 路线 | 目标组合                      | 适合项目                                                                                                      | 完成标准                                                                          |
| ---- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| A    | `weapp-vite + 原生`           | 团队希望继续写原生 `Page/Component`，但想获得 Vite 构建、TS、别名、资源处理、DevTools、截图日志和 AI 维护能力 | 原生页面不改写也能稳定 dev/build/open，关键链路可验证，新增页面仍可按原生方式交付 |
| B    | `weapp-vite + Wevu + Vue SFC` | 团队希望逐步引入组合式 API、响应式状态、SFC 组织方式和更类型化的组件契约                                      | 原生与 SFC 能共存，目标页面族迁到 `.vue`，核心状态和事件契约完成语义升级          |

推荐判断：

* 如果当前最大痛点是工程效率、构建速度、路径别名、TS、调试和 AI 协作，先走路线 A。
* 如果当前最大痛点是页面脚本膨胀、`setData` 大对象、组件契约隐式、状态难维护，再在路线 A 的基础上推进路线 B。
* 如果项目里有复杂插件、`wxs/sjs`、云开发、地图/直播/支付、老旧 Behavior 或大量宿主 API，先保留原生资产，等验证闭环稳定后再选页面族迁到 Wevu。
* 同一个项目可以长期混合：核心老页面保留原生，新页面或低风险页面使用 SFC。

## 迁移目标与验收标准

建议先明确“迁移完成”意味着什么，避免路线 A 被误收敛成路线 B，也避免路线 B 只完成语法替换。

路线 A 的验收标准：

* 原生页面、组件、分包、插件和 npm 依赖在 Weapp-vite 构建链路下行为等价。
* `dev/build/open` 或项目内等价脚本稳定可用。
* `wv prepare` 生成的 `.weapp-vite` 支持文件、AI 指引和本地随包文档接入稳定。
* 路径别名、环境变量、静态资源、DevTools 项目配置和 CI 命令已对齐。
* 至少一条关键链路有可复现的构建、打开、日志或截图验收。

路线 B 的验收标准：

* 功能等价：核心页面流程（浏览、下单、支付、售后）行为与原版一致。
* 稳定性提升：常见空值场景不再出现 `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)`）
* 有导航/分享/滚动等页面事件

## 总体迁移路线（推荐 5 阶段）

```mermaid
flowchart LR
  A[阶段 0<br/>原生项目体检] --> B[阶段 1<br/>接入 weapp-vite]
  B --> C{是否继续迁到 Wevu?}
  C -->|否| D[路线 A<br/>原生链路收口]
  C -->|是| E[路线 B<br/>SFC 试点与共存]
  E --> F[页面族迁移]
  F --> G[语义升级与回归]
```

### 阶段 0：原生项目体检

先盘点当前项目，而不是直接改文件：

* `app.json`、页面路由、tabBar、分包和插件。
* 自定义组件、Behavior、`wxs/sjs`、npm 构建和静态资源。
* 云开发、地图/直播/支付等强宿主能力。
* DevTools 打开方式、CI 命令、预览/上传流程。
* 至少一条关键链路的入口、操作、接口和已知异常。

### 阶段 1：只替构建链路，不改业务行为

先接入 `weapp-vite` 并保证原功能可跑，不立即重构逻辑。

验证最小闭环：

* `pnpm build`
* 在开发者工具中打开并手测 1 到 2 个核心页面

如果目标只是路线 A，这一步不是“过渡态”，而是可以作为阶段性交付终点。

### 阶段 2A：路线 A 收口（继续原生）

保留原生页面和组件，重点收口工程能力：

* 把 `vite.config.ts`、脚本、输出目录和 DevTools 配置写成团队稳定入口。
* 让 `.js/.ts/.wxml/.wxss/.json` 原生资产在 Weapp-vite 下继续由构建链路处理。
* 对齐 `wv prepare`、`.weapp-vite` 类型支持文件、AI 指引、本地 `dist/docs` 阅读顺序。
* 关键页面补截图、日志或轻量 e2e，证明迁移后不是“只能构建，不能运行”。
* 新页面仍可按原生方式新增；需要 SFC 时再显式进入路线 B。

### 阶段 2B：路线 B 试点（原生与 Vue SFC 共存）

目标是证明迁移可以逐页发生：

* 旧页面继续保留原生 `js/wxml/wxss/json`。
* 新页面或低风险页面使用 `.vue`。
* 原生页面和 SFC 页面可以互相跳转。
* 不在试点阶段夹带全局状态、网络层、鉴权或视觉系统重写。

### 阶段 3：机械迁移（重点是“等价”）

先把原 `js + wxml + wxss + json` 聚合成单个 `.vue`，不追求代码优雅。

### 阶段 4：语义迁移（重点是“可维护”）

把 `this.data + this.setData + methods` 逐步替换为 `ref/reactive/computed/watch`。

### 阶段 5：收口（重点是“可持续”）

统一风格、补齐测试、清理历史写法，沉淀迁移规范。

## 原生到 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 | 原生项目体检   | 明确路线 A / B、风险资产和基线 | 迁移边界、回滚点、关键路径清楚   |
| Wave 1 | 工具链接入     | 接入 Weapp-vite，业务 0 改动   | `build` 可过，首页可打开         |
| Wave 2 | 路线 A 收口    | 原生页面继续稳定交付           | dev/build/open/日志或截图闭环    |
| Wave 3 | 路线 B 试点    | 低风险页或新页面迁移到 SFC     | 原生页和 SFC 页互跳，冒烟通过    |
| Wave 4 | 页面族迁移     | 表单页、筛选页、详情页等页面族 | 正/反向流程通过，参数健壮性通过  |
| Wave 5 | 高风险链路收口 | 下单、支付、售后等核心路径     | 关键链路 e2e 通过 + 真机回归通过 |
| Wave 6 | 语义升级       | 清理遗留 `setData` 大对象写法  | 编码规范统一，迁移文档补齐       |

每个波次建议都固定执行这 4 步：

1. 迁移前记录基线行为（页面入口、关键交互、关键接口）。
2. 明确本轮属于路线 A 还是路线 B。
3. 路线 A 只改工程入口，路线 B 再做 `.vue` 机械迁移和语义升级。
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>
```

> 迁移第一步允许“结构升级但逻辑不重构”。先跑通，再优化。

> \[!TIP]
> 如果原页面的 WXML 里混用了较多 HTML 风格标签（例如 `div`、`span`、`img`、`a`、`h1/h2/h3`、`br`、`hr`），迁移到 `.vue` 后可以先利用 `weapp.vue.template.htmlTagToWxml` 做一层编译期映射，降低第一轮机械迁移的模板改造量。
>
> 当前默认还会通过 `weapp.vue.template.htmlTagToWxmlTagClass` 给映射后的节点追加原标签名 class，例如 `h3 -> <view class="h3">`、`br -> <view class="br" />`，便于你后续用 CSS 渐进恢复 HTML 默认外观；如果团队不需要这层语义 class，也可以显式关闭。

## 两种落地策略：渐进式 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. 把路线 A 当成未完成状态

根因：误以为迁移到 Weapp-vite 后必须继续迁到 Wevu / Vue SFC。

修复：如果项目当前只需要工程化收益，就把 `weapp-vite + 原生` 作为明确交付目标，等页面维护成本或新功能形态需要时再进入路线 B。

### 7. 本地开发能跑，但构建后页面崩溃

根因：只验证了 dev 场景，没有验证 build 产物与真机行为。

修复：每轮迁移都执行“开发调试通过 -> 构建验证通过 -> 真机关键路径回归”。

### 8. 一次迁移太多页面导致回滚困难

根因：提交粒度过大。

修复：按“页面族”迁移，每次只处理一个业务域并可单独回滚。

### 9. 先重构再迁移，问题难定位

根因：把“技术迁移”和“业务重构”耦合。

修复：先机械迁移，再结构优化。

## 推荐目录与分层（迁移后）

建议每个页面按“页面 SFC + 同目录服务/工具”组织，避免继续堆在大 `index.vue`。

```text
pages/order/order-confirm/
  index.vue
  pay.ts
  mapper.ts
  guards.ts
```

拆分规则：

* `mapper.ts`：接口 DTO -> 视图模型转换。
* `guards.ts`：空值保护、参数合法化、兜底逻辑。
* `pay.ts`：支付等副作用流程。

## 页面迁移清单（可直接执行）

### 清单 0：路线 A，保留原生

1. 原生页面和组件保持 `js/wxml/wxss/json` 结构。
2. 接入或修正 `vite.config.ts` 的 `weapp` 配置。
3. 对齐路径别名、环境变量、静态资源、npm 构建和输出目录。
4. 运行 `wv prepare`，确认 `.weapp-vite` 支持文件稳定。
5. build 并在 DevTools 打开至少一条关键路径。

### 清单 A：路线 B，机械迁移

1. 合并 `index.js/wxml/wxss/json` 到 `index.vue`。
2. 保留原函数名与流程，不动业务逻辑。
3. 补齐 JSON 配置（导航栏、组件注册、页面配置）。
4. build 并手测页面主路径。

### 清单 B：路线 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）

如果目标是路线 A，当以下条件都成立，迁移可以视为完成：

* 原生页面和组件仍使用原有小程序模型，但已稳定纳入 Weapp-vite 构建链路。
* `dev/build/open`、路径别名、环境变量、资源处理和 DevTools 项目配置可复现。
* `wv prepare`、本地随包文档和项目 AI 指引已对齐。
* 至少一条关键链路有构建、打开、日志或截图验收。

如果目标是路线 B，当以下条件都成立，迁移可以视为完成：

* 核心页面已迁移到 `<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/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-runtime/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-runtime/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-runtime/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-runtime/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-runtime/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-runtime/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-runtime/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-runtime/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-runtime/wevu/src/reactivity/`
* **Wevu 调度器**: `packages-runtime/wevu/src/scheduler.ts`
* **Wevu 运行时**: `packages-runtime/wevu/src/runtime/app.ts`
* **小程序注册**: `packages-runtime/wevu/src/runtime/register.ts`
* **Diff 算法**: `packages-runtime/wevu/src/runtime/diff.ts`
* **双向绑定**: `packages-runtime/wevu/src/runtime/bindModel.ts`

## 相关阅读

* [Wevu 工作原理](https://github.com/weapp-vite/weapp-vite/blob/main/packages-runtime/wevu/ARCHITECTURE.md)
* [Vue 3 兼容性文档](./vue3-compat)
* [小程序 setData 优化](https://developers.weixin.qq.com/miniprogram/dev/framework/performance/tips.html)

---

---
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: /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: /handbook.md
description: 从零开始创建一个 Weapp-vite + Wevu 小程序项目，写出第一个页面，确认它能在开发者工具里正常运行。
---

# 创建项目，跑起来

这篇教程不讲理论，目标就一个：你跟着做完，能在微信开发者工具里看到自己写的页面。

## 你需要准备什么

* Node.js 22 LTS（`>=22.12.0`）
* pnpm
* 微信开发者工具

如果你后面想用命令行控制开发者工具（打开、预览、上传），记得在开发者工具的设置里开启"服务端口"。

## 创建项目

```bash
pnpm create weapp-vite
```

跟着提示走就行。创建完之后，你会看到大概这样的目录：

```txt
my-app/
├─ src/
│  ├─ app.vue
│  ├─ app.json
│  └─ pages/
│     └─ home/
│        └─ index.vue
├─ vite.config.ts
├─ project.config.json
├─ package.json
└─ AGENTS.md
```

脚手架还会问你要不要装推荐的 AI skills，如果跳过了，后面可以手动装：

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

## 写第一个页面

打开 `src/pages/home/index.vue`，写一个最简单的计数器：

```vue
<script setup lang="ts">
import { computed, ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '首页',
}))

const count = ref(0)
const doubled = computed(() => count.value * 2)
</script>

<template>
  <view class="page">
    <text class="title">Hello Weapp-vite</text>
    <text>count: {{ count }}</text>
    <text>doubled: {{ doubled }}</text>
    <button @tap="count++">
      +1
    </button>
  </view>
</template>

<style scoped>
.page {
  padding: 32rpx;
}

.title {
  display: block;
  margin-bottom: 24rpx;
  font-size: 36rpx;
  font-weight: 600;
}
</style>
```

这里面有几个关键点，先记住就行，后面会展开讲：

* `definePageJson()` 是页面配置的宏，用来设置标题、下拉刷新这些
* 响应式 API（`ref`、`computed`）从 `wevu` 导入，不是从 `vue`
* 模板里用的是小程序标签（`view`、`text`、`button`），事件用 `@tap` 不是 `@click`

## 确认页面被路由系统识别

页面写好了，还得确认它被纳入了应用。看一下 `src/app.json`：

```json
{
  "pages": ["pages/home/index"],
  "window": {
    "navigationBarTitleText": "Demo"
  }
}
```

如果你开了自动路由（`weapp.autoRoutes`），这一步可以省掉，`pages/` 下的 `.vue` 文件会被自动扫描。

## 启动开发

```bash
pnpm dev
```

然后用微信开发者工具打开项目的 `dist` 目录（不是 `src`）。你应该能看到页面正常显示，点按钮数字会变。

如果你在用 AI 终端，这几个命令会很常用：

```bash
wv prepare          # 生成类型支持文件
wv ide logs --open  # 把开发者工具的 console 桥接到终端
```

## 跑不起来？先查这几个地方

| 症状             | 先查什么                                                          |
| ---------------- | ----------------------------------------------------------------- |
| 页面白屏         | `app.json` 里有没有这个页面路径                                   |
| 点按钮没反应     | `ref` 是不是从 `wevu` 导入的                                      |
| 数据改了页面没变 | 同上，从 `vue` 导入的 `ref` 在小程序里不会触发更新                |
| 标题没生效       | 看 `dist/pages/home/index.json` 里有没有 `navigationBarTitleText` |
| 开发者工具打不开 | 确认导入的是 `dist` 目录，不是 `src`                              |

## 这套技术栈是怎么分工的

你现在不需要完全理解，但知道这个分工会帮你后面排查问题：

```txt
weapp-vite  → 负责开发、构建、把 .vue 编译成小程序文件
wevu        → 负责运行时：响应式、生命周期、状态管理
你的代码     → 页面、组件、请求、业务逻辑
```

一个 `.vue` 文件最终会变成小程序的四件套：

```txt
dist/pages/home/
├─ index.js      ← 页面逻辑
├─ index.json    ← 页面配置
├─ index.wxml    ← 模板
└─ index.wxss    ← 样式
```

遇到问题的时候，去 `dist` 里看这些文件，比盯着源码猜要快得多。

## 下一步

项目跑起来了，接下来看看[目录怎么放](/handbook/project-structure)比较合理。

---

---
url: /handbook/project-structure.md
description: 从新用户和中小型业务项目的视角，解释 Weapp-vite 项目里的页面、组件、服务、状态和静态资源应该怎么落位。
---

# 目录结构怎么放最顺手

新项目一开始最容易出现两种极端：

* 什么都塞进 `pages/`，后面越写越乱
* 一上来就设计十几层目录，结果团队没人记得住

更稳的做法是：先用一个足够清晰、又不过度设计的结构跑起来。

## 一个推荐的起步结构

如果你现在准备做的是一个正常业务小程序，可以先从下面这个结构开始：

```txt
src/
├─ app.vue
├─ app.json
├─ pages/
│  ├─ home/
│  │  └─ index.vue
│  └─ order/
│     ├─ list.vue
│     └─ detail.vue
├─ components/
│  ├─ product-card/
│  │  └─ index.vue
│  └─ empty-state/
│     └─ index.vue
├─ stores/
│  ├─ user.ts
│  └─ cart.ts
├─ services/
│  ├─ request.ts
│  ├─ user.ts
│  └─ order.ts
├─ utils/
│  ├─ formatPrice.ts
│  └─ time.ts
└─ assets/
   ├─ images/
   └─ icons/
```

在真实项目根目录里，通常还会看到这些不属于 `src/`、但同样重要的文件：

```txt
.
├─ vite.config.ts / weapp-vite.config.ts
├─ project.config.json
├─ AGENTS.md
├─ .weapp-vite/
└─ dist/
```

它们分别负责：

* `vite.config.ts` / `weapp-vite.config.ts`：项目配置入口
* `project.config.json`：微信开发者工具工程配置
* `AGENTS.md`：给 AI 的项目级工作流约束
* `.weapp-vite/`：托管的支持文件与类型产物
* `dist/`：最终给开发者工具或 CI 使用的构建产物

它背后的分工很简单：

* `pages/`
  放页面入口，一个页面一个目录或一个主文件
* `components/`
  放会复用的业务组件或通用组件
* `stores/`
  放状态管理，不要把接口请求、页面渲染和状态都揉在一起
* `services/`
  放请求封装和领域 API
* `utils/`
  放纯工具函数
* `assets/`
  放跨页面复用的静态资源

## 页面目录里建议放什么

一个页面最常见的落位方式是：

```txt
pages/order-detail/
├─ index.vue
├─ components/
│  └─ goods-item.vue
└─ useOrderDetail.ts
```

页面局部的内容可以尽量贴近页面放，这样好处是：

* 打开页面目录就能看到完整上下文
* 页面下线时，局部组件和组合逻辑也能一起删掉
* 不会把全局 `components/` 变成“公共垃圾场”

比如：

```vue
<!-- pages/order-detail/index.vue -->
<script setup lang="ts">
import GoodsItem from './components/goods-item.vue'
import { useOrderDetail } from './useOrderDetail'

const { detail, loading } = useOrderDetail()
</script>
```

## 什么时候放到全局 `components/`

满足下面两个条件，再考虑提升到全局：

1. 确实被多个页面复用
2. 组件本身已经有稳定的输入输出边界

例如这些通常适合放全局：

* `empty-state`
* `price-text`
* `loading-view`
* `user-avatar`

而这种更适合留在页面目录：

* `order-status-card`
* `coupon-dialog`
* `refund-reason-panel`

## `services` 和 `stores` 不要混

一个非常常见的问题是：把请求、缓存、页面 loading、错误提示全塞进页面里。

更推荐的分法是：

```ts
// services/order.ts
export async function getOrderDetail(id: string) {
  return request<OrderDetail>({
    url: `/api/orders/${id}`,
  })
}
```

```ts
// stores/order.ts
import { ref } from 'wevu'
import { getOrderDetail } from '../services/order'

export function useOrderStore() {
  const detail = ref<OrderDetail | null>(null)
  const loading = ref(false)

  async function fetchDetail(id: string) {
    loading.value = true
    try {
      detail.value = await getOrderDetail(id)
    }
    finally {
      loading.value = false
    }
  }

  return {
    detail,
    loading,
    fetchDetail,
  }
}
```

一句话理解：

* `services` 负责和服务端对话
* `stores` 负责把状态组织给页面消费

## 文件命名建议

从长期维护角度，建议一开始就统一：

* 页面目录：语义化、稳定，尽量不要频繁改路径
* 组件目录：`kebab-case`
* 工具函数文件：`camelCase`
* store 名称：按业务域命名，不要做成“超级 store”

例如：

```txt
components/product-card/index.vue
stores/cart.ts
services/order.ts
utils/formatPrice.ts
```

## 新用户最容易踩的目录坑

### 1. 所有内容都放全局

结果是：

* 小组件越来越多
* 页面上下文越来越难找
* 复用和“看起来像复用”混在一起

### 2. 所有内容都放页面目录

结果是：

* 公共组件没有真正抽象出来
* 同一逻辑在不同页面复制粘贴

### 3. 过早拆成特别复杂的领域层

如果你的项目还没超过几个核心业务页面，就不必一上来设计太复杂的模块边界。

### 4. 忽略项目根目录的 AI / 工具文件

当前版本里，下面几个文件或目录不应该被当成“无关生成物”：

* `AGENTS.md`
* `.weapp-vite/`
* `dist/`

建议理解为：

* `AGENTS.md` 决定 AI 进入项目后先读什么、优先用什么命令
* `.weapp-vite/` 决定编辑器类型提示、自动路由类型、自动导入组件类型是否稳定
* `dist/` 决定开发者工具最终看到的到底是不是你以为的输出

如果类型提示异常、AI 行为跑偏、下游验证与源码不一致，先检查这三者是否同步。

## 什么时候应该运行 `wv prepare`

优先在这些场景执行：

* 新 clone 下来的项目第一次打开
* 升级了 `weapp-vite`
* `.weapp-vite` 缺失
* Volar / TypeScript 提示异常
* 想在 `dev/build` 之前先把支持文件生成好

```bash
wv prepare
```

如果你是让 AI 进入项目处理问题，也建议它先读：

1. 根目录 `AGENTS.md`
2. `node_modules/weapp-vite/dist/docs/index.md`
3. `vite.config.ts` / `weapp-vite.config.ts`

## 一句话建议

先让结构服务于“能快速定位代码”，而不是服务于“看起来很高级”。

你现在可以继续看：

* [环境变量与配置怎么分层](/handbook/env-and-config)
* [构建产物到底长什么样](/handbook/build-and-output)
* [先建立 SFC 心智模型](/handbook/sfc/)

---

---
url: /handbook/env-and-config.md
description: 从新用户视角解释构建期变量、运行期配置和小程序 JSON 配置的边界，帮助你避免开发环境正常、线上环境出问题。
---

# 环境变量与配置怎么分层

很多项目不是“不会配”，而是“把不同阶段的配置混在一起了”。

小程序项目里至少有 3 类配置：

1. 构建期配置
2. 运行期配置
3. 小程序宿主配置

如果这三类混在一起，最容易出现的问题就是：

* 本地开发正常
* 预发环境正常
* 一到正式环境就开始白屏、跳错页、请求错域名

## 先用一句话区分三类配置

### 构建期配置

在 Node 环境里生效，决定打包结果。

例如：

* `.env`
* `.env.development`
* `.env.production`
* `vite.config.ts` / `weapp-vite.config.ts`

### 运行期配置

在小程序真正运行时生效，通常来自：

* 远端接口返回
* 本地缓存
* 登录态
* 灰度策略

### 宿主配置

由小程序框架和页面配置决定，例如：

* `app.json`
* `page.json`
* `definePageJson()`

## 一个推荐分层方式

你可以把项目里的配置组织成这样：

```txt
src/
├─ app.json
├─ config/
│  ├─ env.ts
│  ├─ runtime.ts
│  └─ featureFlags.ts
└─ services/
   └─ remoteConfig.ts
```

例如：

```ts
// src/config/env.ts
export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL
export const APP_ENV = import.meta.env.MODE
```

```ts
// src/config/runtime.ts
export interface RuntimeConfig {
  enableNewCouponFlow: boolean
  customerServiceUrl: string
}
```

```ts
// src/services/remoteConfig.ts
export async function loadRuntimeConfig(): Promise<RuntimeConfig> {
  return request({
    url: '/api/runtime-config',
  })
}
```

这样做的好处是：

* 构建期变量和运行期变量天然分开
* 页面里不会到处散落环境判断
* 排查问题时知道该去哪里看

## 一个最小示例：按环境切换 API 域名

```env
# .env.development
VITE_API_BASE_URL=https://dev-api.example.com
```

```env
# .env.production
VITE_API_BASE_URL=https://api.example.com
```

```ts
// services/request.ts
const baseURL = import.meta.env.VITE_API_BASE_URL

export function request<T>(options: { url: string }) {
  return wx.request<T>({
    url: `${baseURL}${options.url}`,
  })
}
```

这个例子属于“构建期决定”的配置，因为域名在打包时就已经确定。

## 不要把运行时能力塞进构建期

这是新用户最常见的错误之一。

错误示例：

```ts
const token = wx.getStorageSync('token')
```

如果你把这种逻辑写进构建期执行的宏、配置函数或 Node 侧代码里，就会出问题，因为那时根本不在小程序运行环境中。

更稳的写法是：

```ts
export function getToken() {
  return wx.getStorageSync('token')
}
```

然后在运行时调用它。

## 页面配置和业务配置不要混

例如页面标题这种宿主配置：

```ts
definePageJson(() => ({
  navigationBarTitleText: '订单详情',
}))
```

就不要和业务环境变量混在一起判断页面路径或页面存在性。

不推荐这样做：

```ts
definePageJson(() => ({
  navigationBarTitleText: import.meta.env.PROD ? '线上标题' : '测试标题',
}))
```

除非你非常清楚这样做的维护成本。

## 最小配置检查清单

```txt
[ ] 敏感信息不提交到仓库
[ ] 构建期变量只做构建期判断
[ ] 运行期状态通过 service/store/cache 获取
[ ] 页面 JSON 配置只表达页面语义
[ ] 不用环境变量拼接不稳定的页面路径
```

## 新用户建议

一开始不必设计复杂的配置中心。
先把这三件事分开就够了：

* `.env*` 管构建变量
* `services/remoteConfig.ts` 管远端运行时配置
* `app.json / definePageJson()` 管宿主配置

然后继续看：

* [构建产物到底长什么样](/handbook/build-and-output)
* [先建立 SFC 心智模型](/handbook/sfc/)

---

---
url: /handbook/build-and-output.md
description: 帮你从源码、编译结果和开发者工具视角理解 Weapp-vite 的输出结构，以及为什么很多问题必须回到 dist 里看。
---

# 构建产物到底长什么样

新用户第一次遇到构建问题时，常见反应是“源码明明是对的”。
但在小程序里，真正运行的不是源码，而是最终产物。

所以这章的核心目标只有一个：让你学会看 `dist`。

## 你平时到底在和哪两套文件打交道

日常开发时，你看到的是源码：

```txt
src/pages/user/index.vue
```

但开发者工具真正运行的，是构建后的产物：

```txt
dist/pages/user/
├─ index.js
├─ index.json
├─ index.wxml
└─ index.wxss
```

理解这件事很重要，因为很多问题只会在“源码 -> 产物”的过程中暴露：

* 路径被改错
* 页面没有被扫描到
* 样式编译后和预期不同
* JSON 合并结果和你想的不一样

## 一个 `.vue` 页面会输出什么

以这个页面为例：

```vue
<script setup lang="ts">
definePageJson(() => ({
  navigationBarTitleText: '用户中心',
}))
</script>

<template>
  <view class="page">
    user
  </view>
</template>

<style scoped>
.page {
  padding: 24rpx;
}
</style>
```

最终你至少应该预期会得到：

```txt
dist/pages/user/
├─ index.js
├─ index.json
├─ index.wxml
└─ index.wxss
```

分别可以这样理解：

* `index.js`
  页面逻辑
* `index.json`
  页面配置
* `index.wxml`
  模板结构
* `index.wxss`
  样式输出

## 调试时最值得先看的 4 个文件

### 1. `index.json`

判断：

* 页面标题有没有生效
* `usingComponents` 有没有写进去
* 页面配置最终合并结果是否正确

### 2. `index.wxml`

判断：

* 模板是不是被正确编译
* 条件渲染、循环、事件绑定是不是按预期输出

### 3. `index.js`

判断：

* 页面逻辑有没有真正输出
* 导入依赖是否缺失

### 4. `app.json`

判断：

* 页面是不是被纳入应用
* 路由顺序和分包配置是否正确

## 最常见的 5 类构建问题

### 1. 页面没生成

通常是：

* 路径不符合扫描规则
* 没被路由系统纳入
* 文件命名不符合约定

### 2. 组件生成了，但页面里用不了

优先看 `usingComponents` 是否正确生成到 `json` 里。

### 3. 图片、字体、静态资源路径不对

这类问题通常只看源码很难判断，必须回到 `dist` 看重写结果。

### 4. 分包里引用路径错了

尤其是：

* 主包组件引用分包资源
* 分包页面引用共享资源
* 静态资源没有跟随正确输出

### 5. dev 正常，build 不正常

这通常意味着：

* 最终产物路径或资源策略有问题
* 依赖兼容性在正式构建阶段才暴露
* 开发者工具看的目录和构建目录不一致

## 一个很实用的排查习惯

每次你怀疑“是不是编译错了”，就按这个顺序看：

1. 源码是否正确
2. `dist` 里对应页面文件是否完整
3. 开发者工具导入的目录是否就是当前 `dist`
4. 构建日志里有没有跳过、警告或兼容性提示

## 最小检查清单

上线前至少做一次这样的确认：

```txt
[ ] app.json 中的页面路径正确
[ ] dist 中每个关键页面都有 js/json/wxml/wxss
[ ] 关键静态资源路径在产物中可访问
[ ] usingComponents 生成符合预期
[ ] 分包页面能在开发者工具中正常打开
```

看完这一章，你下一步最适合继续补的是：

* [环境变量与配置怎么分层](/handbook/env-and-config)
* [页面跳转与路由参数](/handbook/navigation)
* [分包与包体策略](/handbook/subpackages)

---

---
url: /handbook/sfc.md
description: 解释 .vue 文件在 weapp-vite 里是怎么被编译成小程序四件套的，以及写 Vue SFC 时哪些地方和 Web Vue 一样，哪些地方不一样。
---

# .vue 怎么变成小程序

如果你写过 Web Vue，第一次写小程序 SFC 的时候很容易产生一个错觉："这不就是在写普通 Vue 吗？"

写法确实很像，但跑的地方完全不一样。

## 一个 .vue 文件最终会变成什么

你写的是这样：

```vue
<script setup lang="ts">
import { ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '商品页',
}))

const count = ref(0)
</script>

<template>
  <view class="page">
    <text>{{ count }}</text>
  </view>
</template>

<style scoped>
.page {
  padding: 24rpx;
}
</style>
```

构建之后，它会变成：

```txt
dist/pages/product/
├─ index.js      ← script 部分
├─ index.json    ← definePageJson 的输出
├─ index.wxml    ← template 部分
└─ index.wxss    ← style 部分
```

所以你写 SFC 的时候，脑子里要同时想两件事：

* 我在用 Vue 的方式组织代码
* 但最终产物要遵守小程序的规则

## 四个块各自负责什么

### `<template>`

写视图结构。但要用小程序的标签，不是 HTML 标签：

```vue
<template>
  <view class="card">
    <text>{{ title }}</text>
    <button @tap="submit">
      提交
    </button>
  </view>
</template>
```

用 `view` 不用 `div`，用 `text` 不用 `span`，用 `@tap` 不用 `@click`。

### `<script setup>`

写页面逻辑。推荐默认就用 `<script setup lang="ts">`：

```vue
<script setup lang="ts">
import { computed, ref } from 'wevu'

const price = ref(100)
const discount = ref(0.8)
const finalPrice = computed(() => price.value * discount.value)
</script>
```

### `definePageJson()`

声明页面配置。这是小程序特有的，Web Vue 里没有：

```ts
definePageJson(() => ({
  navigationBarTitleText: '订单列表',
  enablePullDownRefresh: true,
}))
```

它会被编译成页面的 `.json` 文件。

### `<style>`

写样式。最终会变成 `.wxss`，所以有些浏览器里能用的 CSS 在这里不一定行：

```vue
<style scoped>
.page {
  padding: 24rpx; /* rpx 是小程序的响应式单位 */
}
</style>
```

## 和 Web Vue 最容易搞混的三件事

### 1. 响应式 API 要从 wevu 导入

这是新手最常踩的坑。在小程序里，`ref`、`computed`、`watch` 这些要从 `wevu` 导入：

```ts
// ❌ 错的 — 从 vue 导入的在小程序运行时里不会触发页面更新
import { computed, ref } from 'vue'

// ✅ 对的
import { computed, ref } from 'wevu'
```

### 2. 模板最终是 WXML，不是浏览器 DOM

你看到的是 Vue 风格的模板语法，但它会被编译成 WXML。这意味着：

* 事件不是标准 DOM Event，是小程序事件
* 模板表达式的能力有边界
* 不是所有 Vue 的高级模板特性都能用

### 3. 页面配置是小程序概念

`definePageJson()` 设置的是小程序页面的标题、下拉刷新、组件声明这些东西，这在浏览器里是不存在的。

## 一个典型的页面长什么样

```vue
<script setup lang="ts">
import { ref } from 'wevu'
import ProductCard from '../../components/product-card/index.vue'

definePageJson(() => ({
  navigationBarTitleText: '商品列表',
}))

const products = ref([
  { id: '1', title: '键盘', price: 199 },
  { id: '2', title: '鼠标', price: 99 },
])
</script>

<template>
  <view class="page">
    <ProductCard
      v-for="item in products"
      :key="item.id"
      :title="item.title"
      :price="item.price"
    />
  </view>
</template>

<style scoped>
.page {
  padding: 32rpx;
}
</style>
```

这里面你能看到：

* 组件可以直接 `import .vue` 来用
* `v-for`、`:key`、`:title` 这些 Vue 语法都能用
* 但标签是 `view` 不是 `div`

## 怎么判断一个写法在小程序里行不行

问自己一个问题：

> 这个东西最终会落到模板、JSON、事件还是样式产物上？

如果会，就要考虑小程序的限制。比如你想用 `<teleport>`，这在小程序里是没有的，因为 WXML 没有这个概念。

## 接下来

* [模板和事件怎么写](/handbook/sfc/template)
* [脚本逻辑怎么组织](/handbook/sfc/script-setup)
* [组件怎么拆](/handbook/sfc/components)

---

---
url: /handbook/sfc/template.md
description: 小程序 SFC 模板的日常写法：条件渲染、列表、事件绑定、v-model，以及哪些 Web Vue 的习惯要收一收。
---

# 模板和事件怎么写

模板长得像 Vue，但最终会编译成 WXML。所以关键不是"会不会写"，而是"哪些写法最稳"。

## 日常最常用的几种写法

先看一个包含了大部分常见场景的页面：

```vue
<script setup lang="ts">
import { computed, ref } from 'wevu'

const keyword = ref('')
const goodsList = ref([
  { id: '1', title: '键盘', price: 199 },
  { id: '2', title: '鼠标', price: 99 },
])

const hasData = computed(() => goodsList.value.length > 0)

function onSearchInput(event: any) {
  keyword.value = event.detail.value
}
</script>

<template>
  <view class="page">
    <input :value="keyword" placeholder="搜索商品" @input="onSearchInput">

    <view v-if="hasData">
      <view v-for="item in goodsList" :key="item.id" class="goods-item">
        <text>{{ item.title }}</text>
        <text>¥{{ item.price }}</text>
      </view>
    </view>

    <view v-else class="empty">
      暂无数据
    </view>
  </view>
</template>
```

这里面用到了：`v-if` / `v-else`、`v-for`、`:value`（属性绑定）、`@input`（事件绑定）。这四种覆盖了日常 80% 的模板需求。

## 条件渲染

```vue
<view v-if="loading">
加载中...
</view>

<view v-else-if="list.length">
列表内容
</view>

<view v-else>
空状态
</view>
```

建议把判断逻辑收到脚本里，模板只负责展示：

```ts
const isEmpty = computed(() => !loading.value && list.value.length === 0)
```

## 列表渲染

```vue
<view v-for="item in list" :key="item.id">
  {{ item.title }}
</view>
```

`:key` 尽量用稳定的唯一标识（比如 `id`），不要用数组索引。

列表项复杂的话，尽早拆成子组件：

```vue
<GoodsCard
  v-for="item in list"
  :key="item.id"
  :title="item.title"
  :price="item.price"
/>
```

## 事件绑定

优先用小程序的事件名：

```vue
<button @tap="submitOrder">
提交订单
</button>

<input @input="onInput" @blur="onBlur">

<picker @change="onPickerChange">
...
</picker>
```

用 `@tap` 而不是 `@click`，因为这更贴近小程序的真实语义，团队不容易搞混。

事件对象里的值通常在 `event.detail` 里：

```ts
function onInput(event: any) {
  const value = event.detail.value
}
```

## v-model

简单输入场景可以直接用 `v-model`：

```vue
<input v-model="form.name" placeholder="请输入姓名">
```

但要记住一个限制：`v-model` 后面必须是可赋值的左值。

```vue
<!-- ✅ 这些可以 -->
<input v-model="form.name" />

<input v-model="form.price" />

<input v-model="list[index].title" />

<!-- ❌ 这些不行 -->
<input v-model="a + b" />

<input v-model="getName()" />
```

如果事件名不是 `input`，或者取值不在 `detail.value`，就别硬用 `v-model`，改成显式写法更稳：

```vue
<slider :value="budget" @change="onBudgetChange" />
```

```ts
function onBudgetChange(event: any) {
  budget.value = Number(event.detail.value)
}
```

## 页面配置

每个页面都可以通过 `definePageJson()` 声明配置：

```ts
definePageJson(() => ({
  navigationBarTitleText: '订单详情',
  enablePullDownRefresh: true,
}))
```

App 入口用 `defineAppJson`，组件用 `defineComponentJson`：

```ts
// app.vue
defineAppJson({
  pages: ['pages/home/index', 'pages/profile/index'],
})

// 组件
defineComponentJson(() => ({
  component: true,
}))
```

新项目统一用这些宏就好。老项目里可能还有 `<json>` 块，那是历史兼容写法。

## 动态 class

```vue
<view :class="{ active: isActive, disabled: loading }" />

<view :class="['item', { selected: isSelected }]" />
```

行内 style 能用但建议克制，样式逻辑尽量交给 class。

## 模板里不要做的事

### 不要放复杂计算

```vue
<!-- 不推荐 -->
<text>
{{ price * count * discountMap[type] }}
</text>

<!-- 推荐：算好了再展示 -->
<text>
{{ finalPrice }}
</text>
```

### 不要调有副作用的函数

```vue
<!-- 不推荐 -->
<text>
{{ trackExpose(item.id) }}
</text>
```

模板应该是纯展示的。

## 原生 WXML 语法

weapp-vite 编译模板的时候，Vue 指令（`v-if`、`v-for`）会自动转成对应的 `wx:if`、`wx:for`。你不需要手写 `wx:*`。

但如果你确实需要用原生 WXML 的能力（比如 `<import>`、`<wxs>`、WXML 模板），也可以直接写：

```html
<import src="/partials/card.wxml" />
<template is="card" data="{{item}}" />
```

`<template>` 标签在 Vue 和 WXML 里都有含义。规则是：

* 有 `name`、`is`、`data` 属性的 → 保留为 WXML 模板
* 有 `v-for`、`v-if` 的 → 编译成 `<block>`
* 什么都没有的 → 直接展开子节点

## 接下来

* [脚本逻辑怎么组织](/handbook/sfc/script-setup)
* [组件怎么拆](/handbook/sfc/components)

---

---
url: /handbook/sfc/script-setup.md
description: 用 script setup 写页面和组件的推荐范式，包括代码组织顺序、生命周期用法、Options API 兼容写法。
---

# 脚本逻辑怎么组织

新项目默认用 `<script setup lang="ts">`。不是因为它时髦，而是因为它和 wevu 的 hooks、响应式写法配合得最自然。

## 一个页面的推荐写法

```vue
<script setup lang="ts">
import { computed, onLoad, ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '商品列表',
}))

const keyword = ref('')
const goodsList = ref<{ id: string, title: string }[]>([])
const loading = ref(false)

const hasData = computed(() => goodsList.value.length > 0)

onLoad(() => {
  console.log('page loaded')
})
</script>
```

这里面有几个值得固定下来的习惯：

* 响应式 API 和 hooks 都从 `wevu` 导入
* 页面配置用 `definePageJson()` 宏
* 代码按"状态 → 派生状态 → 方法 → 生命周期"的顺序排

## 推荐的代码组织顺序

```ts
// 1. import
import { computed, onLoad, onShow, ref } from 'wevu'
import { getOrderList } from '../../services/order'

// 2. 页面配置
definePageJson(() => ({
  navigationBarTitleText: '购物车',
}))

// 3. 状态
const list = ref<CartItem[]>([])
const loading = ref(false)

// 4. 派生状态
const totalPrice = computed(() =>
  list.value.reduce((sum, item) => sum + item.price * item.count, 0),
)

// 5. 方法
function clearCart() {
  list.value = []
}

// 6. 生命周期
onLoad(() => {
  // 首次加载
})

onShow(() => {
  // 每次页面可见
})
```

不用死记，写几个页面就习惯了。关键是团队统一，不要每个页面都换一种组织方式。

## 生命周期怎么用

### 页面常用的 hooks

```ts
import { onHide, onLoad, onReady, onShow, onUnload } from 'wevu'

onLoad((query) => {
  // 页面首次加载，能拿到路由参数
  // 适合：读参数、发首次请求
})

onShow(() => {
  // 每次页面可见都会触发（包括从其他页面返回）
  // 适合：刷新数据、恢复定时器
})

onReady(() => {
  // 首次渲染完成
  // 适合：DOM 查询（createSelectorQuery）
})

onHide(() => {
  // 页面隐藏
  // 适合：暂停定时器
})

onUnload(() => {
  // 页面销毁
  // 适合：清理资源
})
```

触发顺序：`onLoad → onShow → onReady → ... → onHide → onShow → ... → onUnload`

### 交互类 hooks

```ts
import { onPullDownRefresh, onReachBottom, onShareAppMessage } from 'wevu'

// 下拉刷新（需要在 definePageJson 里开启 enablePullDownRefresh）
onPullDownRefresh(async () => {
  await refreshData()
  wx.stopPullDownRefresh()
})

// 触底加载更多
onReachBottom(() => {
  if (hasMore.value) {
    loadNextPage()
  }
})

// 分享
onShareAppMessage(() => ({
  title: '推荐给你',
  path: '/pages/goods/index?id=sku-1',
}))
```

### 组件的 hooks

组件和页面的生命周期不完全一样：

```ts
import { onAttached, onDetached, onReady } from 'wevu'

onAttached(() => {
  // 组件挂载到页面
})

onReady(() => {
  // 组件渲染完成
})

onDetached(() => {
  // 组件从页面移除
})
```

组件没有 `onShow` / `onHide`，这两个是页面专属的。

### 最重要的规则：hooks 必须同步注册

所有 hooks 都要在 `setup()` 的顶层同步注册，不能放在 `await` 后面：

```ts
// ✅ 对的：hook 同步注册，回调里面可以异步
onLoad(async (query) => {
  const data = await fetchData(query.id)
})

// ❌ 错的：在 await 之后注册
await someAsyncWork()
onShow(() => {}) // 这时候可能已经失效了
```

原因是 wevu 需要在同步阶段把 hook 绑定到当前实例上。一旦进入异步，实例上下文可能已经丢了。

## 组件导入

直接 `import .vue` 就能用：

```vue
<script setup lang="ts">
import EmptyState from '../../components/empty-state/index.vue'
import GoodsCard from '../../components/goods-card/index.vue'
</script>

<template>
  <GoodsCard />
  <EmptyState />
</template>
```

这比手写 `usingComponents` 更直观，IDE 跳转也更稳。

## app.vue 入口

全局逻辑、全局样式、全局配置都可以收到 `app.vue` 里：

```vue
<script setup lang="ts">
import { onLaunch } from 'wevu'

defineAppJson({
  pages: [
    'pages/home/index',
    'pages/profile/index',
  ],
})

onLaunch(() => {
  console.log('app launched')
})
</script>

<style>
page {
  font-size: 28rpx;
  color: #333;
}
</style>
```

## 如果你更习惯 Options API

从原生小程序迁移过来的话，可以先用 `defineComponent`：

```vue
<script lang="ts">
import { defineComponent, onLoad, ref } from 'wevu'

export default defineComponent({
  setup() {
    const count = ref(0)

    onLoad(() => {
      console.log('loaded')
    })

    return { count }
  },
})
</script>
```

核心逻辑还是写在 `setup()` 里。等团队熟悉了，再逐步切到 `<script setup>`。

迁移路径：先把 `data` 集中到 `setup` 里的 `ref` → 再把 `defineComponent` 换成 `<script setup>`。

## 三个最常见的错误

### 1. 从 vue 导入响应式 API

```ts
// ❌
import { ref } from 'vue'
// ✅
import { ref } from 'wevu'
```

### 2. 在异步回调里注册 hooks

```ts
// ❌
await fetchSomething()
onShow(() => {})
```

### 3. 忘了清理定时器

```ts
let timer: ReturnType<typeof setInterval> | null = null

onShow(() => {
  timer = setInterval(pollStatus, 5000)
})

onHide(() => {
  if (timer) {
    clearInterval(timer)
    timer = null
  }
})
```

## 接下来

* [样式和资源怎么处理](/handbook/sfc/style)
* [组件怎么拆](/handbook/sfc/components)

---

---
url: /handbook/sfc/style.md
description: SFC 里的样式怎么落到 WXSS、scoped 的真实行为、预处理器怎么选、图片和字体怎么引用。
---

# 样式和资源怎么处理

小程序里写样式，最容易踩的坑不是"不会写 CSS"，而是以为和浏览器里一模一样。

## 样式最终会变成 WXSS

你在 `.vue` 里写的 `<style>`，构建后会变成 `.wxss` 文件。所以有两层约束要同时考虑：

* 你用的预处理器（SCSS / Less）的能力
* 小程序 WXSS 本身的能力

## scoped 是怎么回事

`scoped` 不是浏览器的 Shadow DOM，是编译期的选择器改写：给当前组件的元素加一个唯一属性（`data-v-xxxxx`），选择器也加上这个属性。

效果是同名 class 不会跨组件污染。但如果你想在父组件里改子组件的样式，会被 scoped 挡住。需要穿透的话用 `:deep()`：

```vue
<style scoped>
.parent :deep(.child-inner) {
  color: red;
}
</style>
```

全局样式（比如 `app.vue` 里的基础样式）不需要 scoped：

```vue
<!-- app.vue -->
<style>
page {
  font-size: 28rpx;
  color: #333;
  background: #f5f5f5;
}
</style>
```

## 小程序对 CSS 的限制

### 选择器

这些是安全的：`.class`、`#id`、`.parent .child`、`.parent > .child`、`::after`、`::before`。

这些要小心：`:nth-child()`、`:first-child`（部分基础库不支持）、`*`（通配符）。

### 不一定能用的 CSS

* `position: fixed` 在某些场景表现不同
* `z-index` 在原生组件上可能失效
* `vh` / `vw` 支持有限，用 `rpx` 更稳
* CSS 变量（`var()`）需要较新的基础库
* `backdrop-filter`、复杂 `grid` 布局可能不支持

### rpx 是主力单位

```css
/* 750rpx = 屏幕宽度 */
.container {
  padding: 32rpx;
  font-size: 28rpx;
}
```

## 预处理器

团队统一选一种就好，不要混用。推荐 SCSS：

```vue
<style lang="scss" scoped>
$primary: #1890ff;

.card {
  padding: 24rpx;
  background: #fff;

  &-title {
    font-size: 32rpx;
    color: $primary;
  }
}
</style>
```

## 样式怎么组织

* 全局基础样式放 `app.vue`（不加 scoped）
* 页面样式加 scoped
* 组件样式加 scoped

```vue
<!-- components/goods-card/index.vue -->
<style lang="scss" scoped>
.goods-card {
  display: flex;
  padding: 24rpx;

  &__title {
    font-size: 28rpx;
  }

  &__price {
    color: #ff4d4f;
  }
}
</style>
```

## 图片怎么引用

### 小图片：放在页面或组件旁边

```txt
pages/order-detail/
├─ index.vue
└─ assets/
   └─ status-paid.png
```

```ts
import statusPaid from './assets/status-paid.png'
```

好处是页面下线的时候资源一起删，不会留垃圾。

### 跨页面复用的图片：放 `src/assets/`

```txt
src/assets/images/
├─ logo.png
├─ empty-state.png
└─ default-avatar.png
```

### 大图：走 CDN

小程序包体有大小限制，大图不要打包进去：

```vue
<image
  src="https://cdn.example.com/images/banner.jpg"
  mode="aspectFill"
  lazy-load
/>
```

CDN 域名要在小程序后台配白名单。

### 分包里的图片

分包页面引用主包的图片，构建后路径可能会错。稳妥的做法：

* 分包专属的图片放在分包目录里
* 真正共享的图片走 CDN 或放在明确的共享目录

## 字体

小图标推荐用 iconfont 的 base64 方式，或者直接用小图片代替。

自定义字体可以运行时加载：

```ts
wx.loadFontFace({
  family: 'CustomFont',
  source: 'url("https://cdn.example.com/fonts/custom.woff2")',
})
```

但要注意加载是异步的，字体 URL 也需要域名白名单。

## 样式问题排查

遇到样式不对，先去 `dist` 里看最终的 `.wxss` 文件。很多时候问题出在：

* 选择器被 scoped 改写后不符合预期
* 用了小程序不支持的 CSS 特性
* 开发者工具和真机渲染不一致（尤其是字体和间距）

## 接下来

* [组件怎么拆](/handbook/sfc/components)
* [常用写法速查](/handbook/sfc/cookbook)

---

---
url: /handbook/sfc/components.md
description: 什么时候该拆组件、怎么导入、什么时候还需要 usingComponents、原生组件怎么接类型。
---

# 组件怎么拆

页面能跑起来之后，下一个问题就是：什么时候该拆组件，拆完怎么接回页面。

## 默认方式：直接 import .vue

```vue
<script setup lang="ts">
import OrderCard from './components/order-card.vue'
import OrderEmpty from './components/order-empty.vue'
</script>

<template>
  <OrderCard v-for="item in list" :key="item.id" :data="item" />
  <OrderEmpty v-if="isEmpty" />
</template>
```

这是新项目推荐的默认方式。好处是 IDE 跳转稳、重构安全、依赖关系一目了然。

## 什么时候该拆

出现这些信号就值得拆：

* 页面模板超过 100 行了
* 同一块 UI 在多个页面出现
* 某块区域有自己的状态和行为
* 你开始复制粘贴同样的模板结构

## 放哪里

只服务当前页面的组件，放页面目录下：

```txt
pages/order-list/
├─ index.vue
└─ components/
   ├─ order-card.vue
   └─ order-empty.vue
```

多个页面稳定复用的，放全局 `components/`：

```txt
src/components/
├─ empty-state/index.vue
├─ price-text/index.vue
└─ loading-view/index.vue
```

判断标准很简单：如果这个组件只有一个页面在用，就放页面目录。等第二个页面也要用的时候再提升到全局。

## 什么时候还需要 usingComponents

直接 `import .vue` 能覆盖大部分场景。但这些情况还是需要 `usingComponents`：

* 接第三方原生小程序组件（不是 `.vue` 的）
* 引入原生组件目录
* 历史项目还没迁移到 SFC import

```ts
definePageJson(() => ({
  usingComponents: {
    'native-uploader': '/components/native-uploader/index',
  },
}))
```

## 组件的 props 和事件

用 `defineProps` 和 `defineEmits`：

```vue
<!-- components/goods-card/index.vue -->
<script setup lang="ts">
const props = defineProps<{
  title: string
  price: number
}>()

const emit = defineEmits<{
  select: [id: string]
}>()

function onTap() {
  emit('select', 'sku-1')
}
</script>

<template>
  <view class="goods-card" @tap="onTap">
    <text>{{ props.title }}</text>
    <text>¥{{ props.price }}</text>
  </view>
</template>
```

父组件使用：

```vue
<GoodsCard title="键盘" :price="199" @select="onGoodsSelect" />
```

如果用的是 `defineComponent` 风格，props 通过 `properties` 声明：

```ts
export default defineComponent({
  properties: {
    title: { type: String, value: '' },
    price: { type: Number, value: 0 },
  },
  setup(props, ctx) {
    // props.title, props.price
    // ctx.emit('select', data)
  },
})
```

## 原生组件怎么加类型

如果你引入的是原生小程序组件（不是 `.vue`），可以用 wevu 提供的类型工具补齐 props 提示：

```ts
import type { InferNativeProps, NativeComponent, NativePropType } from 'wevu'

type Tone = 'neutral' | 'success' | 'danger'

const nativeProperties = {
  label: { type: String, value: '' },
  tone: {
    type: String as NativePropType<Tone>,
    value: 'neutral',
  },
}

type NativeBadgeProps = InferNativeProps<typeof nativeProperties>
const NativeBadge = {} as NativeComponent<NativeBadgeProps>
export default NativeBadge
```

然后在页面里正常用，有类型提示：

```vue
<NativeBadge label="已完成" tone="success" />
```

## 插槽

插槽可以用，但不要默认以为 Web Vue 里复杂的作用域插槽都能照搬。优先用结构清晰的默认插槽：

```vue
<BaseCard>
  <view>这里是插槽内容</view>
</BaseCard>
```

## 接下来

* [常用写法速查](/handbook/sfc/cookbook)
* [Wevu 是什么，不是什么](/handbook/wevu/)

---

---
url: /handbook/sfc/cookbook.md
description: 小程序 SFC 项目里最常见的业务场景写法，可以直接照着改。
---

# 常用写法速查

这一页不讲理论，就是一组"遇到这个需求，先这么写"的起手式。代码可以直接拿去改。

## 列表页

一个稳定的列表页至少要处理：loading、空状态、错误、下拉刷新、触底加载。

```vue
<script setup lang="ts">
import { computed, onLoad, onPullDownRefresh, onReachBottom, ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '商品列表',
  enablePullDownRefresh: true,
}))

const list = ref<GoodsItem[]>([])
const page = ref(1)
const loading = ref(false)
const error = ref('')
const hasMore = ref(true)
const isEmpty = computed(() => !loading.value && !error.value && list.value.length === 0)

async function loadList(pageNum: number) {
  if (loading.value) {
    return
  }
  loading.value = true
  error.value = ''
  try {
    const result = await getGoodsList({ page: pageNum, size: 20 })
    if (pageNum === 1) {
      list.value = result.items
    }
    else {
      list.value = [...list.value, ...result.items]
    }
    hasMore.value = result.hasMore
    page.value = pageNum
  }
  catch {
    error.value = '加载失败，请重试'
  }
  finally {
    loading.value = false
  }
}

onLoad(() => loadList(1))

onPullDownRefresh(async () => {
  await loadList(1)
  wx.stopPullDownRefresh()
})

onReachBottom(() => {
  if (hasMore.value) {
    loadList(page.value + 1)
  }
})
</script>

<template>
  <view class="page">
    <view v-if="list.length" class="list">
      <view v-for="item in list" :key="item.id" class="item">
        <text>{{ item.title }}</text>
        <text class="price">¥{{ item.price }}</text>
      </view>
    </view>
    <view v-if="isEmpty" class="empty">
      暂无商品
    </view>
    <view v-if="error" class="error">
      <text>{{ error }}</text>
      <button size="mini" @tap="() => loadList(1)">
        重试
      </button>
    </view>
    <view v-if="loading" class="loading">
      加载中...
    </view>
    <view v-else-if="!hasMore && list.length" class="no-more">
      没有更多了
    </view>
  </view>
</template>
```

## 详情页

```vue
<script setup lang="ts">
import { onLoad, ref } from 'wevu'

definePageJson(() => ({ navigationBarTitleText: '商品详情' }))

const detail = ref<GoodsDetail | null>(null)
const loading = ref(true)
const error = ref('')

onLoad(async (query) => {
  if (!query.id) {
    error.value = '参数错误'
    loading.value = false
    return
  }
  try {
    detail.value = await getGoodsDetail(query.id)
  }
  catch {
    error.value = '加载失败'
  }
  finally {
    loading.value = false
  }
})
</script>

<template>
  <view class="page">
    <view v-if="loading">
      加载中...
    </view>
    <view v-else-if="error">
      {{ error }}
    </view>
    <view v-else-if="detail" class="detail">
      <image :src="detail.imageUrl" mode="aspectFill" class="cover" />
      <text class="title">{{ detail.title }}</text>
      <text class="price">¥{{ detail.price }}</text>
    </view>
  </view>
</template>
```

## 表单页

```vue
<script setup lang="ts">
import { ref } from 'wevu'

definePageJson(() => ({ navigationBarTitleText: '新建地址' }))

const form = ref({ name: '', phone: '', detail: '' })
const errors = ref<Record<string, string>>({})
const submitting = ref(false)

function validate(): boolean {
  const e: Record<string, string> = {}
  if (!form.value.name.trim()) {
    e.name = '请输入姓名'
  }
  if (!/^1\d{10}$/.test(form.value.phone)) {
    e.phone = '请输入正确手机号'
  }
  if (!form.value.detail.trim()) {
    e.detail = '请输入详细地址'
  }
  errors.value = e
  return Object.keys(e).length === 0
}

async function submit() {
  if (!validate() || submitting.value) {
    return
  }
  submitting.value = true
  try {
    await saveAddress(form.value)
    wx.showToast({ title: '保存成功' })
    wx.navigateBack()
  }
  catch {
    wx.showToast({ title: '保存失败', icon: 'none' })
  }
  finally {
    submitting.value = false
  }
}
</script>

<template>
  <view class="form">
    <view class="field">
      <text class="label">姓名</text>
      <input v-model="form.name" placeholder="请输入姓名">
      <text v-if="errors.name" class="error">{{ errors.name }}</text>
    </view>
    <view class="field">
      <text class="label">手机号</text>
      <input v-model="form.phone" type="number" placeholder="请输入手机号">
      <text v-if="errors.phone" class="error">{{ errors.phone }}</text>
    </view>
    <view class="field">
      <text class="label">详细地址</text>
      <textarea v-model="form.detail" placeholder="请输入详细地址" />
      <text v-if="errors.detail" class="error">{{ errors.detail }}</text>
    </view>
    <button :disabled="submitting" @tap="submit">
      {{ submitting ? '保存中...' : '保存地址' }}
    </button>
  </view>
</template>
```

## 登录拦截

```ts
// utils/auth.ts
export function ensureLogin(targetPath?: string): boolean {
  const token = wx.getStorageSync('token')
  if (token) {
    return true
  }

  const currentPage = getCurrentPages().at(-1)
  const redirect = targetPath || (currentPage ? `/${currentPage.route}` : '/pages/home/index')
  wx.navigateTo({ url: `/pages/login/index?redirect=${encodeURIComponent(redirect)}` })
  return false
}
```

页面里用：

```ts
function onBuyTap() {
  if (!ensureLogin()) {
    return
  }
  wx.navigateTo({ url: '/pages/checkout/index' })
}
```

## 分享

```vue
<script setup lang="ts">
import { onShareAppMessage, onShareTimeline } from 'wevu'

onShareAppMessage(() => ({
  title: '推荐给你',
  path: `/pages/goods/index?id=${goodsId.value}`,
  imageUrl: goodsImage.value,
}))

onShareTimeline(() => ({
  title: '限时优惠',
  query: `id=${goodsId.value}`,
}))
</script>

<template>
  <button open-type="share">
    分享给好友
  </button>
</template>
```

注意：`onShareAppMessage` 需要用户点右上角菜单的"转发"或者页面里有 `open-type="share"` 的按钮才会触发。

## Tab 切换

```vue
<script setup lang="ts">
import { ref } from 'wevu'

const tabs = [
  { key: 'all', label: '全部' },
  { key: 'pending', label: '待付款' },
  { key: 'shipped', label: '待收货' },
]
const activeTab = ref('all')

function onTabChange(key: string) {
  if (activeTab.value === key) {
    return
  }
  activeTab.value = key
  loadListByStatus(key)
}
</script>

<template>
  <view class="tabs">
    <view
      v-for="tab in tabs"
      :key="tab.key"
      class="tab" :class="[{ active: activeTab === tab.key }]"
      @tap="() => onTabChange(tab.key)"
    >
      {{ tab.label }}
    </view>
  </view>
</template>
```

## Toast / Modal 封装

```ts
// utils/toast.ts
export function showSuccess(title: string) {
  wx.showToast({ title, icon: 'success' })
}

export function showError(title: string) {
  wx.showToast({ title, icon: 'none' })
}

export function confirm(content: string, title = '提示'): Promise<boolean> {
  return new Promise((resolve) => {
    wx.showModal({
      title,
      content,
      success: res => resolve(res.confirm),
      fail: () => resolve(false),
    })
  })
}
```

## 接下来

写页面的基本功到这里差不多了。接下来去理解一下 wevu 运行时到底在做什么：

* [Wevu 是什么，不是什么](/handbook/wevu/)
* [响应式和生命周期](/handbook/wevu/runtime)

---

---
url: /handbook/wevu.md
description: 搞清楚 wevu 在这套技术栈里的定位：它负责什么、不负责什么、和 Vue 是什么关系。
---

# Wevu 是什么，不是什么

你在前面的章节里已经用过 `ref`、`computed`、`onLoad` 这些 API 了。它们都来自 `wevu`。

这一章把 wevu 的定位讲清楚，这样你遇到问题的时候能更快判断该往哪个方向查。

## 一句话说清楚

wevu 是小程序的运行时层。它让你能用接近 Vue 3 的方式写响应式状态和生命周期，但底下跑的还是小程序。

## 它负责什么

* 响应式：`ref`、`reactive`、`computed`、`watch`、`watchEffect`
* 生命周期：`onLoad`、`onShow`、`onHide`、`onReady`、`onUnload` 等
* 组件定义：`defineComponent`、`createApp`
* 状态管理：`defineStore`、`storeToRefs`
* 最小化更新：自动做快照 diff，只把变化的部分传给 `setData`
* 双向绑定辅助：`bindModel`、`useBindModel`

## 它不负责什么

* 不负责把 `.vue` 编译成小程序文件（那是 weapp-vite 的事）
* 不负责浏览器 DOM 渲染（小程序没有 DOM）
* 不负责把 Web Vue 的所有能力 1:1 搬过来
* 不负责突破小程序宿主本身的限制

## 和 Vue 是什么关系

wevu 借鉴了 Vue 3 的响应式心智模型，但不是 Vue 3 的子集或移植版。

最大的区别：

* 没有 Virtual DOM。wevu 用快照 diff + `setData` 来更新视图
* 没有浏览器 DOM。模板最终是 WXML，不是 HTML
* 事件是小程序事件，不是标准 DOM Event
* 组件树的行为受小程序宿主约束

如果你把 wevu 理解成"面向小程序约束重新设计的一套 Vue 风格运行时"，会比理解成"Vue 3 的缩小版"更准确。

## 为什么不直接用原生写法

原生小程序的 `Page()` + `setData()` 在简单页面里没问题。但页面一复杂，问题就来了：

```ts
// 原生写法
Page({
  data: { count: 0, loading: false, list: [] },
  onLoad() { this.fetchList() },
  async fetchList() {
    this.setData({ loading: true })
    const list = await request({ url: '/api/products' })
    this.setData({ loading: false, list })
  },
})
```

状态散在 `data` 里，逻辑复用困难，生命周期和副作用越来越难拆。

用 wevu 的话，同样的逻辑可以抽成 composable：

```ts
import { onLoad, ref } from 'wevu'

export function useProductList() {
  const list = ref([])
  const loading = ref(false)

  async function fetchList() {
    loading.value = true
    try {
      list.value = await request({ url: '/api/products' })
    }
    finally {
      loading.value = false
    }
  }

  onLoad(fetchList)
  return { list, loading, fetchList }
}
```

状态和副作用可以抽出去、可以复用、可以测试。这是 wevu 最核心的价值。

## 什么时候可以不用

如果页面极度简单（纯展示、几乎没有交互），不用 wevu 也行。关键不是"必须到处用"，而是当页面复杂度上来的时候，wevu 能让代码结构更稳。

## 接下来

* [响应式和生命周期](/handbook/wevu/runtime) — 理解 setup、hooks 和页面更新机制
* [组件通信](/handbook/wevu/component) — props、emit、slots
* [状态管理](/handbook/wevu/store) — 什么时候该上 store

---

---
url: /handbook/wevu/runtime.md
description: 理解 wevu 的 setup 上下文、响应式系统和页面更新机制。
---

# 响应式和生命周期

上一章讲了 wevu 是什么。这一章讲它到底是怎么工作的。

## setup 是怎么回事

不管你用 `<script setup>` 还是 `defineComponent`，核心都是一个 `setup` 函数。wevu 在这个函数里做三件事：

1. 同步创建响应式状态
2. 同步注册生命周期 hooks
3. 把状态暴露给模板消费

```ts
import { defineComponent, onShow, ref } from 'wevu'

export default defineComponent({
  setup() {
    const count = ref(0)

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

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

    return { count, increase }
  },
})
```

用 `<script setup>` 的话更简洁，但本质是一样的：

```vue
<script setup lang="ts">
import { onShow, ref } from 'wevu'

const count = ref(0)

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

onShow(() => {
  console.log('page show')
})
</script>
```

## 响应式系统

wevu 的响应式 API 和 Vue 3 基本一致：

```ts
import { computed, reactive, ref, watch, watchEffect } from 'wevu'

// ref：基础响应式值
const count = ref(0)
count.value += 1

// reactive：响应式对象
const state = reactive({ name: '', age: 0 })
state.name = '张三'

// computed：派生状态
const doubled = computed(() => count.value * 2)

// watch：监听变化
watch(count, (newVal, oldVal) => {
  console.log(`count changed: ${oldVal} → ${newVal}`)
})

// watchEffect：自动追踪依赖
watchEffect(() => {
  console.log('count is', count.value)
})
```

### 状态更新怎么反映到页面

你改了 `ref` 的值，页面就会更新。中间发生的事情大概是：

1. 你修改了响应式值
2. wevu 检测到变化
3. 把当前状态做一次快照
4. 和上一次快照做 diff
5. 只把变化的部分传给小程序的 `setData`

你不需要手动调 `setData`，这是 wevu 帮你做的。

### 常见的响应式陷阱

从 store 解构会丢失响应性：

```ts
const store = useCartStore()

// ❌ 解构后 count 不再是响应式的
const { count } = store

// ✅ 用 storeToRefs
const { count } = storeToRefs(store)
```

在 computed 外面取值会断掉依赖追踪：

```ts
// ❌ 依赖追踪断了
const currentList = list.value
const total = computed(() => {
  return currentList.reduce((sum, item) => sum + item.price, 0)
})

// ✅ 在 computed 内部访问
const total = computed(() => {
  return list.value.reduce((sum, item) => sum + item.price, 0)
})
```

## 生命周期的完整图景

### 页面 hooks

| hook                          | 什么时候触发           | 适合做什么             |
| ----------------------------- | ---------------------- | ---------------------- |
| `onLoad(query)`               | 页面首次加载（只一次） | 读路由参数、发首次请求 |
| `onShow()`                    | 每次页面可见           | 刷新数据、恢复定时器   |
| `onReady()`                   | 首次渲染完成           | DOM 查询               |
| `onHide()`                    | 页面隐藏               | 暂停定时器             |
| `onUnload()`                  | 页面销毁               | 清理资源               |
| `onPullDownRefresh()`         | 下拉刷新               | 重新加载数据           |
| `onReachBottom()`             | 滚动到底部             | 加载下一页             |
| `onPageScroll({ scrollTop })` | 页面滚动               | 吸顶效果等             |
| `onShareAppMessage()`         | 用户点分享             | 返回分享配置           |
| `onShareTimeline()`           | 分享到朋友圈           | 返回分享配置           |
| `onTabItemTap()`              | 点击 tab               | tab 切换逻辑           |

### 组件 hooks

| hook           | 对应页面的      |
| -------------- | --------------- |
| `onAttached()` | 类似 `onLoad`   |
| `onReady()`    | 同名            |
| `onDetached()` | 类似 `onUnload` |

组件没有 `onShow` / `onHide`。

### App hooks

```ts
import { onLaunch, onShow } from 'wevu'

onLaunch((options) => {
  // 小程序启动
})

onShow((options) => {
  // 小程序从后台切回前台
})
```

还有 `onHide`、`onError`、`onPageNotFound`、`onUnhandledRejection`、`onThemeChange`、`onMemoryWarning`。

### hooks 必须同步注册

这个规则前面说过，但值得再强调：所有 hooks 都要在 setup 的顶层同步注册。回调里面可以是异步的，但注册本身不能在 `await` 后面。

```ts
// ✅
onLoad(async (query) => {
  const data = await fetchData(query.id)
})

// ❌
await someWork()
onLoad(() => {}) // 可能失效
```

## 一个完整的页面示例

```vue
<script setup lang="ts">
import { onHide, onLoad, onReachBottom, onShareAppMessage, onShow, ref, useAsyncPullDownRefresh } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '商品列表',
  enablePullDownRefresh: true,
}))

const list = ref<GoodsItem[]>([])
const page = ref(1)
const loading = ref(false)
const hasMore = ref(true)
let pollTimer: ReturnType<typeof setInterval> | null = null

async function loadList(pageNum: number) {
  loading.value = true
  try {
    const result = await getGoodsList({ page: pageNum })
    list.value = pageNum === 1 ? result.items : [...list.value, ...result.items]
    hasMore.value = result.hasMore
    page.value = pageNum
  }
  finally {
    loading.value = false
  }
}

onLoad(() => loadList(1))

onShow(() => {
  // 每次回到页面可以选择性刷新
  pollTimer = setInterval(() => {
    /* 轮询逻辑 */
  }, 10000)
})

onHide(() => {
  if (pollTimer) {
    clearInterval(pollTimer)
    pollTimer = null
  }
})

useAsyncPullDownRefresh(() => loadList(1))

onReachBottom(() => {
  if (!loading.value && hasMore.value) {
    loadList(page.value + 1)
  }
})

onShareAppMessage(() => ({
  title: '好物推荐',
  path: '/pages/goods-list/index',
}))
</script>
```

## 小程序宿主组合式 API

wevu 还提供了一组面向小程序宿主能力的组合式 API，用来替代项目里常见的零散 `wx.*` 胶水代码。

| 场景             | 推荐 API                                                  | 说明                                 |
| ---------------- | --------------------------------------------------------- | ------------------------------------ |
| 异步下拉刷新     | `useAsyncPullDownRefresh()`                               | 自动在刷新结束后停止下拉刷新状态     |
| 节点尺寸查询     | `useBoundingClientRect()` / `useSelectorFields()`         | 自动绑定当前页面/组件实例            |
| 滚动位置查询     | `useScrollOffset()`                                       | 返回 Promise，适合业务逻辑里按需读取 |
| 元素曝光/懒加载  | `useElementIntersectionObserver()`                        | selector 或 enabled 变化时自动重连   |
| 页面栈状态       | `usePageStack()` / `getCurrentPageStackSnapshot()`        | 适合自定义返回按钮                   |
| 自定义导航栏高度 | `useNavigationBarMetrics()` / `getNavigationBarMetrics()` | 自动读取状态栏和胶囊按钮尺寸         |

示例：

```vue
<script setup lang="ts">
import {
  ref,
  useAsyncPullDownRefresh,
  useElementIntersectionObserver,
  useNavigationBarMetrics,
  usePageStack,
} from 'wevu'

const visible = ref(false)
const { canGoBack } = usePageStack()
const { navigationHeight } = useNavigationBarMetrics()

useElementIntersectionObserver({
  selector: '#banner',
  onObserve(result: any) {
    visible.value = Number(result?.intersectionRatio ?? 0) > 0
  },
})

useAsyncPullDownRefresh(async () => {
  await reload()
})
</script>
```

## 接下来

* [组件通信](/handbook/wevu/component) — props、emit、slots 在小程序里怎么用
* [状态管理](/handbook/wevu/store) — 什么时候该上 store

---

---
url: /handbook/wevu/component.md
description: 在 wevu 里怎么做 props、emit 和 slots，以及和 Web Vue 的区别。
---

# 组件通信

组件通信就三件事：父给子数据、子给父事件、插槽。在小程序里都能做，但要用"宿主视角"来理解。

## props：父组件给子组件数据

用 `<script setup>` 的话：

```vue
<!-- goods-card.vue -->
<script setup lang="ts">
const props = defineProps<{
  title: string
  price: number
}>()
</script>

<template>
  <view class="goods-card">
    <text>{{ props.title }}</text>
    <text>¥{{ props.price }}</text>
  </view>
</template>
```

用 `defineComponent` 的话，通过 `properties`：

```ts
export default defineComponent({
  properties: {
    title: { type: String, value: '' },
    price: { type: Number, value: 0 },
  },
  setup(props) {
    // props.title, props.price 是响应式的
  },
})
```

父组件使用：

```vue
<GoodsCard title="键盘" :price="199" />
```

## emit：子组件给父组件事件

```vue
<!-- 子组件 -->
<script setup lang="ts">
const emit = defineEmits<{
  select: [{ id: string }]
}>()

function onTap() {
  emit('select', { id: 'sku-1' })
}
</script>

<template>
  <view @tap="onTap">
    点击选择
  </view>
</template>
```

```vue
<!-- 父组件 -->
<GoodsCard @select="onGoodsSelect" />
```

用 `defineComponent` 的话，通过 `ctx.emit`：

```ts
export default defineComponent({
  setup(props, ctx) {
    function onTap() {
      ctx.emit('select', { id: 'sku-1' })
    }
    return { onTap }
  },
})
```

底层走的是小程序的 `triggerEvent`。

## slots：插槽

默认插槽可以正常用：

```vue
<BaseCard>
  <view>这里是插槽内容</view>
</BaseCard>
```

但不要默认以为 Web Vue 里复杂的作用域插槽都能照搬。小程序的组件隔离机制和浏览器不一样，复杂插槽模式要实际验证。

## 组件设计的建议

组件对外只暴露两类东西：

* 输入：props
* 输出：事件

不要让外部依赖组件的内部实现细节。props 定义清晰、事件语义明确，组件就好维护。

## 接下来

* [状态管理](/handbook/wevu/store)
* [表单和双向绑定](/handbook/wevu/bind-model)

---

---
url: /handbook/wevu/store.md
description: 什么时候该上 store、什么时候页面本地状态就够了、store 怎么组织。
---

# 状态管理

新手最容易在两个极端之间摇摆：什么都放页面本地 state，或者什么都塞进全局 store。

更合理的做法是先问一个问题：这份状态服务谁？

## 什么时候用页面本地状态

只服务当前页面的状态，放页面里就好：

* 当前弹窗是否打开
* 当前输入框内容
* 当前页的 loading

## 什么时候上 store

跨页面共享的状态才需要 store：

* 用户登录态
* 购物车
* 当前门店信息
* 全局主题

## 怎么写一个 store

wevu 的 store 用法和 Pinia 很像。推荐 setup 风格：

```ts
// stores/user.ts
import { defineStore, ref } from 'wevu'

export const useUserStore = defineStore('user', () => {
  const token = ref<string | null>(null)
  const profile = ref<UserProfile | null>(null)

  function setToken(value: string | null) {
    token.value = value
  }

  function clearUser() {
    token.value = null
    profile.value = null
  }

  return { token, profile, setToken, clearUser }
})
```

页面里用：

```vue
<script setup lang="ts">
import { useUserStore } from '../../stores/user'

const userStore = useUserStore()
</script>

<template>
  <text>{{ userStore.profile?.nickname || '游客' }}</text>
</template>
```

## 按业务域拆 store

不要做一个超级大 store。按业务域拆：

```txt
stores/
├─ user.ts
├─ cart.ts
├─ order.ts
└─ location.ts
```

## store 和 service 的边界

一个清晰的分工：

* `service` — 负责请求和平台交互
* `store` — 负责状态组织和业务编排
* `page` — 负责展示和触发动作

```ts
// services/order.ts — 只管请求
export function getOrderList() {
  return request({ url: '/api/orders' })
}

// stores/order.ts — 管状态
export const useOrderStore = defineStore('order', () => {
  const list = ref([])
  async function fetchList() {
    list.value = await getOrderList()
  }
  return { list, fetchList }
})
```

```vue
<!-- 页面只管展示和触发 -->
<script setup lang="ts">
const orderStore = useOrderStore()
</script>
```

## storeToRefs

从 store 解构状态的时候，直接解构会丢失响应性。用 `storeToRefs`：

```ts
import { storeToRefs } from 'wevu'

const store = useCartStore()
const { count, totalPrice } = storeToRefs(store)
// count 和 totalPrice 仍然是响应式的
```

方法不需要 `storeToRefs`，直接解构就行：

```ts
const { addItem, removeItem } = store
```

## store 还提供什么

每个 store 实例还有这些方法：

* `$patch(patch)` — 批量更新状态
* `$reset()` — 重置到初始状态
* `$subscribe(callback)` — 监听状态变化
* `$onAction(callback)` — 监听 action 调用

日常开发里 `$patch` 和 `$subscribe` 用得比较多。

## 不要过早引入 store

如果项目还小，不要为了"看起来先进"就把每个页面都硬塞进 store。先问自己：

* 这个状态真的跨页面吗？
* 未来会被多处消费吗？
* 值得被长期缓存吗？

都不是的话，页面本地状态更简单。

## 接下来

* [表单和双向绑定](/handbook/wevu/bind-model)
* [页面跳转](/handbook/navigation)

---

---
url: /handbook/wevu/bind-model.md
description: v-model 的边界、什么时候该用显式写法、bindModel 解决什么问题。
---

# 表单和双向绑定

表单是最容易"看起来能写、实际最容易踩坑"的场景。因为你会同时撞上输入事件差异、`v-model` 边界和校验逻辑。

## 简单场景：直接用 v-model

两三个输入框的简单表单，`v-model` 就够了：

```vue
<input v-model="form.name" placeholder="姓名">

<input v-model="form.phone" placeholder="手机号">
```

## v-model 的限制

`v-model` 后面必须是可赋值的左值：

```vue
<!-- ✅ -->
<input v-model="form.name" />

<input v-model="list[index].title" />

<!-- ❌ -->
<input v-model="a + b" />

<input v-model="user?.name" />
```

而且 `v-model` 默认绑定的是 `input` 事件和 `detail.value`。如果组件的事件名或取值方式不一样，`v-model` 就不好使了。

## 什么时候改用显式写法

遇到这些情况，就别硬用 `v-model`：

* 事件名不是 `input`（比如 `change`）
* 值不在 `detail.value`（比如 `detail.files`）
* 需要做类型转换（比如字符串转数字）
* 组件是第三方的，事件协议不确定

显式写法：

```vue
<slider :value="budget" @change="onBudgetChange" />
```

```ts
function onBudgetChange(event: any) {
  budget.value = Number(event.detail.value)
}
```

## 自定义组件支持 v-model

如果你想让自己的组件支持 `v-model`，组件需要做两件事：接收值、通过事件抛出新值。

```vue
<!-- MyInput.vue -->
<script setup lang="ts">
const props = defineProps<{ value: string }>()
const emit = defineEmits<{ input: [value: string] }>()

function onInput(event: any) {
  emit('input', event.detail.value)
}
</script>

<template>
  <input :value="props.value" @input="onInput">
</template>
```

父组件就可以：

```vue
<MyInput v-model="name" />
```

## 表单校验怎么组织

推荐把表单值、错误状态、校验逻辑分开放：

```ts
const form = ref({ name: '', phone: '' })
const errors = ref<Record<string, string>>({})

function validate(): boolean {
  const e: Record<string, string> = {}
  if (!form.value.name.trim()) {
    e.name = '请输入姓名'
  }
  if (!/^1\d{10}$/.test(form.value.phone)) {
    e.phone = '请输入正确手机号'
  }
  errors.value = e
  return Object.keys(e).length === 0
}
```

模板只负责展示错误：

```vue
<input v-model="form.name" placeholder="姓名">

<text v-if="errors.name" class="error">
{{ errors.name }}
</text>
```

输入中校验（长度、格式提示）和提交前校验（完整检查）建议分开做。

## bindModel：表单字段多了以后怎么收口

如果页面有很多表单字段，而且不同组件的事件名和取值方式都不一样，每个字段都写一个事件处理函数会很烦。

wevu 提供了 `useBindModel` 来统一处理：

```ts
import { useBindModel } from 'wevu'

const bindModel = useBindModel()

const onNameChange = bindModel<string>('form.name').model({ event: 'change' }).onChange
const onBudgetChange = bindModel<number>('form.budget').model({ event: 'change' }).onChange
```

模板里就统一了：

```vue
<t-input :value="form.name" @change="onNameChange" />

<t-slider :value="form.budget" @change="onBudgetChange" />
```

更复杂的场景，比如上传组件的值在 `detail.files`：

```ts
const onAttachmentsChange = bindModel<UploadFile[]>('form.attachments').model({
  event: 'change',
  valueProp: 'files',
  parser: event => event?.detail?.files ?? [],
}).onChange
```

`bindModel` 支持自定义事件名、值字段、parser 和 formatter。适合后台配置页、多字段业务表单、大量使用第三方组件库的页面。

如果表单只有两三个简单字段，直接 `v-model` 更直观，不需要上 `bindModel`。

## useChangeModel：第三方组件库的 change 事件快捷写法

很多小程序组件库默认用 `change` 事件更新表单项。此时可以用 `useChangeModel()` 少写一层默认配置：

```vue
<script setup lang="ts">
import { reactive, useChangeModel } from 'wevu'

const form = reactive({
  name: '',
  budget: 0,
})

const changeModel = useChangeModel()
const nameModel = changeModel<string>('form.name')
const budgetModel = changeModel<number>('form.budget', {
  parser: event => Number(event?.detail?.value ?? 0),
})
</script>

<template>
  <t-input v-bind="nameModel" />
  <t-slider v-bind="budgetModel" />
</template>
```

它等价于：

```ts
const bindModel = useBindModel({ event: 'change' })
const nameModel = bindModel.model<string>('form.name')
```

## 接下来

写页面和理解运行时的基本功到这里差不多了。接下来开始做业务：

* [页面跳转](/handbook/navigation)
* [网络请求](/handbook/network)

---

---
url: /handbook/navigation.md
description: 用真实业务页面常见场景解释小程序导航 API、参数传递和页面栈管理，帮助新用户少走路由坑。
---

# 页面跳转与路由参数

小程序里的导航，看上去像一组 API，实际背后有 3 件事要同时考虑：

* 跳转到哪里
* 参数怎么带过去
* 页面栈会不会因此失控

## 先记住 5 个最常用 API

### `wx.navigateTo`

打开一个新的非 tab 页面。

```ts
wx.navigateTo({
  url: '/pages/order-detail/index?id=1001',
})
```

### `wx.redirectTo`

替换当前页，适合“我不希望用户再回到上一页”的场景。

```ts
wx.redirectTo({
  url: '/pages/login/index',
})
```

### `wx.switchTab`

切到 tabBar 页面。

```ts
wx.switchTab({
  url: '/pages/home/index',
})
```

### `wx.reLaunch`

清空当前页面栈，重新进入指定页。

```ts
wx.reLaunch({
  url: '/pages/home/index',
})
```

### `wx.navigateBack`

返回上一页或上几页。

```ts
wx.navigateBack({
  delta: 1,
})
```

## 一个最常见的业务场景

例如从订单列表进入订单详情：

```ts
function openOrderDetail(id: string) {
  wx.navigateTo({
    url: `/pages/order-detail/index?id=${encodeURIComponent(id)}`,
  })
}
```

详情页里读取参数：

```ts
import { onLoad } from 'wevu'

onLoad((query) => {
  const id = query.id
  console.log('current order id:', id)
})
```

这就是新项目里最常见、也最值得先掌握的路线。

## 参数怎么传最稳

### 简单参数：用 query

适合：

* `id`
* `tab`
* `source`

例如：

```ts
wx.navigateTo({
  url: '/pages/goods/index?id=sku-1&source=home',
})
```

### 大对象：不要直接塞 URL

不推荐这样：

```ts
wx.navigateTo({
  url: `/pages/confirm/index?payload=${encodeURIComponent(JSON.stringify(data))}`,
})
```

更稳的做法通常是：

* 只传主键或关键标识
* 页面二次拉取详情
* 或暂存到 store/cache 再在目标页读取

## 页面栈什么时候会出问题

### 场景 1：登录回跳

比如用户在下单前未登录：

```ts
if (!hasLogin()) {
  wx.navigateTo({
    url: '/pages/login/index?redirect=/pages/checkout/index',
  })
}
```

登录成功后，你通常要根据业务选择：

* 回上一页：`navigateBack`
* 替换为目标页：`redirectTo`
* 重建首页链路：`reLaunch`

### 场景 2：tab 页面跳转

tab 页不能用 `navigateTo` 打开。
这类问题是新用户最容易踩的坑之一。

错误心智：

```ts
wx.navigateTo({
  url: '/pages/home/index',
})
```

正确心智：

```ts
wx.switchTab({
  url: '/pages/home/index',
})
```

## 推荐封装一个轻量导航层

当项目页面多起来后，建议封装一层简单导航函数，不要让页面里散落大量字符串路径。

```ts
export function toOrderDetail(id: string) {
  return wx.navigateTo({
    url: `/pages/order-detail/index?id=${encodeURIComponent(id)}`,
  })
}

export function toHomeTab() {
  return wx.switchTab({
    url: '/pages/home/index',
  })
}
```

这样做的好处是：

* 页面路径统一管理
* 重构时更安全
* query 规则更统一

## 一份很实用的导航检查清单

```txt
[ ] tab 页面只用 switchTab
[ ] 详情页只传必要参数
[ ] 登录拦截后的回跳策略明确
[ ] 页面栈深度不会无限增长
[ ] 页面路径使用统一封装或常量
```

接下来最适合继续看的，是：

* [网络请求与数据层](/handbook/network)
* [原生能力调用与封装](/handbook/native-apis)

---

---
url: /handbook/network.md
description: 从真实业务页面出发，解释请求封装、领域 service、store 和页面编排之间的边界，让新用户知道请求代码应该放在哪里。
---

# 网络请求与数据层

如果你把请求直接写在页面里，项目通常能跑一阵子；
但一旦业务变复杂，代码会很快出现这些问题：

* 页面里全是接口细节
* 登录态刷新逻辑到处复制
* loading、错误提示、缓存状态混在一起

更稳的思路是把网络层拆成 3 层：

1. `request` 基础封装
2. `services` 领域接口
3. `stores` 或页面组合逻辑

## 推荐的最小结构

```txt
src/
├─ services/
│  ├─ request.ts
│  ├─ user.ts
│  └─ order.ts
└─ stores/
   └─ order.ts
```

## 第 1 层：基础请求封装

基础请求层只做通用事情：

* baseURL
* 超时
* header
* 错误转换
* 登录态注入

例如：

```ts
// services/request.ts
export async function request<T>(options: WechatMiniprogram.RequestOption) {
  const token = wx.getStorageSync('token')

  return new Promise<T>((resolve, reject) => {
    wx.request({
      timeout: 10000,
      ...options,
      header: {
        Authorization: token ? `Bearer ${token}` : '',
        ...options.header,
      },
      success(res) {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve(res.data as T)
          return
        }
        reject(res)
      },
      fail(err) {
        reject(err)
      },
    })
  })
}
```

## 第 2 层：按业务域拆 service

service 不负责页面 loading，也不负责页面跳转。
它只负责表达“我要请求哪个业务接口”。

```ts
// services/order.ts
import { request } from './request'

export function getOrderList() {
  return request<OrderListItem[]>({
    url: '/api/orders',
    method: 'GET',
  })
}

export function getOrderDetail(id: string) {
  return request<OrderDetail>({
    url: `/api/orders/${id}`,
    method: 'GET',
  })
}
```

## 第 3 层：store 或页面组合逻辑

页面真正关心的是：

* 当前列表数据
* 是否 loading
* 是否需要下拉刷新
* 出错后怎么展示

这些更适合放在 store 或 composable 里：

```ts
import { ref } from 'wevu'
import { getOrderList } from '../services/order'

export function useOrderListStore() {
  const list = ref<OrderListItem[]>([])
  const loading = ref(false)
  const errorMessage = ref('')

  async function fetchList() {
    loading.value = true
    errorMessage.value = ''

    try {
      list.value = await getOrderList()
    }
    catch (error) {
      errorMessage.value = '订单列表加载失败'
    }
    finally {
      loading.value = false
    }
  }

  return {
    list,
    loading,
    errorMessage,
    fetchList,
  }
}
```

## 页面里应该剩下什么

页面最好只做“编排”，而不是自己处理所有接口细节。

```vue
<script setup lang="ts">
import { onLoad } from 'wevu'
import { useOrderListStore } from '../../stores/order'

const { list, loading, fetchList } = useOrderListStore()

onLoad(fetchList)
</script>
```

这样页面职责就很明确：

* 负责什么时候触发加载
* 负责把状态渲染出来
* 不负责底层请求细节

## 登录态刷新要不要一开始就做

不一定要第一天就做完整，但架构上最好留出位置。

最起码你要提前想清楚：

* 哪个错误码表示 token 失效
* 刷新失败后要跳去哪里
* 并发请求期间如何避免重复刷新

如果业务已经有登录态，那么建议尽早统一请求入口。不要让不同页面各自带 token。

## 上传和下载属于同一层吗

属于“网络与数据通道”的一部分，但通常会单独封装。

例如：

```ts
export function uploadAvatar(filePath: string) {
  return wx.uploadFile({
    url: '/api/upload/avatar',
    filePath,
    name: 'file',
  })
}
```

这类接口尤其要提前考虑：

* 失败重试
* 进度反馈
* 临时文件清理

## 一个足够稳的最小原则

如果你现在还不确定项目规模，可以先只做到这三条：

* 页面不直接写 `wx.request`
* 所有接口请求统一走 `services/request.ts`
* 页面数据状态通过 store 或 composable 管理

然后再继续看：

* [原生能力调用与封装](/handbook/native-apis)
* [分包与包体策略](/handbook/subpackages)

---

---
url: /handbook/native-apis.md
description: 解释 wx.* 能力在真实项目里应该如何按模块封装、做能力探测、处理授权和失败降级，避免业务页面直接耦合平台细节。
---

# 原生能力调用与封装

小程序业务一旦进入真实阶段，迟早会接触这些能力：

* 登录
* 存储
* 定位
* 图片选择与上传
* 分享
* 文件下载

这时最容易出现的问题是：页面里直接到处写 `wx.*`。

短期看很快，长期会带来这些后果：

* 页面逻辑和平台细节耦合
* 测试和 mock 困难
* 权限、失败、降级行为不统一

## 一个更稳的思路：按能力模块封装

你可以按平台能力来拆模块：

```txt
src/services/native/
├─ auth.ts
├─ storage.ts
├─ location.ts
├─ media.ts
└─ share.ts
```

例如封装本地存储：

```ts
// services/native/storage.ts
export function getToken() {
  return wx.getStorageSync('token')
}

export function setToken(token: string) {
  wx.setStorageSync('token', token)
}

export function clearToken() {
  wx.removeStorageSync('token')
}
```

## 一个真实点的例子：定位能力

直接在页面里这样写并不理想：

```ts
wx.getLocation({
  type: 'gcj02',
  success(res) {
    console.log(res)
  },
})
```

更推荐封成一个服务：

```ts
// services/native/location.ts
export async function getCurrentLocation() {
  return new Promise<WechatMiniprogram.GetLocationSuccessCallbackResult>((resolve, reject) => {
    wx.getLocation({
      type: 'gcj02',
      success: resolve,
      fail: reject,
    })
  })
}
```

页面只关心业务结果：

```ts
import { getCurrentLocation } from '../../services/native/location'

async function locateStore() {
  try {
    const location = await getCurrentLocation()
    console.log(location.latitude, location.longitude)
  }
  catch {
    wx.showToast({
      title: '定位失败',
      icon: 'none',
    })
  }
}
```

## 你应该统一处理的 3 件事

### 1. 能力探测

不是所有宿主、所有基础库、所有平台都支持同一组 API。

所以在高风险能力上，建议先做探测：

```ts
export function canUseChooseLocation() {
  return typeof wx.chooseLocation === 'function'
}
```

### 2. 授权失败

不要把“用户拒绝授权”的处理散落在每个页面里。

更稳的做法是统一处理：

* 弹提示
* 引导去设置
* 记录失败场景

### 3. 错误转换

页面最好看到的是“业务语义错误”，而不是平台底层错误细节。

例如：

```ts
export class LocationDeniedError extends Error {}
export class LocationUnavailableError extends Error {}
```

然后在 service 内部做转换。

## 登录能力尤其值得提前封装

登录不是一个 API，而是一条流程。

建议至少拆出：

* `login()`
* `logout()`
* `getToken()`
* `refreshToken()`
* `ensureLogin()`

这样后面做请求拦截、未登录跳转、token 失效刷新时，复杂度会低很多。

## 页面里到底该保留多少平台细节

推荐原则是：

* 页面可以知道“我要调用定位 / 选择图片 / 分享”
* 页面不要关心“平台底层参数细节、错误码细节、重试细节”

一句话：

> 页面描述业务意图，service 负责和平台 API 说话。

## 一份很实用的原生能力检查清单

```txt
[ ] 高风险能力有统一 service
[ ] 授权拒绝有统一提示与降级
[ ] 低兼容 API 先做能力探测
[ ] 错误码不会直接泄漏到页面层
[ ] 上传/下载/文件类能力有清理策略
```

接下来你可以继续看：

* [分包与包体策略](/handbook/subpackages)
* [调试与排错（按层定位）](/handbook/debugging)

---

---
url: /handbook/subpackages.md
description: 从真实业务模块拆分视角解释主包、分包、共享资源和加载体验，帮助新用户建立小程序包体优化的第一套规则。
---

# 分包与包体策略

分包不是“项目很大以后再做”的事情。
对于大多数小程序项目，它通常都会比你想象中更早出现。

## 为什么分包几乎是必修课

因为你很快就会同时遇到这几类压力：

* 首屏包体不能无限增长
* 某些业务只在低频场景出现
* 页面和组件并不是都应该跟着首页一起下载

例如一个常见商城项目：

```txt
主包：
- 首页
- 搜索
- 商品详情
- 登录态判断

订单分包：
- 订单列表
- 订单详情
- 售后页

营销分包：
- 优惠券
- 活动会场
- 积分商城
```

## 一条对新用户最实用的原则

把“用户一打开 App 最可能立刻访问的页面”留在主包。
把“进入后续流程才会访问的业务模块”逐步拆到分包。

## 一个简单的拆分例子

假设你现在有这些页面：

```txt
pages/
├─ home/index
├─ search/index
├─ goods-detail/index
├─ order-list/index
├─ order-detail/index
└─ after-sale/index
```

推荐先这样想：

* `home/search/goods-detail` 留主包
* `order-list/order-detail/after-sale` 考虑归到订单分包

## 分包不只是路由问题

真正做分包时，你还要同时考虑：

* 页面路径放在哪
* 页面依赖的组件放在哪
* 页面依赖的图片和静态资源放在哪
* 主包和分包之间有没有不合理引用

例如一个很典型的坏味道是：

* 订单分包页面依赖一个只能在主包里的大组件
* 或者订单分包页面引用了主包私有资源路径

这样很容易在构建和运行时都出现问题。

## 一个更稳的组织方式

```txt
src/
├─ pages/
│  ├─ home/
│  └─ goods-detail/
├─ subpackages/
│  └─ order/
│     ├─ list/
│     ├─ detail/
│     └─ after-sale/
├─ components/
│  ├─ shared/
│  └─ home/
└─ assets/
```

你要尽量做到：

* 主包页面依赖主包组件或共享组件
* 分包页面优先依赖分包内部组件或真正的共享组件
* 资源尽量跟着实际使用场景走

## 怎么判断“现在该不该开始分包”

下面这些信号一出现，就值得开始规划：

* 首屏加载明显变慢
* 某些业务页根本不属于用户首次访问路径
* 构建后包体越来越大
* 团队开始因为“放哪一页”争论不清

## 新用户最容易踩的 4 个坑

### 1. 把主包当成无限容量

结果首页不断变重，最后什么都想塞进去。

### 2. 分包只拆页面，不拆依赖

页面路径拆出去了，但组件和资源依赖还在主包，实际收益很有限。

### 3. 共享组件没有真正共享边界

看起来是“共享”，实际上里面偷偷依赖某个主包页面环境。

### 4. 只看构建成功，不看真实加载体验

分包是否做对，最终还是要在开发者工具和真机里验证加载路径与体验。

## 一份足够实用的分包检查清单

```txt
[ ] 主包只保留首屏高频页面
[ ] 分包按业务域拆，不按“随便找个目录”拆
[ ] 分包页面依赖的组件和资源布局清晰
[ ] 共享组件不偷偷依赖特定包环境
[ ] 构建成功后做过真实页面跳转验证
```

你接下来最适合继续看：

* [性能与体验优化](/handbook/performance)
* [构建、预览与上传](/handbook/publish)

---

---
url: /handbook/performance.md
description: 按小程序项目的真实瓶颈来解释包体、渲染、setData、列表和资源优化，让新用户知道应该先优化什么、后优化什么。
---

# 性能与体验优化

性能优化最怕两件事：

* 一上来就做复杂优化，但没抓到主要瓶颈
* 页面明显卡顿了，却不知道该从包体、渲染还是数据更新下手

这章只讲最值得优先做的内容。

## 优先级最高的 4 个方向

### 1. 先控制首屏包体

如果首屏就很重，后面很多体验问题都会被放大。

优先看：

* 是否应该分包
* 是否引入了过重依赖
* 图片和静态资源是否过大

### 2. 再控制列表渲染压力

很多页面卡顿，本质不是“框架慢”，而是：

* 一次渲染的数据太多
* 模板表达式太重
* 每次更新都替换整个大数组

### 3. 再关注状态更新粒度

在 `wevu` 语境里，这一点尤其重要。
如果你的状态设计足够清晰，更新路径就更容易收敛。

### 4. 最后才是细节微调

例如：

* 动画节奏
* 节流防抖
* 占位骨架屏

## 一个典型的大列表例子

不太推荐的写法：

```ts
list.value = response.bigList
```

如果 `bigList` 很大，而且更新频繁，页面很容易有压力。

更稳的思路通常是：

```ts
list.value = [...list.value, ...nextPage]
```

并配合：

* 分页加载
* 下拉刷新重置
* 滚动到底部再加载更多

## 模板里尽量不要做复杂计算

比如这种写法，要慎用：

```vue
<text>
{{ goods.price * goods.count * discountMap[goods.type] }}
</text>
```

更推荐把复杂计算提前到脚本层：

```ts
function getItemTotal(item: CartItem) {
  return item.price * item.count * discountMap[item.type]
}
```

模板只负责展示：

```vue
<text>
{{ getItemTotal(goods) }}
</text>
```

## `wevu` 里一条很重要的性能建议

把状态按“变化频率”和“消费范围”拆开。

例如：

```ts
const summary = ref({
  totalPrice: 0,
  totalCount: 0,
})

const list = ref<CartItem[]>([])
const loading = ref(false)
```

这种拆分通常会比把所有页面状态都塞进一个超级对象里更稳。

## 包体优化的最小动作

如果你刚开始做优化，优先做这些：

* 把低频业务页分包
* 检查大图和重复资源
* 避免为了一个小功能引入很重的依赖
* 尽量复用已有能力，不要叠加重复 SDK

## 体验优化不要只盯性能指标

用户真正感受到的“快”，很多时候来自这些设计：

* 加载时有明确反馈
* 首屏先展示骨架和核心信息
* 下拉刷新和分页行为稳定
* 错误提示可恢复

## 一份很实用的性能检查清单

```txt
[ ] 首屏业务已经做主包/分包区分
[ ] 大列表使用分页或渐进加载
[ ] 模板里没有明显复杂表达式
[ ] 大状态没有每次整块替换
[ ] 图片和静态资源做过体积检查
```

优化完性能以后，建议你继续看：

* [调试与排错（按层定位）](/handbook/debugging)
* [构建、预览与上传](/handbook/publish)

---

---
url: /handbook/debugging.md
description: 用“先分层、再缩小、最后验证”的方式整理 Weapp-vite、SFC 编译链、Wevu 运行时和宿主侧常见问题的排查顺序。
---

# 调试与排错（按层定位）

复杂问题最怕一上来就乱猜。
更高效的方式是先判断：问题到底出现在哪一层。

在 `weapp-vite + Vue SFC + Wevu` 体系里，你可以先把问题拆成 4 层：

1. 小程序宿主层
2. 构建与产物层
3. SFC 编译层
4. Wevu 运行时层

## 第 0 步：先给现象分类

你先不要着急改代码，先判断它属于哪一类：

* 页面白屏
* 组件不显示
* 数据变了但页面不更新
* 样式错乱
* 开发环境正常，构建后异常

只要这一步分清了，后面排查速度会快很多。

## 第 1 层：先看宿主和开发者工具

优先检查：

* 控制台错误
* Network 面板
* 当前页面路由
* 授权与缓存状态

很多“框架问题”，最后其实是：

* 页面路径写错
* 域名没配白名单
* 本地缓存脏了
* 组件路径声明不对

## 第 2 层：再看构建产物

如果问题和页面输出有关，直接看 `dist` 是最快的。

重点看：

* 页面 `json`
* 页面 `wxml`
* 页面 `js`
* 最终 `app.json`

例如“页面标题没生效”，就先看最终产物：

```txt
dist/pages/order-detail/index.json
```

而不是只盯着源码。

## 第 3 层：SFC 编译问题怎么查

如果你怀疑问题在 `.vue` 编译链上，优先排查这些：

* 模板语法是否符合小程序边界
* `usingComponents` 是否正确生成
* 页面 JSON 是否合并正确
* 事件和 `v-model` 写法是否合理

一个典型例子是：页面能出来，但组件不渲染。

这时优先看：

* 是否真的导入了组件
* 最终 `json` 里有没有对应组件声明
* 组件路径是否正确

## 第 4 层：Wevu 运行时问题怎么查

如果现象是“状态改了但页面不更新”，先问自己两个问题：

### 1. 响应式 API 是不是从 `wevu` 导入的

```ts
import { ref } from 'wevu'
```

### 2. hooks 是不是在同步 setup 阶段注册的

```ts
onLoad(() => {
  // ...
})
```

如果 hook 注册时机不对，行为就可能和预期不一致。

## 一个很实用的最小复现思路

无论问题多复杂，都建议尝试压缩成下面这种最小页：

```vue
<script setup lang="ts">
import { ref } from 'wevu'

const count = ref(0)
</script>

<template>
  <view>
    <text>{{ count }}</text>
    <button @tap="count += 1">
      add
    </button>
  </view>
</template>
```

如果最小页没问题，就说明问题通常不在基础链路，而在：

* 业务逻辑
* 组件组合
* 请求时序
* 状态组织

## 一个排错顺序模板

你可以直接套用：

```txt
1. 先复现问题
2. 记录出现问题的页面和路径
3. 看控制台/网络/开发者工具
4. 看 dist 产物
5. 去掉业务依赖，缩成最小复现
6. 再判断是构建层、编译层还是运行时层
```

## 最常见的误判

### 误判 1：白屏一定是运行时问题

很多时候只是路由或页面产物没有生成。

### 误判 2：按钮没反应一定是事件系统坏了

更常见的是模板没渲染、方法名拼错或宿主报错中断。

### 误判 3：数据不更新就是 Wevu 的问题

也可能是：

* 不是从 `wevu` 导入
* 页面根本没消费这个状态
* 你看的是旧缓存页面

## 一句话总结

排错时不要问“哪个框架有 bug”，而要先问：

> 这个问题更像是宿主问题、产物问题、编译问题，还是运行时问题？

接下来你可以继续看：

* [构建、预览与上传](/handbook/publish)
* [参考入口与速查索引](/handbook/reference)

---

---
url: /handbook/publish.md
description: 把从本地构建到开发者工具预览、真机验证和上传发布的流程串成一条新用户可执行的上线前检查路线。
---

# 构建、预览与上传

很多项目在“能开发”之后，第一次真正上线时才发现流程并不完整。

例如：

* 本地 dev 正常，但 build 产物不完整
* 开发者工具导入的不是正确目录
* 真机和开发者工具表现不一致

所以发布流程最好不要临时拼，而要尽早固化。

## 一条最小可执行的发布流程

你可以先把项目流程固定成下面这样：

```txt
1. 本地构建
2. 开发者工具打开 dist
3. 关键页面回归
4. 真机预览
5. 上传版本
```

## 第 1 步：先构建

```bash
pnpm build
```

构建完成后，不要只看“命令通过了没有”，还要看：

* `dist` 是否完整
* 关键页面是否都生成了
* 分包目录是否符合预期

## 第 2 步：确认开发者工具看的目录对

这是一个非常高频的坑。

你要确认开发者工具导入的是最终产物目录，而不是源码目录。
也就是说，`miniprogramRoot` 应该和当前项目输出目录对齐。

## 第 3 步：做一轮关键路径回归

新用户最容易跳过这一步，但它实际上非常重要。

至少建议手动走一遍：

* 首页打开
* 登录流程
* 列表页进入详情页
* 表单提交
* 关键分享或支付前流程

你不需要把所有边角场景都点一遍，但核心业务链路一定要确认。

## 第 4 步：真机预览

开发者工具通过，不代表真机一定通过。

真机更值得关注：

* 登录授权
* 图片和静态资源
* 网络请求域名
* 页面切换与分享
* 长列表和滚动体验

## 第 5 步：上传

如果你的团队已经接入命令行工具链，可以进一步把流程标准化。

例如，项目里经常会把这些动作写进脚本：

```bash
pnpm build
pnpm open
pnpm preview
pnpm upload
```

关键不是命令长什么样，而是团队知道：

* 谁负责构建
* 谁负责验证
* 哪个版本对应哪次上传

## 一个很实用的发布前检查清单

```txt
[ ] 当前分支代码已确认
[ ] pnpm build 通过
[ ] dist 关键页面产物完整
[ ] 开发者工具导入目录正确
[ ] 关键业务路径已回归
[ ] 真机至少验证一轮
[ ] 上传版本号和说明明确
```

## 什么时候适合接入命令行 IDE 流程

如果你的项目已经进入稳定迭代，可以考虑把：

* 打开 IDE
* 预览
* 上传

这些步骤逐步脚本化，这样更适合团队协作和 CI/CD。

## 一个给新用户的建议

先把“本地 build -> 开发者工具导入 -> 真机验证”这条最短链路跑通。
不要一开始就把所有发布自动化做得很重。

看完这一章后，你可以继续看：

* [从旧项目迁移过来](/handbook/migration)
* [参考入口与速查索引](/handbook/reference)

---

---
url: /handbook/migration.md
description: >-
  从原生小程序或旧工程结构迁移到 Weapp-vite + 原生，或继续迁移到 Weapp-vite + Wevu + Vue SFC
  时，推荐采用分阶段、可回滚的迁移路线。
---

# 从旧项目迁移过来

迁移最怕两种做法：

* 一次性全改，最后很难回滚
* 只改一半链路，结果新旧写法互相打架

更稳的思路是：**按阶段迁移，每一阶段都能独立验证。**

## 先决定迁移终点

迁移不一定等于“全量改成 Vue SFC”。常见有两种终点：

* `weapp-vite + 原生`：继续保留 `Page/Component + WXML/WXSS/JSON`，先获得 Vite 构建、TS、别名、资源处理、DevTools、截图日志和 AI 协作能力。
* `weapp-vite + Wevu + Vue SFC`：在前一条路线稳定后，继续把新页面或目标页面族迁到 `.vue`，使用响应式状态和更明确的组件契约。

如果当前项目里有很多复杂插件、`wxs/sjs`、云开发、地图、直播、支付或老旧 Behavior，优先把 `weapp-vite + 原生` 做稳，再挑低风险页面试点 SFC。

## 一条推荐的迁移路线

### 第 1 阶段：先接入 Weapp-vite

这一阶段尽量少碰业务逻辑，目标只是：

* 替换开发与构建体验
* 让项目能通过 Weapp-vite 正常产出 `dist`

这一步完成后，你就已经有了更好的工程化基础。
如果团队只想保留原生开发方式，这一步可以继续收口成明确的阶段性交付，不必强行进入 SFC 迁移。

### 第 2 阶段：整理目录和配置

把这些基础问题先梳理掉：

* 目录结构
* 依赖策略
* 环境变量
* 构建输出

### 第 3 阶段：选择是否试点 SFC

不要一开始就全站改 Vue SFC。
先挑一个低风险、结构清晰的页面。

例如：

* 个人中心首页
* 列表页
* 纯展示详情页

把它改成：

```txt
index.js + index.wxml + index.wxss + index.json
```

变成：

```txt
index.vue
```

并接入 `wevu` 响应式写法。

### 第 4 阶段：抽公共组件、service、store

当试点页稳定后，再开始把公共逻辑抽出来：

* 通用组件
* 请求层
* 状态层

### 第 5 阶段：逐模块推进

例如按业务域推进：

* 商品域
* 订单域
* 用户域

这样每一波迁移的边界都更清楚。

## 一个很实用的迁移判断标准

每次迁移只做一件更大的事：

* 只换构建
* 只换目录
* 只试点一个 SFC 页面
* 只迁移一个业务模块

不要在同一波里同时做：

* 页面改写
* 接口重构
* UI 改版
* 埋点体系调整

## 一个试点页面的迁移示例

原来的原生页面可能是：

```txt
pages/profile/
├─ index.js
├─ index.json
├─ index.wxml
└─ index.wxss
```

迁移后的第一版可以先做到：

```vue
<script setup lang="ts">
import { ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '个人中心',
}))

const nickname = ref('游客')
</script>

<template>
  <view class="page">
    <text>{{ nickname }}</text>
  </view>
</template>
```

第一版不要追求完美，只要：

* 页面跑通
* 结构稳定
* 可回滚

## 什么叫“可回滚迁移”

就是你每次迁移完一个模块，都能明确回答：

* 如果线上有问题，我能不能只回退这一波改动？
* 新旧页面是否能并存一段时间？
* 配置、路由、资源是否仍然兼容？

## 一份迁移清单

```txt
[ ] 先完成工具链接入
[ ] 目录和配置先整理，再迁移页面
[ ] 从一个低风险页面试点
[ ] 每次只迁移一个业务域
[ ] 每一波迁移都可独立验证和回滚
```

如果你当前正处在迁移期，建议配合这些页面一起看：

* [30 分钟快速开始](/handbook/)
* [先建立 SFC 心智模型](/handbook/sfc/)
* [为什么要用 Wevu](/handbook/wevu/)

---

---
url: /handbook/reference.md
description: 帮你在遇到具体问题时，快速判断应该回到 guide、config、wevu 还是源码，避免在文档体系里来回迷路。
---

# 参考入口与速查索引

当你已经顺着 handbook 学了一轮，后面最需要的往往不是“再看一遍教程”，而是：

> 现在这个具体问题，我应该回去哪一类文档查？

这页就是为这个目的准备的。

## 1. 先按问题类型找入口

### 1.1 我想知道某个功能怎么开启

去：

* [/guide/](/guide/)

例如：

* 自动路由
* 自动导入组件
* npm 构建
* WXML/WXS 增强

### 1.2 我想知道某个字段怎么配

去：

* [/config/](/config/)

例如：

* 分包
* Route Rules
* WXML/WXS 配置
* npm 配置

### 1.3 我想知道运行时能力边界

去：

* [/wevu/](/wevu/)
* [/wevu/api/](/wevu/api/)

例如：

* 生命周期
* 组件通信
* store
* runtime bridge

### 1.4 我想知道项目应该怎么组织

回：

* [/handbook/](/handbook/)

例如：

* 目录分层
* 页面跳转
* 请求层组织
* 上线前检查

## 2. 这一页也给你一个“源码地图”

当文档还不够时，可以继续看源码。
这时候最重要的不是“把整个仓库翻一遍”，而是知道先从哪里进。

### 2.1 想看 Vue SFC 编译相关

优先关注：

* `packages/weapp-vite/src/plugins/vue/`

### 2.2 想看 Wevu 运行时相关

优先关注：

* `packages-runtime/wevu/src/`

### 2.3 想看文档和网站导航组织

优先关注：

* `website/.vitepress/config.ts`

## 3. 一个常见问题到入口的映射表

| 你遇到的问题                 | 建议先去哪里                                                                                                           |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| 自动路由怎么开               | [/guide/auto-routes](/guide/auto-routes)                                                                               |
| 分包字段怎么配               | [/config/subpackages](/config/subpackages)                                                                             |
| Web Runtime 全局对象怎么注入 | [/guide/web-runtime-globals](/guide/web-runtime-globals) 和 [/config/web-runtime-globals](/config/web-runtime-globals) |
| `v-model` 在小程序里怎么写   | [/handbook/sfc/template](/handbook/sfc/template)                                                                       |
| 页面为什么不更新             | [/handbook/debugging](/handbook/debugging) 和 [/handbook/wevu/runtime](/handbook/wevu/runtime)                         |
| Wevu 生命周期怎么理解        | [/wevu/api/lifecycle](/wevu/api/lifecycle)                                                                             |
| Web 运行时支持到什么程度     | [/guide/web-compat-matrix](/guide/web-compat-matrix)                                                                   |
| 配置项总览在哪里             | [/config/](/config/)                                                                                                   |

## 4. 你也可以按“当前阶段”找

### 4.1 我在搭项目

先看：

* [30 分钟快速开始](/handbook/)
* [目录结构怎么放最顺手](/handbook/project-structure)
* [环境变量与配置怎么分层](/handbook/env-and-config)

### 4.2 我在写页面

先看：

* [先建立 SFC 心智模型](/handbook/sfc/)
* [为什么要用 Wevu](/handbook/wevu/)
* [页面跳转与路由参数](/handbook/navigation)

### 4.3 我在查问题

先看：

* [调试与排错（按层定位）](/handbook/debugging)
* [/troubleshoot/index](/troubleshoot/index)

### 4.4 我在准备上线

先看：

* [性能与体验优化](/handbook/performance)
* [构建、预览与上传](/handbook/publish)
* [调试与排错（按层定位）](/handbook/debugging)

## 5. 最后一个建议

当你遇到问题时，不要直接在整个文档站里盲搜关键词。
先判断它更像是：

* 功能用法问题
* 配置问题
* 运行时问题
* 项目组织问题

这样你会更快找到正确入口。

## 6. 速查表

| 你要找的东西 | 优先入口                 | 第二入口                                   |
| ------------ | ------------------------ | ------------------------------------------ |
| 功能开关     | [/guide/](/guide/)       | [/troubleshoot/index](/troubleshoot/index) |
| 配置字段     | [/config/](/config/)     | [/guide/](/guide/)                         |
| 运行时 API   | [/wevu/api/](/wevu/api/) | [/wevu/](/wevu/)                           |
| 教程路线     | [/handbook/](/handbook/) | [/handbook/reference](/handbook/reference) |

## 7. 参考资源

| 主题       | 推荐入口                                  |
| ---------- | ----------------------------------------- |
| 教程导读   | [参考入口与速查索引](/handbook/reference) |
| 运行时总览 | [Wevu 概览](/wevu/)                       |
| API 总览   | [Wevu API](/wevu/api/)                    |
| 常见问题   | [troubleshoot](/troubleshoot/index)       |

---

---
url: /migration.md
description: 汇总从原生小程序迁移到 weapp-vite + 原生 / weapp-vite + wevu，以及历史大版本升级的迁移入口与阅读顺序。
---

# 迁移

如果你是在新项目中直接使用最新版本，通常无需阅读本页。这里主要服务两类场景：

* 现有原生小程序项目，希望先迁移到 `weapp-vite + 原生`
* 现有原生小程序项目，希望进一步迁移到 `weapp-vite + wevu + Vue SFC`
* 已经在线上运行旧版本 `weapp-vite`，需要按版本跨度升级

推荐阅读顺序：

1. [从原生小程序迁移到 Weapp-vite / Wevu](../wevu/migration/from-native-to-vue-sfc.md)：先判断目标是 `weapp-vite + 原生`，还是继续升级到 `weapp-vite + wevu + Vue SFC`。
2. [从 v5 升级到 v6](./v6.md)
3. [从 v4 升级到 v5](./v5.md)
4. [从 v3 升级到 v4](./v4.md)
5. [从 v2 升级到 v3](./v3.md)

---

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


---

---
url: /wevu/api-reference.md
description: /wevu/api-reference/ 为兼容旧链接保留；当前 Wevu API 的规范入口已经迁移到 /wevu/api/。
---

# Wevu API 参考（旧路径兼容）

`/wevu/api-reference/` 这条路径当前仅用于兼容旧链接与历史搜索结果。

## 1. 当前规范入口

当前请统一使用新的 API 首页：

* [Wevu API](/wevu/api/)

## 2. 为什么要切换到新路径

| 原因         | 说明                                                         |
| ------------ | ------------------------------------------------------------ |
| 信息源更集中 | 新页面是当前维护中的规范入口                                 |
| 减少双轨漂移 | 避免 `/wevu/api-reference/*` 与 `/wevu/api/*` 内容长期不一致 |
| 站内导航一致 | 当前 sidebar、索引与后续维护都以 `/wevu/api/*` 为准          |

## 3. 迁移建议

如果你在旧文档、笔记或项目内部链接里还使用了 `/wevu/api-reference/*`，建议逐步替换为：

* `/wevu/api/core`
* `/wevu/api/reactivity`
* `/wevu/api/lifecycle`
* `/wevu/api/setup-context`
* `/wevu/api/store`
* `/wevu/api/runtime-bridge`
* `/wevu/api/types`

## 4. 参考资源

| 主题       | 推荐入口                    |
| ---------- | --------------------------- |
| API 首页   | [Wevu API](/wevu/api/)      |
| 运行时总览 | [Wevu 概览](/wevu/)         |
| 高阶路由   | [wevu/router](/wevu/router) |

---

---
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: /wevu/api-reference/core.md
description: 当前 Core API 的规范入口是 /wevu/api/core，本页仅用于兼容旧链接。
---

# Core API（旧路径兼容）

当前请改用新的规范入口：

* [Core API](/wevu/api/core)

## 1. 这页为什么还保留

这条旧路径主要用于兼容：

* 历史站内链接
* 搜索引擎已收录地址
* 外部文章、Issue、讨论帖中的旧链接

## 2. 推荐做法

以后引用 Core API 时，请统一使用新地址：

* [Core API](/wevu/api/core)

## 3. 参考资源

| 主题          | 推荐入口                                     |
| ------------- | -------------------------------------------- |
| API 首页      | [Wevu API](/wevu/api/)                       |
| Reactivity    | [Reactivity API](/wevu/api/reactivity)       |
| Setup Context | [Setup Context API](/wevu/api/setup-context) |

---

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


---

---
url: /wevu/api-reference/lifecycle.md
description: 当前 Lifecycle API 的规范入口是 /wevu/api/lifecycle，本页仅用于兼容旧链接。
---

# Lifecycle API（旧路径兼容）

当前请改用新的规范入口：

* [Lifecycle API](/wevu/api/lifecycle)

## 1. 推荐做法

以后引用生命周期 API 时，请统一使用新地址，避免旧路径与新路径双轨并存。

## 2. 参考资源

| 主题               | 推荐入口                                       |
| ------------------ | ---------------------------------------------- |
| Lifecycle API      | [Lifecycle API](/wevu/api/lifecycle)           |
| Reactivity API     | [Reactivity API](/wevu/api/reactivity)         |
| Runtime Bridge API | [Runtime Bridge API](/wevu/api/runtime-bridge) |

---

---
url: /wevu/api-reference/reactivity.md
description: 当前 Reactivity API 的规范入口是 /wevu/api/reactivity，本页仅用于兼容旧链接。
---

# Reactivity API（旧路径兼容）

当前请改用新的规范入口：

* [Reactivity API](/wevu/api/reactivity)

## 1. 推荐做法

后续引用 `ref`、`reactive`、`computed`、`watch` 等响应式 API 时，请统一指向新路径。

## 2. 参考资源

| 主题           | 推荐入口                               |
| -------------- | -------------------------------------- |
| Reactivity API | [Reactivity API](/wevu/api/reactivity) |
| Lifecycle API  | [Lifecycle API](/wevu/api/lifecycle)   |
| Store API      | [Store API](/wevu/api/store)           |

---

---
url: /wevu/api-reference/runtime-bridge.md
description: 当前 Runtime Bridge API 的规范入口是 /wevu/api/runtime-bridge，本页仅用于兼容旧链接。
---

# Runtime Bridge API（旧路径兼容）

当前请改用新的规范入口：

* [Runtime Bridge API](/wevu/api/runtime-bridge)

## 1. 推荐做法

涉及 `setWevuDefaults`、`markNoSetData`、mutation recorder 等桥接/调试 API 时，请统一引用新路径。

## 2. 参考资源

| 主题               | 推荐入口                                       |
| ------------------ | ---------------------------------------------- |
| Runtime Bridge API | [Runtime Bridge API](/wevu/api/runtime-bridge) |
| Setup Context API  | [Setup Context API](/wevu/api/setup-context)   |
| Wevu 概览          | [Wevu 概览](/wevu/)                            |

---

---
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: 当前 Setup Context API 的规范入口是 /wevu/api/setup-context，本页仅用于兼容旧链接。
---

# Setup Context API（旧路径兼容）

当前请改用新的规范入口：

* [Setup Context API](/wevu/api/setup-context)

## 1. 为什么优先使用新路径

`setup` 上下文相关 API 仍在持续演进，例如：

* `useNativeRouter()` / `useNativePageRouter()` 的语义边界
* `provideGlobal()` / `injectGlobal()` 的弃用说明
* `usePageLayout()` / `setPageLayout()` 等页面运行时辅助能力

这些更新会优先落在新的 `/wevu/api/setup-context` 页面。

## 2. 迁移建议

如果你在旧文档里使用了以下链接，请逐步替换：

* `/wevu/api-reference/setup-context`
* `/wevu/api-reference/setup-context#provideglobal`

替换为：

* [/wevu/api/setup-context](/wevu/api/setup-context)
* [/wevu/api/setup-context#provideglobal](/wevu/api/setup-context#provideglobal)

## 3. 参考资源

| 主题               | 推荐入口                                       |
| ------------------ | ---------------------------------------------- |
| Setup Context API  | [Setup Context API](/wevu/api/setup-context)   |
| Runtime Bridge API | [Runtime Bridge API](/wevu/api/runtime-bridge) |
| wevu/router        | [wevu/router](/wevu/router)                    |

---

---
url: /wevu/api-reference/store.md
description: 当前 Store API 的规范入口是 /wevu/api/store，本页仅用于兼容旧链接。
---

# Store API（旧路径兼容）

当前请改用新的规范入口：

* [Store API](/wevu/api/store)

## 1. 推荐做法

后续引用 `defineStore`、`createStore`、`storeToRefs` 等状态管理 API 时，请统一使用新路径。

## 2. 参考资源

| 主题              | 推荐入口                                     |
| ----------------- | -------------------------------------------- |
| Store API         | [Store API](/wevu/api/store)                 |
| Reactivity API    | [Reactivity API](/wevu/api/reactivity)       |
| Setup Context API | [Setup Context API](/wevu/api/setup-context) |

---

---
url: /wevu/api-reference/types.md
description: 当前 Type Reference 的规范入口是 /wevu/api/types，本页仅用于兼容旧链接。
---

# Type Reference（旧路径兼容）

当前请改用新的规范入口：

* [Type Reference](/wevu/api/types)

## 1. 推荐做法

后续引用 Wevu 类型总览时，请统一使用新路径，避免旧目录成为新的维护分叉点。

## 2. 参考资源

| 主题              | 推荐入口                                     |
| ----------------- | -------------------------------------------- |
| Type Reference    | [Type Reference](/wevu/api/types)            |
| Core API          | [Core API](/wevu/api/core)                   |
| Setup Context API | [Setup Context API](/wevu/api/setup-context) |

---

---
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/basics.md
description: Vue SFC：基础与组成，聚焦 guide / vue-sfc 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/basics](/wevu/vue-sfc/basics)。

---

---
url: /guide/vue-sfc/template.md
description: 本页已迁移至 /wevu/vue-sfc/template。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/template](/wevu/vue-sfc/template)。

---

---
url: /guide/vue-sfc/examples.md
description: 本页已迁移至 /wevu/vue-sfc/examples。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/examples](/wevu/vue-sfc/examples)。

---

---
url: /guide/vue-sfc/troubleshoot.md
description: 本页已迁移至 /wevu/vue-sfc/troubleshoot。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/troubleshoot](/wevu/vue-sfc/troubleshoot)。

---

---
url: /guide/vue-sfc/config.md
description: Vue SFC：配置与宏，聚焦 guide / vue-sfc 相关场景，覆盖 Weapp-vite 与 Wevu 的能力、配置和实践要点。
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/config](/wevu/vue-sfc/config)。

---

---
url: /demos/my-app/README.md
description: Weapp-vite 模板项目的最小使用说明，覆盖开发、构建与打开微信开发者工具的基础命令。
---

# Weapp-vite-template

`weapp-vite` 模板

## 使用方式

### 开发

* `pnpm dev`

* `pnpm dev --open` 可以打包并直接启动微信开发者工具

### 构建

`pnpm build`

### 打开微信开发者工具

`pnpm open`

### 生成组件/页面

`pnpm g path/to/your/component`

## 文档地址

0. `weapp-vite`: https://vite.icebreaker.top/
1. `weapp-tailwindcss`: https://tw.icebreaker.top/

---

---
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`
  * 直接支持 `wv 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`
* 使用 `wv 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-runtime/wevu-compiler/src/plugins/vue/transform/compileVueFile/index.ts`
* `packages-runtime/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-runtime/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 周：基线盘点

* 跑一次 `wv 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` 默认可用，`wv 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`：提供 `wv 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-runtime/wevu-compiler/src/plugins/vue/transform/compileVueFile/index.ts`
* `packages-runtime/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-runtime/wevu-compiler/src/plugins/vue/transform/jsonMacros/index.ts`
* `packages-runtime/wevu-compiler/src/plugins/vue/transform/jsonMacros/parse.ts`
* `packages-runtime/wevu-compiler/src/plugins/vue/transform/jsonMacros/rewrite.ts`

这让页面/组件配置可以写在同一份 SFC 上下文里，同时保持运行时零成本。

### 5.3 运行时：坚持 `diff + setData` 路线

运行时核心在 `packages-runtime/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
* 调用 `wv screenshot`
* 产出截图文件并给出机器可读结果

来源文档：`website/guide/ai.md`

***

# 案例 1 - 演示步骤

```bash
# 1) 启动 MCP（本地）
wv 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. 执行 wv 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-4.25`, 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-4.25` 转义为 `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
wv 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` 直接提供了 `wv 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: /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/vue-sfc/migrate-from-native.md
description: 本章节已迁移为独立迁移指南，不再归属到“Vue SFC 开发”子章节。
---

# 章节已迁移

本章节已迁移为独立迁移指南，不再归属到“Vue SFC 开发”子章节。

请访问新地址：

* [从原生小程序迁移到 Weapp-vite / Wevu（详细指南）](/wevu/migration/from-native-to-vue-sfc)

---

---
url: /llms.md
description: 兼容入口（/llms），与 /ai 共享同一套 AI 学习页面（含 MCP 接入指引）。
---