---
url: /packages/mcp.md
---
# @weapp-vite/mcp

`@weapp-vite/mcp` 是一个 MCP 示例服务包，用于展示如何基于 MCP SDK 注册工具并通过 stdio 传输响应调用。

> 该包以教学和验证为主，不是面向生产的完整服务框架。

## 何时使用

* 你要快速理解 MCP 服务端最小结构
* 你要验证 MCP Client 与 stdio 服务联调流程
* 你要基于示例改造自己的工具服务

## 安装

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

## 运行示例

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

包内示例包含两个工具：

* `calculate-bmi`
* `fetch-weather`

## 二次开发建议

直接修改 `packages/mcp/src/index.ts`：

* 新增工具与参数 schema（zod）
* 调整服务 `name/version`
* 接入真实业务 API 与鉴权逻辑

---

---
url: /packages/volar.md
---
# @weapp-vite/volar

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

## 何时使用

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

## 安装说明

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

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

## 主要能力

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

## 推荐阅读

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

---

---
url: /packages/web.md
---
# @weapp-vite/web

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

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

## 何时使用

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

## 安装

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

## Vite 插件接入

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

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

## 运行时能力

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

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

## 能力边界

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

---

---
url: /packages/weapi.md
---
# @wevu/api

`@wevu/api` 提供跨平台小程序 API 封装，默认推荐 Promise 调用方式，同时兼容传统回调风格。

## 何时使用

* 你希望在业务层统一调用 `wx/my/tt` 等平台能力
* 你希望优先使用 Promise，减少回调嵌套
* 你希望按平台显式注入适配器

## 安装

```bash
pnpm add @wevu/api
```

## 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
* 缺失 API 时，Promise 风格会 `reject`，回调风格会触发 `fail`

---

---
url: /packages/wevu-compiler.md
---
# @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: /deep/init.md
---
# `weapp-vite init` 做了什么？

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

> \[!TIP]
> 如果你更倾向于完全手工搭建，也可以把下面每一小节视为 Checklist，按需执行对应步骤。

## 1. 修改 `project.config.json`

* 设置 `miniprogramRoot` 指向 weapp-vite 产物目录（默认 `dist`），确保微信开发者工具预览/上传的始终是编译后的文件。
* 统一 `npm` 构建相关字段，避免与 weapp-vite 的自动 npm 策略冲突。

> 手工迁移时，记得在开发者工具中重新选择项目根目录或刷新配置，使其指向新的 `dist` 路径。

## 2. 更新 `package.json`

* 添加 `pnpm dev`、`pnpm build`、`pnpm open` 等脚本，与 weapp-vite CLI 对齐。
* 安装基础依赖（`weapp-vite`、`typescript`、`@types` 系列）以及推荐的工具链。

脚本示例：

```json
{
  "scripts": {
    "dev": "weapp-vite dev",
    "build": "weapp-vite build",
    "open": "weapp-vite open",
    "lint": "eslint . --ext .ts,.js --fix"
  }
}
```

## 3. 新增 `tsconfig.json` 与 `vite-env.d.ts`

* `tsconfig.json` 提供 TypeScript 编译基础配置，并启用小程序类型提示。
* `vite-env.d.ts` 声明 weapp-vite 自动注入的全局类型，避免在编辑器中出现缺失提示。

如果项目暂不使用 TypeScript，也建议保留这些文件，以便后续随时开启类型支持。

## 4. 生成 `vite.config.[m]ts`

* 创建标准的 `vite.config.ts`（或 `vite.config.mts`）并写入 weapp-vite 默认配置。
* 默认配置中包含 `weapp: { srcRoot: '.', subPackages: [] }` 等常用字段，你可以在此基础上继续补充别名、插件等设置。

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

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

> \[!IMPORTANT]
> 若项目目录结构特殊（例如 `app.json` 位于 `miniprogram/`），请记得修改 `srcRoot`，并结合 [基础目录与资源收集配置](/config/paths.md) 进行调优。

## 5. 更新 `.gitignore`

* 添加 `dist/`、`node_modules/`、临时缓存等条目，避免编译产物误入版本库。
* 如果项目已有 `.gitignore`，脚手架会合并新条目而非覆盖原内容。

## 6. 其他辅助文件

* 视情况添加 `README` 提示、`pnpm-workspace.yaml`（在 Monorepo 场景下）等文件。
* 对于 SCSS/Tailwind 等需要额外配置的工具，脚手架会保留注释提示下一步应该如何开启。

***

完成 `weapp-vite init` 后，建议依次执行：

1. `pnpm install` 安装依赖；
2. `pnpm dev --open` 验证项目能在微信开发者工具中正常运行；
3. 参考 [快速开始](/guide/) 继续进行页面开发或自定义配置。

如需还原或自定义初始化流程，可直接查看源码：[`@weapp-core/init`](https://github.com/weapp-vite/weapp-vite/tree/main/@weapp-core/init)。

---

---
url: /blog/announce.md
---
![bg](./assets/release4.png)

# `weapp-vite` 发布：重塑小程序开发体验！

大家好，我是[`ice breaker`](https://github.com/sonofmagic)，也是[`weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss)项目的作者。

今天，我非常高兴地宣布`weapp-vite`项目的正式发布，这标志着我在`vite`框架应用与探索上的一个阶段性成果。

`weapp-vite`不仅是我对`vite`技术深入理解和实践的产物，更是我在小程序开发领域的一次创新尝试。该项目旨在结合`vite`的极速构建与热重载能力，为小程序开发者带来更加高效、流畅的开发体验。

通过`weapp-vite`，我们希望能够为小程序开发者提供一种全新的解决方案，让开发过程更加便捷、灵活。同时，我们也期待与广大开发者共同探索`vite`在小程序领域的更多可能性，共同推动小程序开发技术的进步与发展。

## 什么是 `weapp-vite`?

`weapp-vite` 是对 `vite` 的封装，专为小程序开发设计。

它保留了 `vite` 的强大配置和插件系统，同时针对小程序的开发流程进行了优化，支持 `ts`、`postcss`、`sass`、`less` 等现代前端技术栈，让小程序开发更加高效、便捷。

## 诞生背景

### 原生小程序开发的痛点

在深入探索小程序开发的过程中，我深刻体会到了原生小程序开发方式所带来的不便与局限。繁琐的构建流程、有限的工具支持，使得开发体验难以令人满意。同时，跨端框架如`uni-app`、`tarojs`等，虽然提供了多平台兼容的能力，但其基于`vue`、`react`等Web框架的写法，对于追求原生体验的开发者来说，显得过于沉重与冗余。此外，尽管这些框架开源，但源代码的复杂性往往让人望而却步，难以深入理解和定制。

### 差异化加剧的挑战

随着小程序生态的不断发展，各平台之间的差异日益显著。微信小程序凭借其持续的技术投入和创新，如`skyline`、`Donut`等项目的推进，展现出了强大的生命力和未来潜力。然而，这也对开发者提出了更高的要求，需要更加紧密地跟随官方技术动态，以充分利用平台优势。与此同时，其他平台也在不断探索和进步，但市场的竞争与变化使得开发者在选择和适配上面临更多挑战。

### 轻量化与灵活性的追求

鉴于上述痛点与挑战，我萌生了打造一款既轻量化又灵活的小程序开发解决方案的想法。`weapp-vite`应运而生，它保留了`vite`的极速构建与灵活配置优势，同时针对小程序开发流程进行了深度优化。通过引入编译插件系统，`weapp-vite`允许开发者以原生小程序语法为基础，轻松扩展至其他平台，实现所见即所得的跨端开发体验。

### `weapp-vite`的优势

* **轻量级构建**：专注于小程序开发的核心需求，提供极简的构建流程与配置选项。
* **灵活扩展**：利用`vite`的插件生态与编译插件系统，轻松实现功能的定制与增强。
* **高度自定义**：支持对小程序语法的深度自定义与转换，满足不同平台的开发需求。
* **紧跟官方步伐**：以原生小程序语法为基础，确保与官方技术动态保持同步。

综上所述，`weapp-vite`的诞生旨在解决原生小程序开发的痛点，提升开发效率与灵活性，同时保持对技术前沿的敏锐洞察与响应。我们期待与广大开发者携手共进，共同探索小程序开发的无限可能。

## 快速开始

### 创建与初始化

1. 在微信开发者工具中创建一个新的 `js`/`ts` 项目。

![](../images/create-project.png)

2. 确保项目根目录下有 `package.json`，若无则运行 `npm init -y`

> 假如你创建的是一个 `ts` 项目，你需要在 `vite.config.ts` 里的 `weapp.srcRoot` 配置项，指明使用的是 `'./miniprogram'` 目录，详见本页下方

3. 安装 weapp-vite 并执行初始化命令

```sh
npm i -D weapp-vite
# 执行初始化命令
npx weapp-vite init
```

于是就初始化成功了！然后再执行一下安装包的命令，去安装智能提示的类型定义

```sh
npm i
```

这样微信开发小程序的智能提示(`types`)，就也被安装进来

## 语言默认支持

你可以直接使用 `typescript`，把 `js` 改成 `ts` 后缀即可，也可以通过安装 `sass` / `less`，并把 `index.wxss` 的后缀名改成相应的后缀来支持样式预处理器，比如 `scss` / `less` 。

## 开发与构建

* 开发模式：使用 `npm run dev` 启动开发服务器，实时监听文件变化并自动编译。
* 构建模式：通过 `npm run build` 进行生产环境的构建，包括代码压缩等优化。
* 构建 npm：`npm run build-npm` 用于微信开发者工具中的 npm 构建，输出至 `dist/miniprogram_npm`。
* 打开微信开发者工具：`npm run open` 直接启动微信开发者工具，便捷调试。

## 配置项

配置项可以与 `vite` 通用，同时加入了 `weapp-vite` 的扩展:

`vite.config.ts`:

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

export default defineConfig({
  // 其他的配置同
  weapp: {
    // 用来配置监听 app.json 所在的目录
    // 比如默认情况下 ts 创建的项目，app.json 所在为 './miniprogram'
    srcRoot: './miniprogram',
    // weapp-vite options
  },
})
```

![Image](https://pic4.zhimg.com/80/v2-ebc9231004dc0d7582a21d3af7acd302.png)
你可以在 `defineConfig` 使用其他的 `vite` 插件，比如 `weapp-tailwindcss`

## 关于 `weapp-vite` 的承诺与展望

在过去的三年里，`weapp-tailwindcss` 不仅见证了小程序开发社区的蓬勃发展，也陪伴了无数开发者从初识到精通的旅程。这份历程教会了我耐心、细致与不懈追求。现在，我将这份恒心带入 `weapp-vite`，致力于打造一个更加高效、灵活且易于使用的小程序开发解决方案。

## 期待大家的加入

`weapp-vite` 刚刚起步，虽已初具雏形，但仍有许多待完善之处。我诚挚邀请各位开发者加入我们的行列，共同推动项目的成长：

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

## 未来展望

展望未来，`weapp-vite` 将不断进化以适应小程序开发的最新趋势。我们将持续关注各平台小程序的更新迭代，确保 `weapp-vite` 能够无缝兼容并充分利用这些新特性。同时，我们也期待与广大开发者建立更加紧密的联系，听取大家的意见与建议，共同推动 `weapp-vite` 的发展与完善。

## 尾言

感谢每一位对 `weapp-tailwindcss` 及 `weapp-vite` 给予关注与支持的朋友。让我们携手并进，在小程序开发的道路上不断前行，共创辉煌！

[GitHub 项目地址](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/packages/weapp-vite)

---

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


---

---
url: /packages/rolldown-require/options.md
---
# API & options

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

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

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

## Common options

### filepath / cwd

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

### format

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

### require

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

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

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

### rolldownOptions

Pass through parts of rolldown options:

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

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

### external

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

### tsconfig

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

### getOutputFile

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

### preserveTemporaryFile

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

### cache

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

## Example configuration

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

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

This setup will:

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

---

---
url: /packages/rolldown-require/options.zh.md
---
# 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: /wevu/vue-sfc/class-style.md
---

# 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: /packages/create-weapp-vite.md
---
# create-weapp-vite

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

## 何时使用

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

## 快速开始

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

### 非交互模式

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

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

## 可编程 API

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

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

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

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

## 与主文档的关系

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

---

---
url: /wevu/component.md
---

# 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`；也可写 `defineComponent({ pageLifetimes: { ... } })`                                             | `show/hide/resize` 会被 wevu 包装以派发 hook；其他字段按原生透传执行。                                                                                                                                                                   |
| `properties`       | 推荐：`props`；也可：`defineComponent({ properties: { ... } })`                                                                   | `props` 会被 wevu 规范化为原生 `properties`；如果同时传了 `props` 与 `properties`，以 `props` 生成的 `properties` 为准。                                                                                                                 |
| `relations`        | `defineComponent({ relations: { ... } })`                                                                                         | 原样透传。                                                                                                                                                                                                                               |

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

## 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`                 | 所在页面尺寸变化（参数透传原生回调） |

---

---
url: /config/js.md
---
# JS 配置 {#js-config}

`weapp-vite` 内置集成了 `vite-tsconfig-paths`，用于读取 `tsconfig.json/jsconfig.json` 的 `paths/baseUrl`，把别名映射到 Vite/Rolldown 流程中。

\[\[toc]]

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

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

启用规则：

* 当 `tsconfig.json` 或 `jsconfig.json` **存在 `paths` 或 `baseUrl`** 时，会自动启用该插件；
* 若你显式配置 `weapp.tsconfigPaths`，则以你的配置为准；
* 传入 `false` 可完全禁用（适合没有别名需求、追求更快启动的项目）。

```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` 负责把 **tsconfig 的 paths/baseUrl** 转成 Vite alias。
* 你仍然可以在 `resolve.alias` 中补充或覆盖特定映射，两者可共存。

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

### 常见问题

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

***

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

---

---
url: /config/json.md
---
# JSON 配置 {#json-config}

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

\[\[toc]]

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

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

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

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

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

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

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

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

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

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

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

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

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

说明：

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

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

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

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

函数策略会收到上下文：

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

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

***

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

---

---
url: /guide/json-intelli-sense.md
---
# 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: /packages/rolldown-require/cache.md
---
# Loading flow & cache

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

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

## End-to-end flow

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

## Externalization & resolution

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

## Temp output control

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

## Cache strategy

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

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

Example: log cache events and set a custom directory

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

## Debugging tips

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

---

---
url: /integration/miniprogram-computed.md
---
# miniprogram-computed 集成

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

## 安装

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

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

## 使用方式

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

相关 `issues`:

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

---

---
url: /guide/npm.md
---
# npm 自动构建

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

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

## 自动构建

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

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

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

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

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

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

### 详细解释

看一个最常见的例子：

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

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

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

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

### 怎么选（建议）

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

## 手动构建

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

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

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

---

---
url: /config/npm.md
---
# npm 配置 {#config-npm}

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

\[\[toc]]

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

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

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

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

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

* **类型**：
  ```ts
  {
    enable?: boolean
    cache?: boolean
    buildOptions?: (options: NpmBuildOptions, meta: { name: string; entry: InputOption }) => NpmBuildOptions | undefined
  }
  ```
* **默认值**：`{ enable: true, cache: true }`

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

export default defineConfig({
  weapp: {
    npm: {
      enable: true,
      cache: true,
      buildOptions(options, { name }) {
        if (name === 'lodash') {
          return {
            ...options,
            build: {
              ...options.build,
              target: 'es2018',
            },
          }
        }
        return options
      },
    },
  },
})
```

字段说明：

* `enable`：关闭后 **不会自动构建** `miniprogram_npm`。如果你的代码仍保留 `require('pkg')`，需要自行处理（如 devtools 构建 npm）。
* `cache`：是否启用 npm 构建缓存（缓存目录：`node_modules/weapp-vite/.cache/`）。
* `buildOptions`：为单个包覆写 Vite 库模式构建参数。

## 手动构建命令

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

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

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

## 常见问题

* **npm 构建内容未更新**：尝试将 `cache` 设为 `false`，或清理 `node_modules/weapp-vite/.cache/`。
* **分包体积过大**：结合 `weapp.subPackages.*.dependencies` 裁剪独立分包依赖。

***

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

---

---
url: /packages/rolldown-require.md
---
# rolldown-require Guide

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

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

## What problems it solves

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

## Install

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

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

## Quick start

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

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

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

`bundleRequire` will:

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

## How it differs from bundle-require

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

## Next steps

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

---

---
url: /packages/rolldown-require/index.zh.md
---
# rolldown-require 使用指南

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

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

## 它解决什么问题

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

## 安装

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

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

## 快速开始

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

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

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

`bundleRequire` 会：

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

## 和 bundle-require 的区别

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

## 下一步

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

---

---
url: /wevu/store.md
---

# Store（状态管理）

wevu 内置了类 Pinia 的 Store：

* 用 `defineStore()` 定义 Store
* 用 `useXxx()` 获取**单例**实例
* 用 `storeToRefs()` 解构 state/getter，避免丢失响应式

:::tip 导入约定
运行时 API 均从 `wevu` 主入口导入；不支持 `wevu/store` 子路径；`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 专属能力。

## 常见问题

* 不要从 `wevu/store` 导入，所有 API 均在 `wevu` 主入口。
* 不需要为了使用 store 先调用 `createStore()`；仅在使用插件时才需要。

---

---
url: /integration/tailwindcss.md
---
# Tailwindcss 集成

## 直接使用模板（推荐）

如果你是新项目，直接用官方模板创建即可，模板已集成 Tailwind CSS：

```sh
pnpm create weapp-vite
```

## 手动集成

如果你要在现有项目里手动接入 Tailwind CSS，请按下面文档操作：

* https://tw.icebreaker.top/docs/quick-start/native/install

---

---
url: /integration/tdesign.md
---
# 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: /dashboard.md
---


---

---
url: /integration/vant.md
---
# 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: /packages/vite-plugin-performance.md
---
# 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: /wevu/vue-sfc/vue3-vs-weapp-sfc.md
---

# Vue 3 SFC vs weapp-vite SFC：写法对比

这篇文档聚焦“写法层面”的相同与不同：当你用 weapp-vite + wevu 写 `.vue`，哪些和 Vue 3 SFC 一样，哪些因为小程序编译/运行时而发生变化。

## 相同点（写法层面）

* **SFC 结构一致**：`<template>` / `<script setup>` / `<script>` / `<style>` 这些块仍然是主入口。
* **Composition API 语法一致**：`ref` / `reactive` / `computed` / `watch` / `onMounted` 等写法保持 Vue 3 心智。
* **`setup(props, ctx)` 签名一致**：`props` 与 `ctx` 仍是第一、第二参数，SFC 可以同时写 Options API 与 Composition API。
* **Script Setup 宏一致**：`defineProps` / `defineEmits` / `defineExpose` / `defineSlots` / `defineModel` 等宏仍可用（主要用于类型与编译期消解）。

## 不同点（由小程序编译/运行时造成）

### 1. 模板目标不是 DOM，而是 WXML

* 模板会被编译成 WXML，标签与属性遵循小程序规范（如 `view` / `text` / `image`）。
* 事件名会被映射到小程序事件（例如 `@click` 会映射为 `bindtap`）。
* `v-model` 会被编译成小程序事件 + 数据集路径（`bindinput="__weapp_vite_model"` + `data-wv-model="..."`），并只对部分表单元素有专门映射。
* `v-bind="object"` 不会展开为属性，需要显式写 `:prop="..."`。

细节参考：`/wevu/vue-sfc/template`。

### 2. 组件注册方式不同：usingComponents 仍是最终产物

Vue 3 中常见写法是“import + 注册/自动注册”。小程序最终仍要求 **JSON 声明式** 的 `usingComponents`，但 weapp-vite 支持在**编译期**把“import + 模板使用”转为 `usingComponents`，因此可以保留类似的写法心智。

在 weapp-vite 中：

* `usingComponents` 可以写在 `<json>` 或 `definePageJson/defineComponentJson` 宏里。
* 编译器会从 **模板标签** 与 **`<script setup>` 导入** 自动补齐 `usingComponents`（编译期生成，不是运行时注册）。
* 对应的组件导入会被移除，仅作为编译期元信息使用。

细节参考：`/wevu/vue-sfc/config`。

### 3. 新增 `<json>` 与 JSON 宏（Vue 3 没有）

weapp-vite 允许在 `.vue` 中直接写小程序配置：

* `<json>` 自定义块（支持 json/jsonc/json5）。
* `<script setup>` 中的 `defineAppJson / definePageJson / defineComponentJson`（构建期执行并合并到最终 JSON）。

这些配置最终生成 `app.json / page.json / component.json`，属于小程序必需产物。

### 4. 运行时来源是 wevu（而非 vue）

SFC 运行时基于 **wevu**，不是浏览器 DOM：

* `defineComponent`、`ref` 等 API 应从 `wevu` 导入。
* weapp-vite 会把部分 `vue` 运行时 API 重写为 `wevu` 版本（如 `useAttrs` / `useSlots` / `useModel`）。
* `ctx.emit` 实际调用的是小程序 `triggerEvent`，只携带 `detail` 单一载荷。

### 5. 样式输出是 WXSS，scoped 规则不同

* `<style>` 会编译为 WXSS，支持 `lang` 与 `scoped` / CSS Modules，但输出受 WXSS 规则限制。
* `scoped` 通过注入属性选择器实现（`data-v-xxx`），不是 DOM 级别的作用域计算。
* class/style 绑定会注入运行时代码（JS/WXS）以适配小程序模板能力。

## 快速对照示例

Vue 3（Web）：

```vue
<script setup lang="ts">
import { ref } from 'vue'
import MyCard from './MyCard.vue'

const count = ref(0)
</script>

<template>
  <MyCard :count="count" @click="count++" />
</template>
```

weapp-vite + wevu（小程序）：

```vue
<script setup lang="ts">
import { ref } from 'wevu'
import MyCard from './MyCard.vue'

// 编译期会根据 import + 模板使用自动生成 usingComponents
const count = ref(0)
</script>

<template>
  <MyCard :count="count" @click="count++" />
</template>
```

## 实用总结

* **“写法像 Vue 3，产物是小程序”**：语法趋同，但目标平台完全不同。
* **优先认清两层**：模板/配置在编译期解决，响应式与生命周期在 wevu 运行期解决。
* **遇到问题先分层**：模板/指令 → 看 weapp-vite 编译；状态/生命周期 → 看 wevu 运行时。

---

---
url: /guide/vue-sfc.md
---

# Vue SFC 开发

这里是 Vue SFC 开发的入口说明。完整内容已迁移到 `wevu` 文档目录：weapp-vite 负责编译期（`.vue` → 小程序产物），wevu 负责运行期（响应式与生命周期）。

## 目录

* [总览](/wevu/vue-sfc/)
* [基础与组成](/wevu/vue-sfc/basics)
* [配置与宏](/wevu/vue-sfc/config)
* [模板与指令](/wevu/vue-sfc/template)
* [示例](/wevu/vue-sfc/examples)
* [调试与排错](/wevu/vue-sfc/troubleshoot)

---

---
url: /wevu/vue-sfc.md
---

# 在 weapp-vite 中使用 Vue SFC

weapp-vite 内置了 Vue SFC 编译链路，配合 `wevu` 运行时即可用 Vue 风格开发小程序页面/组件，同时保持小程序能力（页面特性、分享、性能优化）。

> 适用版本：Vue SFC 仅在 `weapp-vite@6.x` 及以上可用，请先升级到 6 大版本。

## 快速开始

* 需要安装 `wevu`（任意包管理器均可 `add/install wevu`）。
* 官方模板已默认带上，手动集成时请先装依赖再继续。

## 心智模型

Vue SFC 在小程序里建议拆成两段：

* **编译期（weapp-vite）**：负责把 `.vue` 拆解/编译为小程序产物（WXML/WXSS/JS/JSON），并做模板语法（如 `v-if/v-for/v-model`）到 WXML 的转换。
* **运行期（wevu）**：负责响应式、生命周期 hooks、快照 diff 与最小化 `setData`，让你用 Vue 3 风格的 Composition API 写业务逻辑。

```mermaid
flowchart LR
  A[Vue SFC<br/>.vue] --> B[编译期<br/>weapp-vite]
  B --> C[小程序产物<br/>WXML / WXSS / JS / JSON]
  C --> D[运行期<br/>wevu]
  D --> E[小程序逻辑层<br/>响应式 / hooks / diff + setData]
  E --> F[渲染层更新<br/>UI]
```

## 章节导航

* [基础与组成](/wevu/vue-sfc/basics)：SFC 各块作用、宏/指令的编译时与运行时、页面与组件区分等
* [配置与宏](/wevu/vue-sfc/config)：`usingComponents` 规则、`<json>` 与 Script Setup JSON 宏
* [模板与指令](/wevu/vue-sfc/template)：页面事件触发机制、`v-model` 支持范围与限制
* [class/style 绑定](/wevu/vue-sfc/class-style)：对齐 Vue 3 的 class/style 语法与运行时模式
* [示例](/wevu/vue-sfc/examples)：页面示例与组件 `v-model` 示例
* [调试与排错](/wevu/vue-sfc/troubleshoot)：常见问题定位与建议
* [Vue 3 写法对比](/wevu/vue-sfc/vue3-vs-weapp-sfc)：与 Vue 3 SFC 写法的相同点/不同点

迁移相关内容已独立成章节，请阅读：[从原生小程序迁移到 Vue SFC（详细指南）](/wevu/migration/from-native-to-vue-sfc)。

---

---
url: /config/vue.md
---
# Vue SFC 配置 {#vue-config}

`weapp-vite` 内置 Vue SFC（`.vue` → WXML/WXSS/JS/JSON）编译链路。这里聚焦编译期可配置项。

\[\[toc]]

## `weapp.vue.enable` {#weapp-vue-enable}

* **类型**：`boolean`
* **默认值**：`true`
* **说明**：保留字段。当前版本会在检测到 `.vue` 时自动启用 SFC 支持，该字段不影响行为。

## `weapp.vue.template` {#weapp-vue-template}

* **类型**：
  ```ts
  {
    // 注意：removeComments / simplifyWhitespace 暂未接入编译流程
    removeComments?: boolean
    simplifyWhitespace?: boolean
    scopedSlotsCompiler?: 'auto' | 'augmented' | 'off'
    scopedSlotsRequireProps?: boolean
    slotMultipleInstance?: boolean
    classStyleRuntime?: 'auto' | 'wxs' | 'js'
    classStyleWxsShared?: boolean
  }
  ```

示例：

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

export default defineConfig({
  weapp: {
    vue: {
      template: {
        scopedSlotsCompiler: 'auto',
        scopedSlotsRequireProps: true,
        slotMultipleInstance: true,
        classStyleRuntime: 'js',
        classStyleWxsShared: true,
      },
    },
  },
})
```

字段说明：

* `scopedSlotsCompiler`：作用域插槽编译策略。
  * `auto`：自动选择最小可用方案（默认）。
  * `augmented`：强制使用增强方案。
  * `off`：关闭 scoped slot（仅保留原生 slot，不支持 slot props）。
* `scopedSlotsRequireProps`：仅在 slot 传递作用域参数时才生成 scoped slot 组件。默认值随 `scopedSlotsCompiler` 自动推导。
* `slotMultipleInstance`：`v-for` 下 scoped slot 多实例模式（默认 `true`）。
* `classStyleRuntime`：class/style 绑定运行时。
  * `js`：强制 JS（默认）。
  * `auto`：平台支持 WXS 时优先 WXS，否则回退 JS。
  * `wxs`：强制 WXS，不支持时回退 JS 并告警。
* `classStyleWxsShared`：是否复用 class/style 的 WXS helper（主包与非独立分包共享，独立分包各自生成）。

> \[!NOTE]
> `removeComments` / `simplifyWhitespace` 目前尚未接入实际编译流程，仅保留类型入口。

## `weapp.vue.autoImport` {#weapp-vue-autoimport}

* **类型**：`boolean`
* **默认值**：`undefined`
* **说明**：保留字段，当前不影响构建行为。

> 组件自动导入请使用 [`weapp.autoImportComponents`](/config/auto-import-components.md)。

---

---
url: /guide/vue-sfc/basics.md
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/basics](/wevu/vue-sfc/basics)。

---

---
url: /wevu/vue-sfc/basics.md
---

# 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 配置；也可在 SFC `<json>` 块中编写静态配置。配合 `weapp-vite/volar` 获得智能提示。
* 模板语法与 Vue 3 基本一致（事件、v-if/v-for/class/style 绑定），构建时转为小程序原生 WXML。
* 样式使用 `<style lang="scss|less|css">`，构建后输出 `wxss`。
* 组件引入沿用小程序约定：在 `<json>` 的 `usingComponents` 中声明，脚本里不要用 ESModule `import` 引入组件。
* props 推荐：wevu 会把 Vue 风格的 `props` 规范化为小程序 `properties`，原生 `properties` 亦兼容。

## 页面与组件：如何区分

在微信小程序里，页面与组件都是“用 `Component()` 注册”的，但它们的 JSON 字段与生命周期事件并不一样。

* **页面**：通常位于 `src/pages/**/index.vue`，最终会出现在 `app.json` 的 `pages` 列表中（来源依赖你的路由/扫描策略）。
  * 页面配置用 `definePageJson()` 或 `<json>` 写（最终生成 `page.json`）。
  * 页面 hooks（滚动/分享/触底/下拉刷新等）只对页面生效。
* **组件**：通常位于 `src/components/**/index.vue`，通过页面/组件 JSON 的 `usingComponents` 使用。
  * 组件配置用 `defineComponentJson()` 或 `<json>` 写（最终生成 `component.json`），并确保 `component: true`。

组件最小示例（只展示关键字段）：

```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` 可写在 `<json>` 块，也可通过 Script Setup JSON 宏注入；脚本侧不要通过 `import` 注册小程序组件（见“配置与宏”章节）。
* 避免直接使用 `window/document` 等浏览器专属能力，需改用微信小程序 API；模板事件使用小程序事件名（`@tap` 等）。

---

---
url: /guide/vue-sfc/template.md
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/template](/wevu/vue-sfc/template)。

---

---
url: /wevu/vue-sfc/template.md
---

# Vue SFC：模板与指令

## 页面事件与生命周期：怎么触发

在小程序里，很多页面事件属于“按需派发”：

* 只有你定义了 `onPageScroll/onReachBottom/onPullDownRefresh/...` 这些页面方法，事件才会从渲染层派发到逻辑层。
* `wevu` 的 `onPageScroll/onShareAppMessage/...` hooks，本质也是在注册对应页面方法。

```mermaid
flowchart LR
  R[渲染层] -->|scroll/share/...| P[Page 方法 onXxx]
  P --> W[wevu hooks 桥接]
  W --> L[setup 同步注册的回调]

  Note[说明：按需派发<br/>没定义 onXxx 就不会派发] -.-> P
```

你通常不需要手写 `features.enableOnXxx`：

* **使用 weapp-vite 构建**：当编译器检测到你调用了对应 hooks，会在编译阶段自动补齐 `features.enableOnXxx = true`。
* **不使用 weapp-vite（或极端场景）**：才需要在 `defineComponent({ features: ... })` 里手动开启。

## v-model 支持范围与限制

`weapp-vite` 的 Vue 模板编译会把 `v-model="x"` 直接编译成**小程序的“赋值表达式事件”**（例如 `bind:input="x = $event.detail.value"`），因此它有一些明确限制：

* **表达式必须可赋值**：只建议写 `x` / `x.y` / `x[i]` 这类“左值”。不要写 `a + b`、函数调用、可选链（`a?.b`）等。
* **不支持 v-model 参数/修饰符**：`v-model:title`、`v-model.trim/.number/.lazy` 目前不会按 Vue 语义生效（会当作普通 v-model 处理，可能导致行为不符合预期）。
* **仅对部分表单元素做了专门映射**（见下表）。其他标签会退化为 `value + bind:input` 并给出编译警告。

当前内置映射（实现位于 `packages/weapp-vite/src/plugins/vue/compiler/template.ts`）：

| 标签                    | 绑定属性  | 事件          | 赋值来源                                    |
| ----------------------- | --------- | ------------- | ------------------------------------------- |
| `input`（默认/text）    | `value`   | `bind:input`  | `$event.detail.value`                       |
| `input type="checkbox"` | `checked` | `bind:change` | `$event.detail.value`（实现为 best-effort） |
| `input type="radio"`    | `checked` | `bind:change` | `$event.detail.value`                       |
| `textarea`              | `value`   | `bind:input`  | `$event.detail.value`                       |
| `select`                | `value`   | `bind:change` | `$event.detail.value`                       |
| `switch` / `checkbox`   | `checked` | `bind:change` | `$event.detail.value`                       |
| `slider` / `picker`     | `value`   | `bind:change` | `$event.detail.value`                       |

> 建议：复杂/非标准表单（如 `radio-group` / `checkbox-group`）或自定义组件，优先使用显式 `:value` + `@input/@change`，或者用 `wevu` 的 `ctx.bindModel()` 自己定义 `event/valueProp/parser`。

```mermaid
flowchart TB
  A[v-model=\"x\"] --> B{标签类型}
  B -->|input/textarea| C[value + bind:input<br/>x = $event.detail.value]
  B -->|switch/checkbox| D[checked + bind:change<br/>x = $event.detail.value]
  B -->|slider/picker| E[value + bind:change<br/>x = $event.detail.value]
  B -->|其它/自定义| F[退化为 value + bind:input<br/>并给出编译警告]
```

## v-bind 限制

`v-bind="object"`（对象展开）目前不会生成任何属性，等同于未绑定。
建议改为显式写法：`:<prop>="..."` + `@<event>="..."`。

## 延伸阅读

* [class/style 绑定能力](/wevu/vue-sfc/class-style)

---

---
url: /guide/vue-sfc/examples.md
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/examples](/wevu/vue-sfc/examples)。

---

---
url: /wevu/vue-sfc/examples.md
---

# Vue SFC：示例

## 页面示例：计数 + 分享 + 页面滚动

```vue
<!-- pages/counter/index.vue -->
<script setup lang="ts">
import { computed, onPageScroll, onShareAppMessage, ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '计数器',
}))

const count = ref(0)
const doubled = computed(() => count.value * 2)
const reachedTop = ref(true)

onPageScroll(({ scrollTop }) => {
  reachedTop.value = scrollTop < 40
})

onShareAppMessage(() => ({
  title: `当前计数 ${count.value}`,
  path: '/pages/counter/index',
}))

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

<template>
  <view class="page">
    <text>count: {{ count }} / doubled: {{ doubled }}</text>
    <text v-if="!reachedTop">
      正在滚动...
    </text>
    <button @tap="inc">
      +1
    </button>
  </view>
</template>
```

> 说明：小程序部分页面事件是“按需派发”（分享/滚动等），weapp-vite 会在编译阶段根据你是否调用 `onPageScroll/onShareAppMessage/...` 自动补齐 `features.enableOnXxx = true`；如需手动控制，仍可在 `defineComponent({ features: ... })` 中显式覆盖。

## 组件示例：Props + Emits + v-model（Script Setup + 宏）

这个示例展示一个自定义组件如何配合 `v-model` 工作。对于自定义组件，`weapp-vite` 会把 `v-model="x"` 按默认策略编译为 `value="{{x}}"` + `bind:input="x = $event.detail.value"`，因此组件侧需要：

* 接收 `value`（props）
* 触发 `input` 事件，并在 `detail.value` 中带回新值

```mermaid
flowchart LR
  Page[页面 state.amount] --> WXML[WXML: v-model 编译产物<br/>value={{state.amount}}]
  WXML --> Comp[自定义组件 props.value]
  Comp -->|triggerEvent('input', { value: next })| WXML
  WXML -->|bind:input 赋值表达式| Page
```

```vue
<!-- components/stepper/index.vue -->
<script setup lang="ts">
import { computed } from 'wevu'

const props = withDefaults(defineProps<{
  value?: number
  min?: number
  max?: number
}>(), {
  value: 0,
  min: 0,
  max: 10,
})

const emit = defineEmits<{
  (e: 'input', detail: { value: number }): void
}>()

defineComponentJson(() => ({
  component: true,
}))

const value = computed(() => props.value ?? 0)

function setValue(next: number) {
  emit('input', { value: next })
}

function inc() {
  if (value.value >= props.max) {
    return
  }
  setValue(value.value + 1)
}

function dec() {
  if (value.value <= props.min) {
    return
  }
  setValue(value.value - 1)
}
</script>

<template>
  <view class="stepper">
    <button @tap="dec">
      -
    </button>
    <text>{{ value }}</text>
    <button @tap="inc">
      +
    </button>
  </view>
</template>
```

使用（页面侧同样推荐用宏注入 `usingComponents`）：

```vue
<!-- pages/demo/index.vue -->
<script setup lang="ts">
import { reactive } from 'wevu'

definePageJson(() => ({
  usingComponents: {
    stepper: '/components/stepper/index',
  },
}))

const state = reactive({ amount: 1 })
</script>

<template>
  <stepper v-model="state.amount" :min="1" :max="5" />
</template>
```

更多实践可搭配仓库中的示例应用 `apps/wevu-*`（如 [wevu-comprehensive-demo](https://github.com/weapp-labs/weapp-vite/tree/main/apps/wevu-comprehensive-demo)、[wevu-runtime-demo](https://github.com/weapp-labs/weapp-vite/tree/main/apps/wevu-runtime-demo)、[wevu-vue-demo](https://github.com/weapp-labs/weapp-vite/tree/main/apps/wevu-vue-demo)）。

---

---
url: /guide/vue-sfc/troubleshoot.md
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/troubleshoot](/wevu/vue-sfc/troubleshoot)。

---

---
url: /wevu/vue-sfc/troubleshoot.md
---

# Vue SFC：调试与排错

## 最佳实践与限制

* 使用小程序组件/事件名：模板中的 `<view>`、`<button>`、`@tap` 等会在构建时转为原生写法。
* 避免 DOM 专属 API（`window/document`）；需用小程序 API（如 `wx.request`）。
* 样式选择器遵循小程序规范；`scoped` 样式会编译为符合小程序前缀的选择器。
* 若使用 `<slot>`，保持与小程序组件 slot 语义一致。
* 需要分享/朋友圈/收藏能力时，请按微信官方实现页面回调（`onShareAppMessage/onShareTimeline/onAddToFavorites`），并在需要时调用 `wx.showShareMenu()` 配置菜单项。

## 常见问题

### 1) 组件不渲染

优先按这个顺序检查：

* `usingComponents` 是否声明、路径是否正确（注意分包路径与大小写）。
* `component.json` 是否包含 `component: true`（组件必须是组件）。
* 开发者工具控制台是否提示 “usingComponents not found / component path not found / wxml parse error”。

```mermaid
flowchart TB
  A[组件不渲染] --> B{usingComponents 是否正确？}
  B -->|否| B1[修正路径/分包路径/大小写]
  B -->|是| C{component: true 是否存在？}
  C -->|否| C1[用 <json> 或 defineComponentJson 写入 component: true]
  C -->|是| D{控制台是否报错？}
  D -->|是| D1[按错误信息定位：wxml parse / path not found]
  D -->|否| E[进一步排查：模板/条件渲染/样式隐藏]
```

### 2) 状态不更新

* 确认响应式 API 来自 `wevu`（不是 `vue`）。
* 确认你更新的是响应式值（例如 `ref.value`）。
* 确认模板确实依赖了该状态（否则更新不会反映到 UI）。

### 3) hooks 不触发（滚动/分享/触底等）

* hooks 必须在 `setup()` **同步阶段**注册（`await` 后注册会报错或失效）。
* 分享/朋友圈/收藏等能力是否满足微信官方触发条件（菜单项、`open-type="share"`、`wx.showShareMenu()` 等）。

### 4) v-model 行为不符合 Vue 预期

回到“模板与指令”章节的 `v-model` 限制：它是小程序“赋值表达式事件”，不是 Vue 的完整 v-model 语义（参数/修饰符等）。

更强的双向绑定方案请参考：`/wevu/runtime` 的 `bindModel` 部分。

---

---
url: /guide/vue-sfc/config.md
---

# 已迁移

本页已迁移至 [/wevu/vue-sfc/config](/wevu/vue-sfc/config)。

---

---
url: /wevu/vue-sfc/config.md
---

# Vue SFC：配置与宏

## usingComponents：为什么脚本里不要 import

小程序组件的注册是 **JSON 声明式** 的：只认 `usingComponents`。因此在 SFC 里推荐：

* 在 `<json>` 或 `definePageJson/defineComponentJson` 里声明 `usingComponents`
* 模板里直接写组件标签（例如 `<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`。
:::

## 配置块模式对比

| 写法                  | 作用                | 适合场景                 |
| --------------------- | ------------------- | ------------------------ |
| `<json>`              | JSONC + Schema 提示 | 静态配置（默认可写注释） |
| `<json lang="jsonc">` | JSONC + Schema 提示 | 静态配置（显式标注）     |
| `<json lang="ts/js">` | TS/JS + 类型检查    | 动态/异步配置            |
| Script Setup 宏       | build-time 注入配置 | 覆盖/拼装页面与组件配置  |

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

特点与限制：

* 必须是 `<script setup>` 的**顶层语句**，且**只能传 1 个参数**。
* 同一个 SFC 内只能使用一种宏（例如只能用 `definePageJson`），但可以调用多次；多次返回会 **deep merge**（后者覆盖前者）。
* 支持 `object` / `() => object` / `async () => object`（也支持返回 `Promise`）。
* 宏只在 **构建期（Node.js）** 执行：请保持幂等，避免依赖小程序运行时 API；推荐只做本地 import、常量拼装与轻量计算。
* 合并优先级最高：会覆盖 `<json>` 块以及自动 `usingComponents` 的结果。

> TypeScript 提示：确保项目的 `vite-env.d.ts` 包含 `/// <reference types="weapp-vite/client" />`（脚手架默认已配置），这样 IDE 才能识别这些全局宏。

组件示例：

```vue
<script setup lang="ts">
defineComponentJson(() => ({
  styleIsolation: 'isolated',
  options: { virtualHost: true },
  externalClasses: ['macro-card-class'],
}))
</script>
```

页面示例：

```vue
<script setup lang="ts">
import { macroDemoNavBg, macroDemoNavTitle } from './macro.config'

definePageJson(() => ({
  navigationBarTitleText: macroDemoNavTitle,
  navigationBarBackgroundColor: macroDemoNavBg,
  enablePullDownRefresh: true,
}))
</script>
```

---

---
url: /integration/vue-mini.md
---
# Vue-mini 集成

## vue-mini 介绍

Vue Mini 是一个基于 Vue 3 的小程序框架，你可以用 Vue 3 的响应式和组合式 API 来开发小程序。

文档：<https://vuemini.org/>

## 集成

在 `weapp-vite` 中接入 `vue-mini` 的步骤很简单：安装依赖后按官方文档使用即可。

```sh
pnpm i @vue-mini/core
```

然后你就可以跟随文档，使用 `vue-mini` 的所有特性了！

## 模板地址

这是一个 `vue-mini` + `weapp-vite` + `weapp-tailwindcss` 已配置好的模板：

<https://github.com/icebreaker-template/vue-mini-tailwindcss-template>

---

---
url: /packages/weapp-ide-cli.md
---
# weapp-ide-cli

`weapp-ide-cli` 是对微信开发者工具官方命令行的增强封装：保留官方命令语义，同时补齐路径、配置和非交互体验。

## 何时使用

* 在本地脚本中执行 `open / preview / upload`
* 在 CI 环境自动上传构建产物
* 需要跨平台（macOS/Windows/Linux 社区版）统一命令入口

## 前置条件

在微信开发者工具中打开：`设置 -> 安全设置 -> 服务端口`。

## 安装

```bash
pnpm add -g weapp-ide-cli
# 或 npm install -g weapp-ide-cli
```

## 常用命令

```bash
# 当前目录作为项目目录
weapp open -p

# 指定项目目录
weapp open --project ./dist/dev/mp-weixin

# 预览二维码
weapp preview --project ./dist/dev/mp-weixin

# 上传
weapp upload --project ./dist/build/mp-weixin --version 1.0.0
```

`weapp` 与 `weapp-ide-cli` 是等价入口。

## 支付宝 minidev 转发

```bash
weapp alipay login
weapp alipay preview --project ./dist/mp-alipay
```

也支持：

```bash
weapp open --platform alipay -p ./dist/dev/mp-alipay
```

## CI 建议

* 显式加 `--non-interactive`，避免登录失效时挂起
* 结合 `--login-retry=never|once|always` 控制失败策略
* 使用 `--qr-output` / `--result-output` 收集产物日志

---

---
url: /blog/release4.md
---
# 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/release6.md
---
# weapp-vite@6：原生模式之外，多一种 Vue 选择

## 前言

还记得在 weapp-vite 4.0 的发布文章里，我写过这样的话：

> **不适用场景**：需要使用 `Vue`/`React` 等前端框架的写法，来取代小程序原生写法。

当时的想法很单纯：weapp-vite 的定位是「原生小程序的现代化构建工具」，保持零运行时，专注于 TypeScript、SCSS、HMR 这些开发体验的提升。

但社区的声音让我重新思考这个定位。

确实，市面上已经有不少支持 Vue 写小程序的方案：

* **Taro**：React/Vue 语法，跨端能力强大
* **uni-app**：Vue 语法，开箱即用
* **mpx**：美团出品，增强型小程序框架

但它们都有各自的"槽点"：运行时庞大、DSL 不标准、技术栈老旧、或者深度绑定特定生态。

**能不能做一个既保留原生模式优势，又提供 Vue 开发体验的工具？**

于是，weapp-vite@6 来了——**在原生模式之外，多一种 Vue 选择**。

## 背景故事：从零运行时到 Vue 支持

### 最初的定位

weapp-vite 最初的设计理念是做一个**零运行时**的原生小程序构建工具。用户用原生写法，weapp-vite 提供现代化的开发体验，保证打出来的包足够小、性能足够好。

这个定位满足了很多只需要开发微信小程序、追求极致性能的用户。

但我也在思考：能不能在不破坏原生模式的前提下，给用户一个 Vue 的选择？

### 市面上的选择

看看现有的方案，各有取舍：

* **Taro**：跨端能力很强，但代价是庞大的运行时代码。分包规划不好，主包容易爆表。而且语法是 React/Vue 的"变种"，学习成本不低。

* **uni-app**：上手简单，但专属的 DSL 和 `uni.xxx` API 是另一套新东西。和标准 Vue 生态貌合神离。

* **mpx**：美团出品，基于 Vue 2.7 + webpack。技术栈较老，而且响应式系统和标准 Vue 不完全一样。

### weapp-vite 的思路

weapp-vite@6 的思路是：**同一个工具，给你两种模式**。

* **原生模式**：零运行时，极致性能，适合追求包体积和性能的项目
* **Vue 模式**：完整的 Vue 3 开发体验，适合熟悉 Vue 的团队

两者可以在同一个项目中并存，你可以根据具体页面/组件的需求来选择。

### wevu 的诞生

转折点是在开发 `wevu` 时——一个专为小程序设计的 Vue 运行时。

`wevu` 保留了 Vue 3 的核心 API——`ref`、`computed`、`watch`、`onMounted` 等，但底层用小程序的 `setData` 做更新。给小程序装上了 Vue 的"大脑"，但骨子里还是小程序的"身体"。

更重要的是，**wevu 既可以在 weapp-vite 中配合 SFC 编译时使用，也可以单独作为纯运行时库使用**。

### 编译时 + 运行时

既然 `wevu` 运行时已经就绪，Vue SFC 编译支持就是顺水推舟的事了。

## 认识 wevu：Vue 3 风格的小程序运行时

**wevu** 是一个专为小程序设计的 Vue 3 风格运行时。它的核心设计理念是：**响应式系统与 Vue 3 同源，渲染层深度适配小程序**。

### 核心特点

* **100% 兼容 Vue 3 响应式 API**：`ref`、`reactive`、`computed`、`watch`、`watchEffect` 等
* **Vue 3 生命周期支持**：`onMounted`、`onUpdated`、`onUnmounted` 等，自动映射到小程序生命周期
* **快照 diff 优化**：最小化 `setData` 调用，只传递变更的数据路径
* **内置状态管理**：`defineStore`/`storeToRefs`，API 类似 Pinia
* **可独立使用**：既可以配合 weapp-vite 的 SFC 编译，也可以单独作为运行时库使用

### Vue 3 vs wevu：实现上的异同

虽然 wevu 的 API 设计与 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 内置 |

**相同点：响应式系统**

Vue 3 和 wevu 的响应式系统**完全相同**，都基于 `Proxy` + `effect` 实现：

```ts
// 这段代码在 Vue 3 和 wevu 中写法完全一致
import { computed, ref, watch } from 'wevu'  // Vue 3 同名 API

const count = ref(0)
const doubled = computed(() => count.value * 2)

watch(count, val => console.log(val))
```

**不同点：渲染机制**

Vue 3 使用 Virtual DOM Diff，然后调用 DOM API 更新视图：

```
状态变化 → effect 触发 → 组件更新 → VNode Diff → DOM 操作
```

wevu 使用快照 Diff，然后调用小程序的 `setData`：

```
状态变化 → effect 触发 → 快照 Diff → setData → 小程序渲染
```

wevu 的快照 Diff 直接对响应式数据对象做深度比较，计算出最小变更路径（如 `data.a.b[2]`），然后只传递这部分数据给 `setData`，避免全量更新。

### weapp-vite + wevu 的组合

* **weapp-vite**：负责**编译时**工作，把 Vue SFC 拆解、转换、生成小程序四件套
* **wevu**：负责**运行时**工作，提供响应式系统和生命周期

两者结合，你得到的是：

1. Vue 3 风格的开发体验（SFC + Composition API）
2. 小程序原生的运行性能
3. 可选的独立运行时使用（wevu 可单独安装）

最关键的设计决策是：**把 Vue SFC 支持直接内置到 `weapp-vite` 里**，而不是作为外部插件。

这意味着：

* 不需要安装 `@vitejs/plugin-vue`
* 不需要复杂的配置
* 只需要在 `vite.config.ts` 里加一个开关

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

export default defineConfig({
  plugins: [
    weappVite({
      vue: {
        enable: true, // 就这么简单！
      },
    }),
  ],
})
```

从现在起，weapp-vite 不再只是"原生小程序的现代化工具"，而是"**原生 + Vue**的双料选择"。

## 一处编写，四处生成

当你创建一个 `.vue` 文件时，weapp-vite 会悄悄地施展编译魔法：

```
MyComponent.vue
    ├─> MyComponent.js    // 脚本逻辑
    ├─> MyComponent.wxml  // 模板结构
    ├─> MyComponent.wxss  // 样式文件
    └─> MyComponent.json  // 组件配置
```

Vue 的 `<script>`、`<template>`、`<style>` 会被智能拆分并转换成小程序能理解的格式。整个过程就像是把 Vue 组件"翻译"成了小程序的方言。

**编译原理小剧场**：

1. **解析阶段**：使用 `vue/compiler-sfc` 把 SFC 拆成三块
2. **转换阶段**：Vue 指令 → 小程序指令（`v-if` → `wx:if`，`@click` → `bindtap`）
3. **生成阶段**：输出小程序四件套
4. **运行时**：配合 `wevu` 提供响应式能力

整个过程中，编译缓存机制确保只有修改过的文件才会重新编译——这就是 HMR 的基础。

## Vue 语法无缝转换

weapp-vite 的 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 用小程序的方式执行。

## 使用用例：从简单到复杂

### 用例 1：计数器——Vue 响应式的魔力

先来个最经典的例子，对比一下原生写法和 Vue 写法：

**原生小程序写法**：

```js
Page({
  data: {
    count: 0,
  },
  increment() {
    this.setData({
      count: this.data.count + 1, // 每次都要写 this.data 和 this.setData
    })
  },
})
```

**weapp-vite + Vue 写法**：

```html
<script setup>
import { ref } from 'wevu'

const count = ref(0)

function increment() {
  count.value++ // 就这？
}
</script>

<template>
  <view class="counter">
    <text>Count: {{ count }}</text>
    <button @tap="increment">+1</button>
  </view>
</template>
```

这区别，就像是骑自行车和开电动车——都能到目的地，但体验完全不同。

### 用例 2：computed 和 watch——复杂状态管理

```html
<script setup lang="ts">
import { computed, ref, watch } from 'wevu'

const count = ref(0)
const doubled = computed(() => count.value * 2)

// 监听变化
watch(count, (newValue, oldValue) => {
  console.log(`count changed: ${oldValue} -> ${newValue}`)
})

function increment() {
  count.value++
}
</script>

<template>
  <view class="counter">
    <text>Count: {{ count }}</text>
    <text>Doubled: {{ doubled }}</text>
    <button @tap="increment">+1</button>

    <view v-if="count > 5">
      <text>Count is greater than 5!</text>
    </view>
    <view v-else>
      <text>Count is 5 or less</text>
    </view>
  </view>
</template>
```

`computed` 自动计算，`watch` 自动监听，`v-if` 自动渲染。不用手动管理任何依赖关系。

### 用例 3：definePageJson——宏的魔法

weapp-vite 提供了三个独特的宏，让你在 `<script setup>` 里定义小程序配置：

```html
<script setup lang="ts">
import { ref } from 'wevu'

// 页面配置宏——直接生成页面 JSON
definePageJson({
  navigationBarTitleText: '首页',
  navigationBarBackgroundColor: '#4c6ef5',
  navigationBarTextStyle: 'white',
})

const count = ref(0)
</script>

<template>
  <view>{{ count }}</view>
</template>
```

**宏的原理**：编译时，`definePageJson` 的参数会被提取出来，合并到最终生成的 `.json` 文件中。这个过程发生在构建阶段，运行时零开销。

宏家族有三个成员：

* `defineAppJson`：在 `app.vue` 中定义全局配置
* `definePageJson`：在页面中定义页面配置
* `defineComponentJson`：在组件中定义组件配置

**为什么推荐使用宏而不是 `<json>` 块？**

1. **完整的 TypeScript 类型支持**：宏指令有完整的类型提示和校验
2. **共享 setup 作用域**：可以在宏的参数中引用 `<script setup>` 里定义的变量
3. **更好的开发体验**：IDE 自动补全、类型检查、重构支持

```html
<script setup lang="ts">
import { ref } from 'wevu'

// 可以引用 setup 作用域的变量！
const pageTitle = ref('动态标题')

definePageJson({
  navigationBarTitleText: pageTitle.value, // ✅ 类型安全
  // ...
})
</script>
```

相比之下，自定义 `<json>` 块虽然支持 JSONC 和 JS/TS 格式，但与 `<script setup>` 作用域隔离，无法共享变量，也缺乏类型支持。

### 用例 4：v-model——双向绑定

表单处理一直是小程序的痛点。原生写法需要手动监听 `input` 事件，然后 `setData`。Vue 的 `v-model` 让这一切变得简单：

```html
<script setup>
import { ref } from 'wevu'

const message = ref('Hello WeVU!')
const checked = ref(false)
const selected = ref('option1')
</script>

<template>
  <view class="form">
    <!-- 文本输入 -->
    <input v-model="message" placeholder="输入点什么...">

    <!-- 复选框 -->
    <checkbox v-model="checked">同意协议</checkbox>

    <!-- 单选框 -->
    <radio-group v-model="selected">
      <radio value="option1">选项 1</radio>
      <radio value="option2">选项 2</radio>
    </radio-group>

    <view>
      <text>message: {{ message }}</text>
      <text>checked: {{ checked }}</text>
      <text>selected: {{ selected }}</text>
    </view>
  </view>
</template>
```

`v-model` 会自动处理不同表单元素的双向绑定逻辑，无需手动写事件监听。

### 用例 5：组件通信——props 和 emits

```html
<!-- Parent.vue -->
<script setup>
import { ref } from 'wevu'
import Child from './Child.vue'

const parentMessage = ref('来自父组件的消息')

function handleChildEvent(data) {
  console.log('收到子组件事件:', data)
}
</script>

<template>
  <view>
    <Child
      :title="parentMessage"
      @child-event="handleChildEvent"
    />
  </view>
</template>

<!-- Child.vue -->
<script setup>
import { defineEmits, defineProps } from 'weapp-vite/runtime'

const props = defineProps<{
  title: string
}>()

const emit = defineEmits<{
  childEvent: [data: string]
}>()

function handleClick() {
  emit('childEvent', '来自子组件的数据')
}
</script>

<template>
  <view @tap="handleClick">
    <text>{{ title }}</text>
  </view>
</template>
```

完整的 TypeScript 支持，类型安全的组件通信。

### 用例 6：app.vue——应用级配置

`app.vue` 是 weapp-vite Vue 模式的入口文件，你可以在这里定义全局配置和应用生命周期：

```html
<script setup lang="ts">
import { onHide, onLaunch, onShow } from 'wevu'

defineAppJson({
  pages: [
    'pages/index/index',
    'pages/detail/detail',
  ],
  window: {
    navigationBarTitleText: 'Weapp-Vite + WeVU',
    navigationBarBackgroundColor: '#4c6ef5',
    navigationBarTextStyle: 'white',
  },
  style: 'v2',
  sitemapLocation: 'sitemap.json',
})

onLaunch(() => {
  console.log('App Launch')
})

onShow(() => {
  console.log('App Show')
})

onHide(() => {
  console.log('App Hide')
})
</script>

<style lang="scss">
@use 'tailwindcss/base';
@use 'tailwindcss/components';
@use 'tailwindcss/utilities';

page {
  color: #1c1c3c;
  background: #f6f7fb;
}
</style>
```

注意这里还支持 SCSS 和 TailwindCSS——现代化的开发体验，一个都不能少。

### 用例 7：自定义 `<json>` 块

除了用宏定义配置，weapp-vite 还支持 Vue SFC 的自定义块语法：

```html
<script setup>
const count = ref(0)
</script>

<template>
  <view>{{ count }}</view>
</template>

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

<!-- 小程序专属配置块 -->
<json>
{
  "navigationBarTitleText": "Vue 小程序",
  "navigationBarBackgroundColor": "#667eea",
  "navigationBarTextStyle": "white"
}
</json>
```

`<json>` 块的内容会直接合并到生成的 `.json` 文件中。这是 weapp-vite 支持的语法，但**不推荐使用**——推荐使用前面介绍的 `definePageJson` 等宏指令，因为它们有完整的 TypeScript 类型支持，并且可以共享 `<script setup>` 作用域的变量。

### 用例 8：插槽 Slots

插槽是组件复用的重要机制，weapp-vite 支持完整的插槽语法：

```html
<!-- Card.vue -->
<script setup>
defineProps<{
  title: string
}>()
</script>

<template>
  <view class="card">
    <view class="card-header">{{ title }}</view>

    <!-- 默认插槽 -->
    <view class="card-body">
      <slot />
    </view>

    <!-- 具名插槽 -->
    <view class="card-footer">
      <slot name="footer">
        <text>默认底部内容</text>
      </slot>
    </view>
  </view>
</template>
```

```html
<!-- 使用 Card 组件 -->
<script setup>
import Card from './Card.vue'
</script>

<template>
  <Card title="卡片标题">
    <!-- 默认插槽内容 -->
    <view>这是卡片主体内容</view>

    <!-- 具名插槽内容 -->
    <template #footer>
      <view>自定义底部</view>
    </template>
  </Card>
</template>
```

编译后会转换为小程序的 `<slot>` 语法：

* 默认插槽 `<slot></slot>` → `<slot></slot>`
* 具名插槽 `<slot name="footer"></slot>` → `<slot name="footer"></slot>`
* 插槽内容 `<template #footer>` → `<template slot="footer">`

## 适用场景

### weapp-vite 的独特优势：双模式并存

与其他框架不同，weapp-vite@6 支持在同一个项目中同时使用原生模式和 Vue 模式。你可以：

* 核心页面用原生模式，保证极致性能
* 业务页面用 Vue 模式，提升开发效率
* 逐步迁移，不需要一次性重写

### 适合 Vue 模式的场景：

* 你熟悉 Vue 3，想用 Vue 语法写小程序
* 团队有 Vue 技术栈，想复用到小程序
* 追求更优雅的响应式和组件化体验
* 想要热重载、TypeScript 支持等现代开发体验
* 希望 Vue 代码能尽量复用到 Web 项目

### 适合原生模式的场景：

* 需要极致性能，不想任何运行时开销
* 已有大量原生小程序代码，不想大改
* 团队熟悉小程序原生 API
* 对包体积有严格要求

### 什么时候选其他框架？

* **Taro**：如果你真的需要同时支持微信、支付宝、百度、字节等所有平台的小程序，甚至还要编译成 H5、RN，Taro 确实是唯一选择。但大部分项目真的需要跨这么多端吗？

* **uni-app**：如果你需要一个"开箱即用"的一站式解决方案，而且习惯了 DCloud 的生态（HBuilderX、uniCloud 等），uni-app 适合你。但它的专属 DSL 和标准 Vue 有差异。

* **mpx**：基于 Vue 2.7 + webpack，技术栈较老。如果你已经在用美团的小程序生态，可以考虑，否则不建议新项目使用。

**一句话总结**：weapp-vite@6 的独特之处在于——原生 + Vue 双模式并存，同一个工具，给你两种选择。

## 快速体验

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

## 技术细节（给好奇的同学）

weapp-vite 的 Vue 支持不是简单的黑盒，而是精心设计的编译管道：

### 编译流程

```
.vue 文件
  ↓
vue/compiler-sfc 解析
  ↓
┌─────────┬─────────┬─────────┐
│ <script>│<template>│<style>  │
└────┬────┴────┬────┴────┬────┘
     │         │         │
     ↓         ↓         ↓
  处理宏    指令转换   样式转换
     │         │         │
     └─────────┴─────────┘
               ↓
         生成四件套
         .js .wxml .wxss .json
```

### 支持的功能清单

* **核心指令**：v-if、v-else、v-for、v-show、v-model
* **事件绑定**：@click、@tap、自定义事件
* **属性绑定**：:class、:style、动态属性
* **样式处理**：CSS Modules、预处理器（SCSS/Less）
* **组件通信**：props、emits、provide/inject、slots
* **生命周期**：onMounted、onUpdated、onUnmounted 等
* **响应式 API**：ref、computed、watch、watchEffect
* **TypeScript**：完整支持，包括泛型组件

### 测试覆盖

* **73+ 测试用例** 全部通过
* **85%+ 代码覆盖率**
* 测试分类：基础模板编译、样式处理、高级特性、E2E 集成测试

## 最后

weapp-vite@6 的 Vue SFC 支持建立在：

* `vue/compiler-sfc` 的解析能力
* `wevu` 运行时的精心设计
* 社区对更好开发体验的需求反馈

感谢每一位提出建议、反馈 bug、贡献代码的同学。

weapp-vite@6 把选择权交给你：

* 需要极致性能？用原生模式
* 需要 Vue 开发体验？用 Vue 模式
* wevu 也可以单独作为纯运行时库使用

***

如果 weapp-vite 帮到了你，欢迎给项目点个 [Star](https://github.com/weapp-vite/weapp-vite)！

Happy Coding! 🚀

---

---
url: /guide/web-compat-matrix.md
---

# Web 兼容矩阵 experimental {#web-compat-matrix}

本文用于说明 `weapp-vite` 在 Web 运行时（`@weapp-vite/web`）下的能力边界。
状态含义如下：

* `supported`：已实现且有基础测试覆盖。
* `partial`：可用但有明显限制或降级行为。
* `unsupported`：当前未实现，不应依赖。

> \[!WARNING]
> Web 运行时仍处于实验阶段（experimental），用于预览/调试，不替代开发者工具与真机行为。

## 模板语法矩阵

| 能力                                | 状态          | 说明                                                              |
| ----------------------------------- | ------------- | ----------------------------------------------------------------- |
| `{{}}` 插值表达式                   | `supported`   | 支持文本与属性表达式。                                            |
| `wx:if / wx:elif / wx:else`         | `supported`   | 支持条件分支链路。                                                |
| `wx:for / wx:key`                   | `supported`   | 支持列表渲染与 key 生成。                                         |
| `<template name>` + `<template is>` | `supported`   | 支持模板注册与调用。                                              |
| `<import>` / `<wx-import>`          | `supported`   | 支持模板导入，缺失时告警。                                        |
| `<include>` / `<wx-include>`        | `supported`   | 支持模板包含，缺失时告警。                                        |
| `<wxs>`（内联与 src）               | `partial`     | 支持基础执行与 `require`，仅允许相对/绝对路径。                   |
| `<slot>`                            | `partial`     | 保留为原生 `slot` 标签；高级插槽语义不保证与小程序完全一致。      |
| 事件前缀 `bind/catch/capture`       | `partial`     | 采用表驱动映射并支持 `catch/capture` 标记；事件别名仍是高频子集。 |
| 复杂模板能力（如 `wx:model` 等）    | `unsupported` | 当前未进入 Web 编译主路径。                                       |

## 组件选项矩阵

| 能力                                             | 状态          | 说明                                                             |
| ------------------------------------------------ | ------------- | ---------------------------------------------------------------- |
| `properties`（含 `type/value/observer`）         | `supported`   | 支持属性反射、类型收敛与 observer。                              |
| `data` / `setData`                               | `supported`   | 支持基础状态更新与重渲染。                                       |
| `methods` / `triggerEvent`                       | `supported`   | 支持事件触发与组件方法调用。                                     |
| `lifetimes`（`created/attached/ready/detached`） | `supported`   | 支持基础生命周期。                                               |
| `pageLifetimes`（`show/hide`）                   | `partial`     | 在页面显示/隐藏时分发到组件；`resize` 依赖浏览器环境。           |
| `behaviors`（递归合并）                          | `supported`   | 支持递归合并 `data/properties/methods/lifetimes/pageLifetimes`。 |
| `observerInit`                                   | `supported`   | 可配置初始化阶段 observer 触发策略。                             |
| `relations` / `externalClasses` 等               | `unsupported` | 当前未在 runtime `ComponentOptions` 中实现。                     |

## `wx` API 矩阵（Web bridge）

| API                                                                                                      | 状态          | 说明                                                                                                    |
| -------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| `wx.navigateTo`                                                                                          | `supported`   | 支持基础页面栈推进。                                                                                    |
| `wx.redirectTo`                                                                                          | `supported`   | 支持替换当前页面。                                                                                      |
| `wx.reLaunch`                                                                                            | `supported`   | 支持重建路由栈。                                                                                        |
| `wx.switchTab`                                                                                           | `partial`     | 当前行为等价于 `redirectTo`。                                                                           |
| `wx.showTabBar` / `wx.hideTabBar`                                                                        | `partial`     | 当前为 no-op 成功桥接，用于兼容调用链，不改变实际 Web 布局。                                            |
| `wx.loadSubPackage` / `wx.preloadSubpackage`                                                             | `partial`     | 当前提供 no-op 成功桥接，主要用于兼容分包加载调用链，不执行真实下载与预加载流程。                       |
| `wx.navigateBack`                                                                                        | `supported`   | 支持 `delta` 回退。                                                                                     |
| `wx.setNavigationBarTitle`                                                                               | `partial`     | 依赖默认导航栏组件存在。                                                                                |
| `wx.setNavigationBarColor`                                                                               | `partial`     | 依赖默认导航栏组件存在。                                                                                |
| `wx.setBackgroundColor` / `wx.setBackgroundTextStyle`                                                    | `partial`     | 提供页面背景与文本样式的近似桥接，基于 DOM 样式设置，不等价小程序原生渲染语义。                         |
| `wx.showNavigationBarLoading` / `hideNavigationBarLoading`                                               | `partial`     | 依赖默认导航栏组件存在。                                                                                |
| `wx.showLoading` / `wx.hideLoading`                                                                      | `partial`     | 提供轻量 DOM loading 层，视觉行为为近似实现。                                                           |
| `wx.nextTick`                                                                                            | `partial`     | 基于微任务队列调度回调，时序近似小程序行为。                                                            |
| `wx.showModal`                                                                                           | `partial`     | 基于浏览器 `confirm/alert`，`confirmText/cancelText` 不生效。                                           |
| `wx.showActionSheet`                                                                                     | `partial`     | 通过浏览器 `prompt` 或预设索引桥接选择结果，交互样式与真机 ActionSheet 不一致。                         |
| `wx.showToast`                                                                                           | `partial`     | 提供轻量 DOM toast，样式与真机不完全一致。                                                              |
| `wx.startPullDownRefresh` / `wx.stopPullDownRefresh`                                                     | `partial`     | Web 侧均作为 no-op 成功桥接，便于兼容下拉刷新调用链。                                                   |
| `wx.hideKeyboard`                                                                                        | `partial`     | 通过 `blur` 当前聚焦输入元素近似桥接收起键盘能力，行为受浏览器焦点模型限制。                            |
| `wx.pageScrollTo`                                                                                        | `partial`     | 支持 `scrollTop/duration` 的基础滚动，`selector` 等高级能力未覆盖。                                     |
| `wx.createCanvasContext`                                                                                 | `partial`     | 基于浏览器 2D Canvas 上下文桥接高频绘制命令，绘图状态与高级 API 未全量覆盖。                            |
| `wx.createVideoContext`                                                                                  | `partial`     | 基于页面 video 元素提供播放控制桥接（`play/pause/seek` 等），不包含原生播放器完整语义。                 |
| `wx.createWorker`                                                                                        | `partial`     | 基于浏览器 Worker 桥接消息收发与错误监听（`postMessage/onMessage/onError`），线程模型与真机不完全一致。 |
| `wx.createSelectorQuery`                                                                                 | `partial`     | 支持 `in/select/selectAll/selectViewport` 与 `boundingClientRect/scrollOffset/fields/node` 高频子集。   |
| `wx.setClipboardData` / `wx.getClipboardData`                                                            | `partial`     | 依赖浏览器剪贴板权限；失败时会回调 `fail`。                                                             |
| `wx.request`                                                                                             | `partial`     | 基于 `fetch` 桥接，支持常见 JSON/text 场景；上传下载与高级拦截能力未覆盖。                              |
| `wx.uploadFile`                                                                                          | `partial`     | 基于 `fetch + FormData` 桥接文件上传，支持基础表单字段；上传任务进度与中断控制语义未覆盖。              |
| `wx.downloadFile`                                                                                        | `partial`     | 基于 `fetch` + `Blob URL` 桥接，返回临时 URL；文件系统语义与真机不一致。                                |
| `wx.openDocument`                                                                                        | `partial`     | 支持 URL 或内存文件桥接到浏览器新窗口预览，文档菜单与内置查看器行为不等价。                             |
| `wx.chooseImage`                                                                                         | `partial`     | 优先使用 `showOpenFilePicker`，降级到文件输入框选择；结果为浏览器临时 URL。                             |
| `wx.chooseMedia`                                                                                         | `partial`     | 基于文件选择器桥接图片/视频选择，结果为浏览器临时 URL，媒体元信息（时长/尺寸）当前为近似占位值。        |
| `wx.chooseVideo`                                                                                         | `partial`     | 基于媒体文件选择桥接视频选择，返回浏览器临时 URL；时长/尺寸字段当前为近似占位值。                       |
| `wx.compressImage`                                                                                       | `partial`     | 优先基于 Canvas 执行近似压缩，失败或能力缺失时回退原图路径；压缩质量与真机语义不完全一致。              |
| `wx.compressVideo`                                                                                       | `partial`     | 当前提供 no-op 兼容桥接（默认返回原视频路径），可通过预设结果注入压缩后的临时路径用于调试流程。         |
| `wx.getImageInfo`                                                                                        | `partial`     | 基于浏览器 `Image` 对象读取图片宽高与类型；EXIF 与方向能力为近似值。                                    |
| `wx.getVideoInfo`                                                                                        | `partial`     | 优先读取运行时预设，降级尝试浏览器 video 元信息；文件大小、帧率、码率等字段当前为近似值。               |
| `wx.chooseMessageFile`                                                                                   | `partial`     | 基于文件选择器桥接消息文件选择，返回浏览器临时文件信息；会话/聊天上下文语义与真机不同。                 |
| `wx.chooseFile`                                                                                          | `partial`     | 基于文件选择器桥接通用文件选择，支持 `extension` 过滤；返回浏览器临时文件信息。                         |
| `wx.previewImage`                                                                                        | `partial`     | 使用浏览器 `window.open` 预览图片，依赖浏览器弹窗策略。                                                 |
| `wx.previewMedia`                                                                                        | `partial`     | 基于浏览器新窗口预览媒体 URL，不提供小程序原生媒体预览器的手势、切换与播放控制能力。                    |
| `wx.openVideoEditor`                                                                                     | `partial`     | 当前提供 API 级兼容桥接（默认返回原视频路径），可通过预设结果注入编辑后路径用于调试流程。               |
| `wx.saveImageToPhotosAlbum`                                                                              | `partial`     | 通过浏览器下载行为近似桥接保存流程，不具备系统相册写入与权限弹窗等真机语义。                            |
| `wx.saveVideoToPhotosAlbum`                                                                              | `partial`     | 通过浏览器下载行为近似桥接保存流程，不具备系统相册写入与权限弹窗等真机语义。                            |
| `wx.saveFile`                                                                                            | `partial`     | 将临时文件路径近似持久化到 Web 内存文件系统并返回 `savedFilePath`，不等价真机文件沙箱语义。             |
| `wx.saveFileToDisk`                                                                                      | `partial`     | 通过浏览器下载行为近似桥接保存文件流程，不具备小程序容器内的系统文件管理语义。                          |
| `wx.login` / `wx.checkSession` / `wx.getAccountInfoSync`                                                 | `partial`     | 提供 Web 环境下的登录态占位桥接与会话校验，不等价真实小程序登录会话。                                   |
| `wx.getUserInfo` / `wx.getUserProfile`                                                                   | `partial`     | 提供用户信息读取与授权确认占位桥接，可通过预设结果注入用户资料，不触发系统级授权弹窗。                  |
| `wx.showShareMenu` / `wx.updateShareMenu`                                                                | `partial`     | 提供 API 级成功回调桥接，不覆盖平台级分享能力差异。                                                     |
| `wx.getExtConfigSync` / `wx.getExtConfig`                                                                | `partial`     | 返回 Web runtime 注入的扩展配置快照（默认空对象）。                                                     |
| `wx.getUpdateManager` / `wx.getLogManager`                                                               | `partial`     | 返回 Web 侧更新/日志桥接对象：更新流程可通过预设状态驱动，日志输出映射到浏览器 console。                |
| `wx.cloud.init` / `wx.cloud.callFunction`                                                                | `partial`     | 提供云能力初始化与云函数调用占位桥接，返回 mock 结果用于流程调试，不连接真实云环境。                    |
| `wx.reportAnalytics`                                                                                     | `partial`     | 在运行时内存中记录事件用于调试，不会真实上报到微信数据分析后台。                                        |
| `wx.navigateToMiniProgram` / `wx.exitMiniProgram`                                                        | `partial`     | 提供 API 级桥接用于流程调试，不执行真实小程序容器跳转/退出。                                            |
| `wx.openCustomerServiceChat`                                                                             | `partial`     | 可选地通过浏览器打开客服链接，企业微信会话能力不等价。                                                  |
| `wx.makePhoneCall`                                                                                       | `partial`     | 通过浏览器 `tel:` 链接桥接拨号流程，受设备与浏览器支持限制。                                            |
| `wx.chooseAddress`                                                                                       | `partial`     | 支持通过运行时预设或 `prompt` 输入桥接收货地址选择，不包含小程序原生地址簿与用户授权弹窗能力。          |
| `wx.chooseLocation`                                                                                      | `partial`     | 支持通过预设值或 `prompt` 输入经纬度完成桥接，不包含地图选点 UI 与 POI 选择能力。                       |
| `wx.openLocation`                                                                                        | `partial`     | 通过地图 URL 跳转近似桥接定位查看能力，不等价微信内置地图页面行为。                                     |
| `wx.requestPayment`                                                                                      | `partial`     | 仅提供成功回调级占位桥接，不涉及真实支付签名与交易流程。                                                |
| `wx.requestSubscribeMessage`                                                                             | `partial`     | 提供订阅消息授权结果占位桥接，可通过预设值控制模板消息确认结果，不触发平台级订阅弹窗。                  |
| `wx.createRewardedVideoAd` / `wx.createInterstitialAd`                                                   | `partial`     | 提供广告对象生命周期桥接（`load/show/onError/onClose`），不触发真实广告网络与平台策略。                 |
| `wx.createVKSession`                                                                                     | `partial`     | 提供 VKSession 生命周期占位桥接（`start/stop/destroy/on/off`），不包含真实 VisionKit 推理能力。         |
| `wx.getNetworkType` / `wx.onNetworkStatusChange` / `wx.offNetworkStatusChange`                           | `partial`     | 基于 `navigator.onLine` 与浏览器网络事件，网络类型为近似值。                                            |
| `wx.scanCode`                                                                                            | `partial`     | 提供基于输入/预设结果的占位扫码桥接，用于流程调试，不等价真实摄像头扫码能力。                           |
| `wx.getLocation`                                                                                         | `partial`     | 基于浏览器 Geolocation API 桥接，坐标与精度字段受浏览器权限策略影响。                                   |
| `wx.getFuzzyLocation`                                                                                    | `partial`     | 优先读取运行时预设并降级到定位结果模糊化桥接（经纬度保留两位小数），精度字段为近似值。                  |
| `wx.vibrateShort`                                                                                        | `partial`     | 通过浏览器 `navigator.vibrate` 触发短振动，实际效果受设备与权限限制。                                   |
| `wx.getBatteryInfo` / `wx.getBatteryInfoSync`                                                            | `partial`     | 优先读取浏览器 Battery API，缺失时回退到缓存近似值。                                                    |
| `wx.getFileSystemManager`                                                                                | `partial`     | 提供基于内存的文件读写桥接（`writeFile/readFile` 及 sync 版本），用于开发调试，不等价真机沙箱文件系统。 |
| `wx.setStorage` / `getStorage` / `removeStorage` / `clearStorage` / `getStorageInfo`                     | `partial`     | 基于内存 + `localStorage` 前缀桥接；与真机容量和隔离策略不完全一致。                                    |
| `wx.setStorageSync` / `getStorageSync` / `removeStorageSync` / `clearStorageSync` / `getStorageInfoSync` | `partial`     | 提供同步桥接，缺失 key 时 `getStorageSync` 返回空字符串。                                               |
| `wx.getSystemInfo` / `wx.getSystemInfoSync` / `wx.getWindowInfo`                                         | `partial`     | 基于浏览器环境推断，字段为近似值。                                                                      |
| `wx.onWindowResize` / `wx.offWindowResize`                                                               | `partial`     | 基于浏览器 `resize` 事件桥接窗口尺寸变化回调，触发时序与真机可能有差异。                                |
| `wx.getDeviceInfo` / `wx.getSystemSetting` / `wx.getAppAuthorizeSetting`                                 | `partial`     | 返回浏览器可推断字段与默认授权状态（多数字段为近似/占位值）。                                           |
| `wx.getSetting` / `wx.authorize` / `wx.openSetting`                                                      | `partial`     | 提供基于运行时内存状态的权限桥接，支持常见 scope 调试，不会触发系统级授权弹窗。                         |
| `wx.openAppAuthorizeSetting`                                                                             | `partial`     | 提供应用级授权设置结果桥接，可通过预设状态注入授权结果，不触发系统级授权设置页。                        |
| `wx.getAppBaseInfo`                                                                                      | `partial`     | 提供浏览器环境下的基础信息近似值（语言、主题、平台等）。                                                |
| `wx.getMenuButtonBoundingClientRect`                                                                     | `partial`     | 返回基于窗口尺寸的启发式胶囊按钮区域，不保证与真机一致。                                                |
| `wx.getLaunchOptionsSync` / `wx.getEnterOptionsSync`                                                     | `partial`     | 返回基于当前 Web runtime 路由推断的启动参数快照。                                                       |
| `wx.canIUse`                                                                                             | `partial`     | 支持 API 级能力探测（`wx.xxx`）；复杂组件/样式规则探测未覆盖。                                          |
| `getCurrentPages` / `getApp`                                                                             | `supported`   | 提供基础桥接能力。                                                                                      |
| 其他常见 API（多媒体高级能力等）                                                                         | `unsupported` | 尚未内置桥接，需业务层自行兼容。                                                                        |

## 已知限制

1. Web 侧表达式与 WXS 执行依赖动态求值机制，行为与小程序引擎存在差异。
   如需更保守或更严格的行为，可通过 `weapp.web.pluginOptions.runtime.executionMode` 调整为 `safe` 或 `strict`。
2. 事件映射与组件标签映射优先覆盖高频场景，未承诺全量等价。
3. `analyze --platform h5` 目前仅支持 Web 静态配置分析（`weapp.web` 与 `executionMode`），不包含分包体积、源码映射和仪表盘能力。
4. 运行时告警已支持 `runtime.warnings.level` 与 `runtime.warnings.dedupe`，但当前可观测信息仍以控制台输出为主。

## 建议用法

1. 将 Web 运行时作为“开发期预览与调试层”，不要直接等价真机验收。
2. 新增 Web 能力时，同步更新本矩阵，并补齐单测/E2E 用例。
3. 需要查看 Web 侧静态分析时，可执行 `weapp-vite analyze --platform h5 --json`。
4. 若业务依赖 `unsupported` 能力，建议在业务侧提供平台分支与降级策略。

---

---
url: /config/web.md
---
# Web 运行时配置 experimental {#web-config}

`weapp-vite` 可选集成浏览器端运行时（`@weapp-vite/web`），用于 Web 预览/调试。

\[\[toc]]

> \[!TIP]
> Web 端能力边界请配合阅读：[Web 兼容矩阵](/guide/web-compat-matrix)。

> \[!WARNING]
> `weapp.web` 仍处于实验阶段（experimental）。当前建议用于开发期预览与调试，不建议作为生产验收的唯一依据。
> 若需查看 Web 侧配置解析结果，可执行 `weapp-vite analyze --platform h5 --json`（当前仅静态分析，非包体分析）。

## `weapp.web` {#weapp-web}

* **类型**：
  ```ts
  {
    enable?: boolean
    root?: string
    srcDir?: string
    outDir?: string
    pluginOptions?: Partial<Omit<WeappWebPluginOptions, 'srcDir'>>
    vite?: InlineConfig
  }
  ```
* **默认值**：不开启（未配置 `weapp.web` 时不生效）。

### 示例

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

export default defineConfig({
  weapp: {
    web: {
      enable: true,
      root: '.',
      srcDir: 'src',
      outDir: 'dist/web',
      pluginOptions: {
        wxss: {
          designWidth: 750,
        },
        form: {
          preventDefault: true,
        },
        runtime: {
          executionMode: 'safe',
          warnings: {
            level: 'warn',
            dedupe: true,
          },
        },
      },
      vite: {
        server: { host: true },
      },
    },
  },
})
```

字段说明：

* `enable`：默认启用（当 `weapp.web` 存在且 `enable !== false` 时生效）。
* `root`：Web 项目根目录（`index.html` 所在目录），默认项目根目录。
* `srcDir`：小程序源码目录（相对于 `root`），默认与 `weapp.srcRoot` 保持一致。
* `outDir`：Web 构建输出目录（相对 `root`），默认 `dist/web`。
* `pluginOptions`：透传给 `weappWebPlugin` 的额外参数。当前可用字段主要包括：
  * `wxss`：WXSS 转换参数（如 `designWidth`、`rpxVar`）。
  * `form`：Web 端表单行为配置（如 `preventDefault`）。
  * `runtime.executionMode`：运行时执行策略（`compat`/`safe`/`strict`）：
    * `compat`（默认）：保持历史行为。
    * `safe`：表达式与 WXS 错误降级为告警并返回空值。
    * `strict`：表达式与 WXS 错误直接抛出，便于开发期快速定位。
  * `runtime.warnings`：运行时告警策略：
    * `level`：`warn`（默认）/`error`/`off`，分别对应 `console.warn`、`console.error`、关闭告警输出。
    * `dedupe`：默认 `true`，同一告警 key 仅输出一次。
  * `srcDir` 由 `weapp.web.srcDir` 自动注入，此处无需手动传入。
* `vite`：额外合并到 Web 构建中的 Vite 内联配置。

> \[!NOTE]
> Web 运行时用于预览/调试，不替代开发者工具与真机行为。

---

---
url: /CHANGELOG.md
---
# 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/vue3-vs-wevu.md
---

# wevu vs Vue 3：核心差异与小程序适配

> 深入对比 wevu 与 Vue 3 的架构差异，以及 wevu 如何适配微信小程序

## 目录

1. [核心架构对比](#核心架构对比)
2. [小程序适配的关键部分](#小程序适配)
3. [生命周期映射](#生命周期映射)
4. [双向绑定适配](#双向绑定)
5. [渲染层对比](#渲染层对比)

***

## 核心架构对比

### 架构图对比

#### Vue 3 架构

```
┌─────────────────────────────────────────────────────────────┐
│                      Vue 3 Application                       │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐      ┌──────────────┐      ┌────────────┐ │
│  │  Component  │ ───> │ Reactive Sys │ ───> │ Renderer  │ │
│  │   (Setup)   │      │  (Proxy)     │      │  (VNode)   │ │
│  └─────────────┘      └──────────────┘      └────────────┘ │
│         │                    │                    │         │
│         │                    ▼                    ▼         │
│         │              ┌──────────┐         ┌─────────┐   │
│         │              │ Scheduler│         │ DOM API │   │
│         │              │(nextTick)│         │         │   │
│         │              └──────────┘         └─────────┘   │
│         │                                               │
└─────────────────────────────────────────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │    Virtual DOM Tree     │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │     DOM Diff Patch      │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │     Browser DOM         │
        └─────────────────────────┘
```

#### wevu 架构

```
┌─────────────────────────────────────────────────────────────┐
│                       wevu Application                       │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐      ┌──────────────┐      ┌────────────┐ │
│  │ Component/  │ ───> │ Reactive Sys │ ───> │ Diff Algo  │ │
│  │    Page     │      │  (Proxy)     │      │(Snapshots) │ │
│  └─────────────┘      └──────────────┘      └────────────┘ │
│         │                    │                    │         │
│         │                    ▼                    ▼         │
│         │              ┌──────────┐         ┌─────────┐   │
│         │              │ Scheduler│         │ Adapter │   │
│         │              │(nextTick)│         │(setData)│   │
│         │              └──────────┘         └─────────┘   │
│         │                                               │
└─────────────────────────────────────────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │    Data Snapshots       │
        │  (Plain JS Objects)     │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │   Diff Algorithm        │
        │  (Path-based Diff)      │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │  Mini-Program setData   │
        │  { 'a.b.c': value }     │
        └─────────────────────────┘
                    ↓
        ┌─────────────────────────┐
        │   WeChat Native View    │
        └─────────────────────────┘
```

### 关键差异表

| 层级           | Vue 3               | wevu                | 差异说明    |
| -------------- | ------------------- | ------------------- | ----------- |
| **响应式系统** | Proxy + effect      | Proxy + effect      | 相同        |
| **调度器**     | queueJob + nextTick | queueJob + nextTick | 相同        |
| **数据模型**   | Virtual DOM Tree    | Data Snapshots      | ❌ **不同** |
| **渲染算法**   | Virtual DOM Diff    | Snapshot Diff       | ❌ **不同** |
| **视图更新**   | DOM API (patch)     | setData (小程序)    | ❌ **不同** |
| **生命周期**   | Web 标准生命周期    | 小程序生命周期      | ❌ **不同** |

### 相同的部分

#### 1. 响应式系统（100% 相同）

```typescript
// Vue 3 和 wevu 都是这样实现的

class RefImpl<T> {
  get value(): T {
    trackEffects(this.dep) // 收集依赖
    return this._value
  }

  set value(newValue: T) {
    if (!Object.is(newValue, this._rawValue)) {
      this._value = convertToReactive(newValue)
      triggerEffects(this.dep) // 触发更新
    }
  }
}
```

结论：wevu 直接复用了 Vue 3 的响应式系统设计。

#### 2. 调度器（99% 相同）

```typescript
// Vue 3 和 wevu 的调度器实现几乎一样

const resolvedPromise = Promise.resolve()
const jobQueue = new Set<Job>()

export function queueJob(job: Job) {
  jobQueue.add(job)
  if (!isFlushing) {
    resolvedPromise.then(flushJobs) // 微任务执行
  }
}
```

**唯一区别**：Vue 3 的 job 主要是执行 Virtual DOM patch，wevu 的 job 是执行 diff + setData。

### 不同的部分

#### 1. 渲染层（完全不同）

**Vue 3 的渲染流程：**

```typescript
// 文件：packages/vue/runtime-core/src/renderer.ts

function patch(n1, n2) {
  // 虚拟 DOM diff
  if (n1.type !== n2.type) {
    // 替换整个节点
  }
  else {
    // 更新属性、子节点
    patchElement(n1, n2)
  }

  // 最终调用 DOM API
  hostInsert(el, parent, anchor)
  hostSetElementText(el, text)
}
```

**wevu 的渲染流程：**

```typescript
// 文件：packages/wevu/src/runtime/app.ts

function job() {
  // 1. 收集快照（纯 JS 对象）
  const snapshot = collectSnapshot()

  // 2. Diff 快照（不是 Virtual DOM）
  const diff = diffSnapshots(latestSnapshot, snapshot)

  // 3. 调用小程序 setData
  adapter.setData(diff) // { 'user.name': 'Bob' }
}
```

**关键差异：**

| 特性          | Vue 3            | wevu             |
| ------------- | ---------------- | ---------------- |
| **数据结构**  | Virtual DOM Tree | Plain JS Objects |
| **Diff 算法** | 树形结构 Diff    | 深度对象 Diff    |
| **输出**      | DOM 操作列表     | setData 路径对象 |
| **更新方式**  | DOM API          | setData          |

#### 2. 视图层 API（完全不同）

**Vue 3 的 DOM 操作：**

```typescript
// Vue 3 直接操作 DOM

hostPatchProp(
  el,
  key,
  value,
  isSVG,
  prevChildren
)

// 最终调用：
el.textContent = text
el.setAttribute(key, value)
el.addEventListener(key, handler)
```

**wevu 的 setData 操作：**

```typescript
// wevu 通过小程序 setData 更新

adapter.setData({
  'user.name': 'Bob',
  'items[0].done': true
})

// 最终调用小程序 API：
this.setData({
  'user.name': 'Bob',
  'items[0].done': true
})
```

***

## 小程序适配

### 适配层架构

```
┌─────────────────────────────────────────────────────────────┐
│                    wevu 适配层                               │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  1. 注册层 (register.ts)                               │  │
│  │     ├─ registerApp()        → App()                  │  │
│  │     └─ registerComponent()  → Component()            │  │
│  └──────────────────────────────────────────────────────┘  │
│                          ↓                                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  2. 运行时层 (app.ts)                                  │  │
│  │     ├─ mount()               → 创建 runtime           │  │
│  │     ├─ adapter.setData()      → 桥接到小程序          │  │
│  │     └─ effect + scheduler     → 响应式更新            │  │
│  └──────────────────────────────────────────────────────┘  │
│                          ↓                                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  3. Diff 层 (diff.ts)                                  │  │
│  │     ├─ toPlain()              → 响应式转普通对象       │  │
│  │     ├─ diffSnapshots()        → 计算差异              │  │
│  │     └─ assignNestedDiff()     → 生成 setData 路径    │  │
│  └──────────────────────────────────────────────────────┘  │
│                          ↓                                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  4. 双向绑定层 (bindModel.ts)                          │  │
│  │     ├─ bindModel()            → 创建 model 绑定       │  │
│  │     ├─ defaultParser()        → 解析小程序事件        │  │
│  │     └─ model()                → 生成小程序事件属性    │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                          ↓
        ┌─────────────────────────────────────────────┐
        │    微信小程序原生 API                        │
        │    ├─ App() / Component()                   │
        │    ├─ setData()                             │
        │    ├─ triggerEvent()                        │
        │    └─ data / properties / methods            │
        └─────────────────────────────────────────────┘
```

### 1. 注册层适配 (register.ts)

**核心代码：**

```typescript
// 文件：packages/wevu/src/runtime/register.ts

// 关键：桥接到小程序 Component()（在微信中可用于页面/组件）
export function registerComponent<T extends object, C, M>(
  runtimeApp: RuntimeApp<T, C, M>,
  methods: M,
  watch: WatchMap | undefined,
  setup: DefineComponentOptions<T, C, M>['setup'],
  mpOptions: Record<string, any>,
) {
  const componentOptions: Record<string, any> = {
    ...mpOptions,
  }

  // 拦截 onLoad，挂载 runtime
  const userOnLoad = mpOptions.onLoad
  componentOptions.onLoad = function onLoad(this, ...args) {
    // 关键：在这里创建 wevu runtime
    mountRuntimeInstance(this, runtimeApp, watch, setup)

    if (typeof userOnLoad === 'function') {
      userOnLoad.apply(this, args)
    }
  }

  // 拦截 onUnload，清理 runtime
  const userOnUnload = mpOptions.onUnload
  componentOptions.onUnload = function onUnload(this, ...args) {
    teardownRuntimeInstance(this) // 清理

    if (typeof userOnUnload === 'function') {
      userOnUnload.apply(this, args)
    }
  }

  // 调用小程序原生 API
  Page(pageOptions)
}
```

**适配要点：**

1. **生命周期拦截**：在小程序生命周期中挂载/卸载 runtime
2. **方法桥接**：将 runtime.methods 桥接到小程序实例
3. **保留用户代码**：不覆盖用户定义的生命周期

**对比 Vue 3：**

```typescript
// Vue 3 的组件注册（Web）

const app = createApp(RootComponent)
app.mount('#root') // 直接挂载到 DOM

// 不需要拦截，因为 Web 没有生命周期概念
```

### 2. setData 适配 (app.ts + register.ts)

**核心代码：**

```typescript
// 文件：packages/wevu/src/runtime/register.ts

export function mountRuntimeInstance<T extends object, C, M>(
  target: InternalRuntimeState,
  runtimeApp: RuntimeApp<T, C, M>,
  watchMap: WatchMap | undefined,
  setup?: DefineComponentOptions<T, C, M>['setup'],
): RuntimeInstance<T, C, M> {
  // 关键：创建 adapter，桥接到小程序 setData
  const runtime = runtimeApp.mount({
    setData(payload: Record<string, any>) {
      // target 是小程序实例 (this)
      if (typeof target.setData === 'function') {
        target.setData(payload) // 调用小程序原生 API
      }
    },
  })

  // 挂载到实例上
  target.__wevu = runtime
}
```

**在 job 中使用：**

```typescript
// 文件：packages/wevu/src/runtime/app.ts

function job() {
  const snapshot = collectSnapshot()
  const diff = diffSnapshots(latestSnapshot, snapshot)

  // 关键：调用 adapter.setData
  // 实际上调用的是 target.setData()
  if (typeof currentAdapter.setData === 'function') {
    currentAdapter.setData(diff)
  }
}
```

**适配要点：**

1. **Adapter 模式**：通过 adapter 抽象层适配不同平台
2. **setData 路径**：生成小程序兼容的路径（`'a.b.c'`）
3. **错误处理**：捕获 setData 失败，避免中断

**对比 Vue 3：**

```typescript
// Vue 3 的 DOM 更新（Web）

function patch(n1, n2) {
  // 直接操作 DOM
  hostPatchProp(el, key, value)

  // 不需要 adapter，因为 Web 标准 API
}
```

### 3. Diff 算法适配 (diff.ts)

**核心需求：生成小程序 setData 兼容的路径**

```typescript
// 文件：packages/wevu/src/runtime/diff.ts

export function diffSnapshots(
  prev: Record<string, any>,
  next: Record<string, any>
): Record<string, any> {
  const output: Record<string, any> = {}

  const keys = new Set([...Object.keys(prev), ...Object.keys(next)])

  for (const key of keys) {
    const prevValue = prev[key]
    const nextValue = next[key]

    if (!isDeepEqual(prevValue, nextValue)) {
      // 关键：递归 diff，生成嵌套路径
      assignNestedDiff(prevValue, nextValue, key, output)
    }
  }

  return output
}

function assignNestedDiff(
  prev: any,
  next: any,
  path: string, // 路径：'user' -> 'user.name' -> 'user.name.first'
  output: Record<string, any>
) {
  if (isPlainObject(prev) && isPlainObject(next)) {
    const keys = new Set([...Object.keys(prev), ...Object.keys(next)])

    keys.forEach((key) => {
      if (!Object.prototype.hasOwnProperty.call(next, key)) {
        output[`${path}.${key}`] = null // 删除属性
        return
      }

      // 递归，生成嵌套路径
      assignNestedDiff(
        prev[key],
        next[key],
        `${path}.${key}`, // 路径拼接
        output
      )
    })
  }
  else {
    output[path] = normalizeSetDataValue(next) // 最终路径
  }
}
```

**示例：**

```typescript
// 初始状态
const prev = {
  user: {
    profile: {
      name: 'Alice',
      age: 25
    },
    settings: {
      theme: 'dark'
    }
  },
  items: [1, 2, 3]
}

// 修改后
const next = {
  user: {
    profile: {
      name: 'Bob', // ← 改了
      age: 25
    },
    settings: {
      theme: 'dark'
    }
  },
  items: [1, 2, 3, 4] // ← 加了一个
}

// diff 结果（小程序 setData 格式）
const diff = {
  'user.profile.name': 'Bob',
  'items[3]': 4,
}

// 调用小程序 API
this.setData({
  'user.profile.name': 'Bob',
  'items[3]': 4
})
```

**对比 Vue 3：**

```typescript
// Vue 3 的 Virtual DOM diff

const prevVNode = {
  type: 'div',
  props: { className: 'container' },
  children: [
    { type: 'span', children: 'Hello' }
  ]
}

const nextVNode = {
  type: 'div',
  props: { className: 'wrapper' }, // ← 改了
  children: [
    { type: 'span', children: 'Hello' }
  ]
}

// diff 结果：DOM 操作列表
const operations = [
  { op: 'setAttribute', name: 'className', value: 'wrapper' },
]

// 调用 Web API
el.setAttribute('className', 'wrapper')
```

### 4. 双向绑定适配 (bindModel.ts)

**小程序的双向绑定事件**

```vue
<!-- Web Vue 3 -->
<input v-model="username" />

<!-- 编译为 -->
<input
  :value="username"
  @input="username = $event.target.value"
/>
```

```vue
<!-- 小程序 -->
<input model:value="{{username}}" bind:input="handleInput" />

<!-- 需要手动处理 -->
Page({
  data: { username: '' },

  handleInput(e) {
    this.setData({
      username: e.detail.value  // 小程序的事件格式不同
    })
  }
})
```

**wevu 的适配方案：**

```typescript
// 文件：packages/wevu/src/runtime/bindModel.ts

// 解析小程序事件
export function defaultParser(event: any) {
  if (event == null) {
    return event
  }

  if (typeof event === 'object') {
    // 关键：从小程序事件中提取值
    if ('detail' in event && event.detail && 'value' in event.detail) {
      return event.detail.value // 大多数小程序组件
    }
    if ('target' in event && event.target && 'value' in event.target) {
      return event.target.value // 某些特殊组件
    }
  }

  return event
}

// 创建 model 绑定
export function createBindModel(
  publicInstance: Record<string, any>,
  state: Record<string, any>,
  computedRefs: Record<string, ComputedRef<any>>,
  computedSetters: Record<string, (value: any) => void>,
) {
  return function bindModel<T = any>(path: string, options?: ModelBindingOptions<T>) {
    const segments = toPathSegments(path)

    const resolveValue = () => getFromPath(publicInstance, segments)
    const assignValue = (value: T) => {
      setByPath(state, computedRefs, computedSetters, segments, value)
    }

    return {
      value: resolveValue,
      update: assignValue,

      // 生成小程序事件绑定
      model(modelOptions?: ModelBindingOptions<T>) {
        const handlerKey = `on${capitalize(event)}`
        return {
          [valueProp]: formatter(resolveValue()), // 绑定值
          [handlerKey]: (event: any) => { // 绑定事件
            const parsed = parser(event) // 解析事件
            assignValue(parsed) // 更新值
          }
        }
      }
    }
  }
}
```

**使用示例：**

```typescript
// 组件 setup
import { bindModel, ref } from 'wevu'

export default {
  setup() {
    const username = ref('')

    // 创建 model 绑定
    const usernameModel = bindModel(this, 'username')

    // 生成小程序事件绑定
    const inputBinding = usernameModel.model({
      event: 'input',
      valueProp: 'value'
    })
    // → { value: 'Bob', onInput: fn }

    return {
      username,
      inputBinding
    }
  }
}
```

```vue
<!-- 模板中使用 -->
<input model:value="{{username}}" bind:input="handleInput" />
```

***

## 生命周期映射

### Vue 3 vs 小程序生命周期

```typescript
// 文件：packages/wevu/src/runtime/hooks.ts

// Vue 3 生命周期 → 小程序生命周期映射

export function onMounted(handler: () => void) {
  if (!__currentInstance) {
    throw new Error('onMounted() must be called synchronously inside setup()')
  }
  // 映射到小程序 onReady
  pushHook(__currentInstance, 'onReady', handler)
}

export function onUnmounted(handler: () => void) {
  if (!__currentInstance) {
    throw new Error('onUnmounted() must be called synchronously inside setup()')
  }
  // 映射到小程序 onUnload (Page) 或 detached (Component)
  pushHook(__currentInstance, 'onUnload', handler)
}

export function onActivated(handler: () => void) {
  if (!__currentInstance) {
    throw new Error('onActivated() must be called synchronously inside setup()')
  }
  // 映射到小程序 onShow
  pushHook(__currentInstance, 'onShow', handler)
}

export function onDeactivated(handler: () => void) {
  if (!__currentInstance) {
    throw new Error('onDeactivated() must be called synchronously inside setup()')
  }
  // 映射到小程序 onHide
  pushHook(__currentInstance, 'onHide', handler)
}
```

### 生命周期对比表

| Vue 3             | Page       | Component              | 说明                           |
| ----------------- | ---------- | ---------------------- | ------------------------------ |
| `onBeforeMount`   | -          | -                      | 立即执行（小程序无挂载前钩子） |
| `onMounted`       | `onReady`  | `ready`                | 页面/组件就绪                  |
| `onBeforeUpdate`  | -          | -                      | setData 前立即执行             |
| `onUpdated`       | -          | -                      | setData 后执行（自定义）       |
| `onBeforeUnmount` | -          | -                      | 立即执行（小程序无卸载前钩子） |
| `onUnmounted`     | `onUnload` | `detached`             | 页面卸载/组件移除              |
| `onActivated`     | `onShow`   | `show` (pageLifetimes) | 页面/组件显示                  |
| `onDeactivated`   | `onHide`   | `hide` (pageLifetimes) | 页面/组件隐藏                  |
| `onErrorCaptured` | `onError`  | `error`                | 错误捕获                       |

***

## 双向绑定

### Web Vue 3 的 v-model

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

const username = ref('')
const message = ref('')
const selected = ref('a')
</script>

<template>
  <input v-model="username">
  <textarea v-model="message" />
  <select v-model="selected">
    <option value="a">
      A
    </option>
    <option value="b">
      B
    </option>
  </select>
</template>
```

**编译后：**

```vue
<!-- 简化版 -->
<input
  :value="username"
  @input="username = $event.target.value"
/>

<textarea
  :value="message"
  @input="message = $event.target.value"
></textarea>

<select
  :value="selected"
  @change="selected = $event.target.value"
>
  <option value="a">A</option>
  <option value="b">B</option>
</select>
```

### 小程序的 model

```vue
<!-- 小程序原生写法 -->
<input model:value="{{username}}" bind:input="handleInput" />

<textarea model:value="{{message}}" bind:input="handleInput"></textarea>

<picker model:value="{{selected}}" bind:change="handleChange">
  <view>A</view>
  <view>B</view>
</picker>
```

```typescript
Page({
  data: {
    username: '',
    message: '',
    selected: 'a'
  },

  handleInput(e) {
    this.setData({
      username: e.detail.value
    })
  },

  handleChange(e) {
    this.setData({
      selected: e.detail.value
    })
  }
})
```

### wevu 的 bindModel

```typescript
// 文件：packages/wevu/src/runtime/bindModel.ts

// 创建 model 绑定
const model = bindModel(publicInstance, 'form.username')

// 生成小程序属性
const inputProps = model.model({
  event: 'input',
  valueProp: 'value'
})

// 结果：
// {
//   value: 'Bob',
//   onInput: (e) => {
//     const value = defaultParser(e)  // e.detail.value
//     setByPath(state, ['form', 'username'], value)
//   }
// }
```

**使用示例：**

```vue
<script>
import { ref } from 'wevu'
import { bindModel } from 'wevu/runtime'

export default {
  setup() {
    const username = ref('')
    const message = ref('')

    return {
      username,
      message
    }
  },

  // bindModel 会自动生成这些方法
  methods: {
    handleUsernameInput(e) {
      // 自动更新 username
    },

    handleMessageInput(e) {
      // 自动更新 message
    }
  }
}
</script>

<template>
  <input model:value="{{username}}" bind:input="handleUsernameInput">
  <textarea model:value="{{message}}" bind:input="handleMessageInput" />
</template>
```

***

## 渲染层对比

### Vue 3 的渲染流程

```
用户代码: state.count++
   ↓
Reactive System: 触发依赖
   ↓
Scheduler: queueJob(patch)
   ↓
微任务: 执行 patch
   ↓
Virtual DOM Diff:
  - 对比新旧 VNode 树
  - 生成最小操作列表
  [
    { type: 'PATCH', prop: 'textContent', value: '1' }
  ]
   ↓
DOM 操作:
  - el.textContent = '1'
   ↓
浏览器渲染引擎更新 DOM
```

### wevu 的渲染流程

```
用户代码: 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 更轻量？

```
Vue 3 核心代码量：
├── reactivity/      ~5,000 行  wevu 复用
├── runtime-core/   ~10,000 行  ❌ wevu 不需要（Virtual DOM）
├── runtime-dom/    ~5,000 行  ❌ wevu 不需要（DOM 操作）
├── compiler-core/  ~15,000 行  ❌ wevu 不需要（模板编译）
└── compiler-dom/   ~5,000 行  ❌ wevu 不需要（DOM 编译）
Total: ~40,000 行

wevu 核心代码量：
├── reactivity/     ~5,000 行  与 Vue 3 相同
├── runtime/        ~3,000 行  ⚡ 精简版（无 Virtual DOM）
├── scheduler/      ~100 行    与 Vue 3 相同
└── diff/           ~500 行   ⚡ 小程序专用
Total: ~8,600 行

节省：~31,400 行（78%）
```

### 适配策略

| 需求           | Vue 3       | wevu        | 适配方式                 |
| -------------- | ----------- | ----------- | ------------------------ |
| **数据响应式** | Proxy       | Proxy       | 直接复用                 |
| **批量更新**   | nextTick    | nextTick    | 直接复用                 |
| **视图更新**   | DOM API     | setData     | Adapter 桥接             |
| **事件处理**   | DOM Events  | Mini Events | Parser 解析              |
| **生命周期**   | Web Hooks   | MP Hooks    | 映射转换                 |
| **模板编译**   | VNode → DOM | Vue → WXML  | 编译器处理（weapp-vite） |

***

## 参考源码

* **wevu 响应式**: `packages/wevu/src/reactivity/`
* **wevu 调度器**: `packages/wevu/src/scheduler.ts`
* **wevu 运行时**: `packages/wevu/src/runtime/app.ts`
* **小程序注册**: `packages/wevu/src/runtime/register.ts`
* **Diff 算法**: `packages/wevu/src/runtime/diff.ts`
* **双向绑定**: `packages/wevu/src/runtime/bindModel.ts`

## 相关阅读

* [wevu 工作原理](https://github.com/weapp-vite/weapp-vite/blob/main/packages/wevu/ARCHITECTURE.md)
* [Vue 3 兼容性文档](./vue3-compat)
* [小程序 setData 优化](https://developers.weixin.qq.com/miniprogram/dev/framework/performance/tips.html)

---

---
url: /wevu.md
---

# wevu 概览

`wevu` 是一个面向小程序（以微信小程序为主）的轻量运行时。你可以把它理解成：“把 Vue 3 的响应式心智模型带到小程序里”，但不引入 Virtual DOM，而是用快照 diff 来尽量减少 `setData` 的更新量。

它主要提供：

* Vue 3 风格的响应式（`ref` / `reactive` / `computed` / `watch`）
* 基于快照 diff 的最小化 `setData` 更新
* 类 Pinia 的 Store（状态管理）

wevu 不改变小程序“数据驱动 + 模板渲染”的基本模型：你仍然写 WXML/WXSS（或配合 weapp-vite 用 Vue SFC 编写模板/样式/配置），但业务逻辑可以用熟悉的 Composition API 组织起来。

## wevu 在整套体系里的位置

如果你同时使用 weapp-vite 的 Vue SFC：

* **weapp-vite（编译期）**：把 `.vue` 编译成 WXML/WXSS/JS/JSON，并做模板语法转换。
* **wevu（运行期）**：负责响应式、生命周期 hooks、快照 diff 与最小化 `setData`。

因此遇到问题时可以快速分层定位：

* “模板/指令/usingComponents/v-model 怎么编译？” → 先看 `/wevu/vue-sfc`
* “状态为什么不更新 / hooks 为什么不触发？” → 先看 `/wevu/runtime` 与 `/wevu/compatibility`

## 诞生的小故事

这段背景不影响使用，你可以先跳过：

* 最初想叫 `wevue`（weapp + vue），但 npm 已被占用，于是缩写成了 `wevu`。
* 在为 `weapp-vite` 补齐 Vue SFC 支持时，调研过社区方案（如 `vue-mini`），但编译器与运行时都需要大改，最后选择自己实现以更贴合小程序。
* 借鉴 Vue 3 的响应式设计思路，并考虑多小程序平台适配，逐步形成现在的 wevu。

## 你会用到的能力

* **响应式与调度**：与 Vue 3 相同心智的 `ref` / `reactive` / `computed` / `watch` / `watchEffect`，更新通过微任务批量调度（`nextTick`）。
* **页面/组件注册**：`defineComponent()` 统一通过小程序 `Component()` 注册；`createApp()` 可在存在全局 `App()` 时自动注册应用；`createWevuComponent()` 供 weapp-vite 编译产物调用。
* **最小化 setData**：运行时把 state + computed 转为 plain snapshot，diff 后只把变化路径传给 `setData`。
* **双向绑定辅助**：`bindModel(path)` 生成适配小程序事件的数据/事件绑定对象。
* **Store（状态管理）**：`defineStore` / `storeToRefs` / `createStore`（可选插件入口）。

:::tip 导入约定
运行时 API 都从 `wevu` 主入口导入；不支持 `wevu/store`、`wevu/runtime` 等子路径。`wevu/compiler` 仅供 weapp-vite 等编译侧工具使用（非稳定用户 API）。
:::

## 编译侧桥接（wevu/compiler）

`wevu/compiler` 用来承载 wevu 与编译工具之间的共享常量，避免在多个项目里重复写字符串：

* `WE_VU_MODULE_ID`：运行时入口模块名（`wevu`）。
* `WE_VU_RUNTIME_APIS`：运行时 API 名称集合（如 `createApp` / `defineComponent` / `createWevuComponent`）。
* `WE_VU_PAGE_HOOK_TO_FEATURE`：页面 hook 与 features 的映射表。

这些导出面向编译工具（例如 weapp-vite），应用代码不要依赖它们作为稳定 API。

## 推荐学习顺序（按“最短上手 → 深入理解”）

1. `/wevu/quick-start`：先跑通一个页面/组件（含 store）
2. `/wevu/runtime`：理解 `setup(props, ctx)`、生命周期 hooks、`bindModel`、watch 策略
3. `/wevu/component`：掌握组件字段透传、`properties/props`、`emit/expose` 等细节
4. `/wevu/store`：落地状态管理（订阅、补丁、插件）
5. `/wevu/compatibility`：了解限制与边界（尤其是 provide/inject、页面事件按需派发）

接下来可以按顺序阅读：

* 快速上手：`/wevu/quick-start`
* 运行时 API：`/wevu/runtime`
* defineComponent（组件）：`/wevu/component`
* Store：`/wevu/store`
* 兼容性与注意事项：`/wevu/compatibility`
* Vue 3 兼容性说明（完整）：`/wevu/vue3-compat`
* wevu vs Vue 3（核心差异）：`/wevu/vue3-vs-wevu`

---

---
url: /wevu/vue3-compat.md
---

# wevu 的 Vue 3 兼容性说明

`wevu` 是一个面向小程序（以微信小程序为主）的 Vue 3 风格运行时：尽量提供熟悉的 Vue 3 API 形态，同时针对小程序运行环境进行适配与约束。

本文用于帮助你快速判断：

* 哪些 API 可以像 Vue 3 一样直接使用
* 哪些 API 在小程序中存在差异或仅部分兼容
* 哪些 Vue 3 能力在小程序中不适用

## Vue 3 兼容性目标

`wevu` 的核心目标是降低 Vue 开发者进入小程序的心智成本：让你可以继续用 Composition API 组织业务逻辑，并通过快照 diff 最小化 `setData` 更新。

需要注意：小程序不是浏览器环境，没有 DOM / Virtual DOM；事件系统与生命周期也与 Web 存在天然差异，因此 `wevu` 不可能做到“100% 无差别兼容 Vue 3”。

## 完全兼容的 API

以下 API 与 Vue 3 的行为一致（或在 `wevu` 中保持同等语义），可以直接按 Vue 3 的习惯使用。

### 响应式（Reactivity）

* `reactive()`：创建响应式对象
* `ref()`：创建 ref
* `computed()`：创建计算属性
* `watch()`：监听响应式源
* `watchEffect()`：自动追踪依赖的副作用
* `toRefs()`：把响应式对象转换为 refs
* `toRef()`：为指定属性创建 ref
* `toRaw()`：获取原始对象
* `isRef()`：判断是否为 ref
* `isReactive()`：判断是否为 reactive
* `readonly()`：创建只读包装
* `markRaw()`：标记对象跳过响应式转换
* `isRaw()`：判断对象是否被标记为 raw

### 浅层响应式（Shallow Reactivity）

* `shallowReactive()`：创建浅层响应式对象
* `shallowRef()`：创建浅层 ref
* `isShallowReactive()`：判断是否为 shallowReactive
* `isShallowRef()`：判断是否为 shallowRef
* `triggerRef()`：手动触发 ref 更新

### 生命周期钩子（Lifecycle Hooks）

以下钩子在 `wevu` 中提供与 Vue 3 对齐的调用方式（但其触发时机映射到小程序生命周期，具体差异见后文）：

* `onMounted()`：组件/页面已就绪
* `onUpdated()`：更新后（在 `setData` 后触发）
* `onUnmounted()`：组件/页面卸载
* `onBeforeMount()`：挂载前（在小程序里会立即执行，见后文）
* `onBeforeUpdate()`：更新前（在 `setData` 前触发）
* `onBeforeUnmount()`：卸载前（在小程序里会立即执行，见后文）
* `onActivated()`：组件激活（映射 `onShow`）
* `onDeactivated()`：组件失活（映射 `onHide`）
* `onErrorCaptured()`：错误捕获

### 组件与调度（Component API）

* `defineComponent()`：定义组件/页面（底层通过小程序 `Component()` 注册）
* `createApp()`：创建应用实例
* `getCurrentInstance()`：获取当前实例
* `nextTick()`：在下一次更新后执行回调

### 依赖注入（Dependency Injection）

* `provide()`：提供依赖
* `inject()`：注入依赖
* `provideGlobal()` / `injectGlobal()`：全局 provide/inject（已弃用，仅用于兼容/过渡）

### Store（Pinia 风格）

`wevu` 内置了 Pinia 风格 Store，并且可以做到“无需全局注册，直接使用”：

* `defineStore()`：定义 Store（Setup/Options 两种模式）
* `storeToRefs()`：从 store 提取 refs
* `createStore()`：可选的 store manager（可做插件入口）
* `$patch`：批量更新 state
* `$reset`：重置 state（仅 Options Store）
* `$subscribe`：订阅 state 变更
* `$onAction`：订阅 action 调用

**关键差异：不需要全局注册**

```ts
// ❌ Pinia：需要全局注册
import { createPinia } from 'pinia'

// wevu：直接使用即可
import { defineStore } from 'wevu'

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  return { count }
})

const pinia = createPinia()
app.use(pinia) // Pinia 必须先注册
```

更多 Store 细节见：`/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: /config/worker.md
---
# Worker 配置 {#worker-config}

当 `app.json` 配置了 `workers` 目录，`weapp-vite` 可以帮助编译 Worker 入口脚本。

\[\[toc]]

## `weapp.worker` {#weapp-worker}

* **类型**：
  ```ts
  {
    entry?: string | string[]
  }
  ```
* **默认值**：`undefined`

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

export default defineConfig({
  weapp: {
    worker: {
      entry: ['calc.ts', 'image.ts'],
    },
  },
})
```

说明：

* `entry` 为 **相对于 `app.json.workers` 目录** 的路径。
* 若未写扩展名，会自动尝试 `.js/.ts`。
* Worker 构建会复用 TS/别名/依赖解析能力，并输出到同一 `dist/` 目录下的 `workers/` 目录。

常见问题：

* **未指定 `entry` 会怎样？** 不会额外构建 Worker；你可以自行维护产物，但无法享受自动编译。
* **Worker 入口不存在？** 构建时会输出警告，并跳过该入口。

***

更多调试手段请见 [共享配置 · weapp.debug](/config/shared.md#weapp-debug)。

---

---
url: /guide/wxml.md
---
# WXML 增强

`weapp-vite` 对 WXML 做了两类增强：

* **自动收集 WXML 依赖**：把 `import` / `include` 引到的模板文件自动带进产物
* **事件语法糖（可选）**：允许写 `@tap="fn"`，构建时自动转换成原生 `bind:tap`

这页介绍它们的工作方式，以及在你不需要时如何关闭。

## 静态分析与额外文件

默认情况下，框架会扫描页面、组件、分包目录，解析 `import` / `include` 中的 `src`，将对应的 WXML 文件复制到产物目录，并保持路径一致。

> \[!IMPORTANT]
> 该分析是静态的，无法推断运行时动态拼接的路径。当前版本的 `weapp.isAdditionalWxml` 仍为预留字段，**不会参与扫描**。如果必须走动态路径，请确保这些模板能通过某个固定的 `import` / `include` 被引用，或在构建流程中自行补充产物。

## 事件绑定语法糖（可选）

开启 `weapp.wxml` 后，可以使用类似 Vue 的 `@` 语法，weapp-vite 会在构建时转换为原生事件写法：

```html
<!-- 源代码 -->
<view @tap="hello"></view>
<!-- 编译结果 -->
<view bind:tap="hello"></view>
```

对应关系示例：

| 写法                                        | 转换结果            |
| ------------------------------------------- | ------------------- |
| `@tap`                                      | `bind:tap`          |
| `@tap.catch`                                | `catch:tap`         |
| `@tap.mut`                                  | `mut-bind:tap`      |
| `@tap.capture`                              | `capture-bind:tap`  |
| `@tap.capture.catch` / `@tap.catch.capture` | `capture-catch:tap` |

更多事件类型可参考[官方事件分类](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxml/event.html)。

> \[!WARNING]
> 某些第三方 WXML 插件的格式化功能可能无法识别 `@tap` 等语法糖。当前版本暂无单独开关，建议直接使用原生 `bind:` 写法规避冲突。

## 当前可配置的范围

目前 `weapp.wxml` 仅影响 **扫描阶段**（`excludeComponent` / `platform`），模板处理阶段的 `transformEvent` / `removeComment` 等选项尚未接入，详见 [WXML 配置](/config/wxml.md#weapp-wxml)。

---

---
url: /config/wxml.md
---
# WXML 配置 {#wxml-config}

`weapp-vite` 会扫描 WXML 以完成组件自动导入、WXS 依赖分析与模板产物输出。本页说明 `weapp.wxml` 的配置项与当前生效范围。

\[\[toc]]

## `weapp.wxml` {#weapp-wxml}

* **类型**：
  ```ts
  boolean | {
    // 扫描阶段
    excludeComponent?: (tagName: string) => boolean
    platform?: MpPlatform

    // 模板处理阶段（当前版本未接入配置）
    removeComment?: boolean
    transformEvent?: boolean
    scriptModuleExtension?: string
    scriptModuleTag?: string
    templateExtension?: string
  }
  ```
* **默认值**：`true`

### 当前版本的实际生效范围

* **已生效**：`excludeComponent` / `platform`（影响 WXML 扫描）。
* **尚未接入**：`removeComment` / `transformEvent` / `scriptModuleExtension` / `scriptModuleTag` / `templateExtension`。

### 示例

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

export default defineConfig({
  weapp: {
    wxml: {
      excludeComponent(tag) {
        return tag.startsWith('demo-')
      },
    },
  },
})
```

> \[!NOTE]
> 当前版本即便设置 `weapp.wxml = false`，仍会进行基础扫描与产物输出；该字段主要保留用于后续增强选项的统一入口。

***

相关能力：

* [自动导入组件配置](/config/auto-import-components.md#weapp-autoimportcomponents)
* [WXS 配置](/config/wxs.md)

---

---
url: /guide/wxs.md
---
# WXS 增强 experimental

WXS（WeiXin Script）是微信小程序提供的轻量脚本语言，常用于在模板里做一些同步的、简单的逻辑处理。它和 JavaScript 不完全一样，能力也更受限。

`weapp-vite` 为 WXS 提供了实验性的增强：你可以用 `.wxs.js` / `.wxs.ts` 写代码，或在 `<wxs>` 里用 `lang="js/ts"` 内联编写，再由构建阶段转换为标准 `.wxs`。

这页说明怎么用、能用到什么程度，以及遇到问题怎么回退。

> \[!WARNING]
> 该能力仍处于实验阶段，仅支持部分 ES 语法。请务必编写单元测试或在开发者工具中充分验证输出结果。

## 外部文件：`.wxs.js` / `.wxs.ts`

* 在引用 WXS 时，可以把 `src` 指向 `.wxs.js` 或 `.wxs.ts`：
  ```html
  <wxs module="test" src="index.wxs.ts" />
  ```
* 构建产物中会自动生成 `index.wxs` 文件，并把 `src` 改写为 `.wxs`。
* 文件内部可以使用部分 ES 语法（如解构、`const`），但仍需遵守 WXS 运行时的限制：
  * 只能使用 `require`，不能使用 `import`。
  * 不能访问浏览器/Node API。
  * 某些语法（例如 `for...of`、`Array.prototype.map`）仍不被支持。

推荐组合 TypeScript 或 JSDoc 的类型提示，在编辑器中获得更好的开发体验。

## 内联 WXS：`lang="js"` / `lang="ts"`

在 WXML 中内联 WXS 时，可以给 `<wxs>` 标签添加 `lang` 属性，让 weapp-vite 帮你完成转译：

```html
<view>{{test.foo}}</view>
<view @tap="{{test.trigger}}">{{test.label}}</view>

<wxs module="test" lang="ts">
const { foo, bar } = require('./index.wxs.js')
const extra = require('./extra.wxs')

export const label = 'demo'

export function trigger(value: string) {
  console.log(value, label)
}

export {
  foo,
  bar,
  extra,
}
</wxs>
```

转译后会自动去除类型标注、保留 `require` 调用，并输出合法的 WXS。

## 当前支持的语法

* 变量声明：`const` / `let` / `var`
* 解构赋值、模板字符串、对象展开（大部分场景）
* 函数声明与导出（`export const`、`export function`、`export { ... }`）
* 简单的 TypeScript 类型标注（会在构建时剥离）

> \[!TIP]
> WXS 不支持 Promise 等异步能力，很多 JS 原生方法也不可用；`weapp-vite` 不会自动 polyfill。建议只在 WXS 里写同步、轻量的逻辑。

## 调试与回退方案

* 构建产物位于 `dist/**.wxs`，可直接打开查看 weapp-vite 的转译结果。
* 若遇到构建失败或运行异常，可临时回退到手写 `.wxs` 版本，或提交 Issue 反馈不兼容的语法。
* 对于复杂逻辑，推荐改写为普通 JS/TS 工具函数，在页面脚本中使用，而不是放在 WXS 中。

随着更多反馈，我们会持续完善 WXS 转译器的兼容性和报错提示。

---

---
url: /config/wxs.md
---
# WXS 配置 experimental {#wxs-config}

`weapp-vite` 会对 `.wxs/.sjs`（以及 `.wxs.ts/.wxs.js`）进行编译输出，并在 Vue SFC 的 class/style 运行时中按需使用 WXS。

> \[!WARNING]
> WXS 增强仍处于实验阶段（experimental），建议在开发者工具中充分验证编译与运行结果。

\[\[toc]]

## `weapp.wxs` {#weapp-wxs}

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

### 实际生效范围

* **影响**：Vue SFC 模板编译阶段的 `class/style` 运行时选择（`auto` 时是否优先 WXS）。
* **不影响**：WXML 中显式引用的 `.wxs/.sjs` 仍会被编译输出。

### 示例

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

export default defineConfig({
  weapp: {
    wxs: false, // 禁用 SFC class/style 使用 WXS，强制回退 JS 运行时
  },
})
```

### 常见问题

* **WXML 引用的 `.wxs` 仍然被输出？** 是的，该行为与 `weapp.wxs` 无关。
* **Vue SFC 的 class/style 绑定走 JS 了？** 若设置了 `weapp.wxs = false`，会强制回退到 JS 运行时。

***

相关能力：

* [Vue SFC 配置](/config/vue.md)
* [WXML 配置](/config/wxml.md)

---

---
url: /guide/wxss.md
---
# 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/what-is-weapp-vite.md
---
# 什么是 Weapp-vite ?

## 核心简介

`weapp-vite` 是一个面向微信小程序的现代构建框架：尽量不改变你写原生小程序的方式（语法、目录结构都能沿用），但把 Vite 生态、TypeScript、CSS 预处理器和更顺滑的开发/构建流程带进来。你仍然写小程序，但开发体验会更接近“现代前端工程”。

## 我们想解决的问题

* 原生工具链缺少一些现代体验：模块化、自动刷新、类型提示等效率工具不够完善。
* 跨端框架虽然功能丰富，但抽象层更厚，学习/调试成本更高；并不适合想坚持原生写法的团队。
* 老项目常见的 gulp / 自研脚本维护成本高：升级依赖、接入新能力都比较费劲。

## Weapp-vite 的能力亮点

* **原生写法 0 改动**：保留微信原生语法和目录组织方式，逐步引入现代能力。
* **Vite/Rolldown 生态**：兼容 Vite 配置与插件，底层打包器 Rolldown 针对小程序场景做了分包、样式注入等优化。
* **工程化开箱即用**：默认支持 TypeScript、PostCSS、Sass/Less、Tailwind CSS、JSONC 等常用特性，并提供 `pnpm create weapp-vite` 和 `pnpm g` 等脚手架命令。
* **小程序特色增强**：自动构建 `miniprogram_npm`、智能分包依赖分析、自动组件注册、WeChat Developer Tools CLI 集成。
* **良好的调试体验**：保存即热更新、详细的构建日志、`weapp.debug` 钩子帮助排查路径解析、产物归属等问题。

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

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

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

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

## 迁移与生态

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

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

---

---
url: /migration/v3.md
---
# 从 v2 升级到 v3

## 重大变更

### 升级了内置 `vite` 的版本，从 `v5` 到 `v6`,

这可能会导致一些 `vite` 的配置项失效，请根据 `v6` 的文档进行配置。

同时由于内部的 `rollup` 插件也得到了升级，可能会导致一些 `commonjs` 和 `esm` 混用的情况失效

## 修复

* 修复了构建 `npm` 包，不自动构建依赖的问题 [#104](https://github.com/weapp-vite/weapp-vite/issues/104)
* 修复了自动构建 `npm` 时，会删除独立子包中的 `miniprogram_npm` 目录问题

---

---
url: /migration/v4.md
---
# 从 v3 升级到 v4

## 重大变更

1. 现在 `autoImportComponents.globs` 是以 `srcRoot` 作为路径，以前是以 `cwd` 作为基准路径，鼓励将所有的资源都放在 `srcRoot` 内部

```diff
    enhance: {
      autoImportComponents: {
-       globs: ['src/components/**/*'],
+       globs: ['components/**/*.wxml'],
      },
    }
```

2. 完全重构的编译核心，带来了更高效的处理速度的同时，也带来了更加强大的扩展性
3. 放弃了 `ts-morph` 编译 `worker` 的实现，因为太慢了，转变为直接使用 `vite` 进行编译
4. 使用 `vite-plugin-commonjs` 来处理项目中带有的 `require` 问题，而不是使用 `@rollup/plugin-commonjs`

由于 `4` 的更改，这导致我们项目中，假如需要引用外部的 `cjs` / `umd` 模块，比如: [visactor index-wx-simple.min.js](https://visactor.io/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/mini-app/wx)

我们需要手动把 `index-wx-simple.min.js` 重命名为 `index-wx-simple.min.cjs` (`js` -> `cjs`)

然后再在你的项目中进行引入:

```ts
import VChart, { vglobal } from './vchart/index-wx-simple.min.cjs'
```

这样就可以正常使用了, [Demo案例](https://github.com/weapp-vite/weapp-vite/tree/main/apps/vite-native/components/chart)

---

---
url: /migration/v5.md
---
# 从 v4 升级到 v5

`weapp-vite@5` 版本编号: `不破不立`

## 重大变更

### 1. 从 `vite` 切换到 `rolldown-vite`

为了带给用户更好的体验，我决定从 `vite` 切换到 `rolldown-vite` 来解决经常被用户诟病的热更新慢的问题

然后我以我一个复杂的测试案例进行性能测试，主包有 `726` 个模块，独立分包有 `643` 个模块，测试结果如下：

整体平均构建时间提升：约 `1.86` 倍

热更新平均构建时间提升：约 `2.50` 倍

`vite` 的整体平均构建时间为 `4302.26` ms, 构建热更新平均构建时间为 `2216.58` ms

切换到 `rolldown-vite` 后，整体平均构建时间为 `2317.75` ms, 构建热更新平均构建时间为 `887.56` ms

### 2. 从 `tsup` 切换到 `tsdown`

都是基于 `rolldown` 生态的

### 3. 从 `bunldle-require` 切换到 `rolldown-require`

`rolldown-require` 是我在这个项目写的一个包，基于 `rolldown` 的

使用 `API` 和配置方面，参考了 `bunldle-require` 但是代码完全不同，代码绝大部分都是从 `rolldown-vite` 抽离出来的

## 迁移成本

目前测试用例暂时都是全部通过的，配置项也完全一致。

基本不需要做什么配置上的变更，就能平滑升级上来。

## 是否过于激进?

本来这种事情就是不破不立，我希望给用户带来极致的体验，而不是保存一下等半天，这会让我感觉到自己很失败

我试了我所有的模板，还有 `200` 个测试用例都跑通了，所以 `weapp-vite` 认为 `v5` 升级还是利极大的大于弊的。

---

---
url: /migration/v6.md
---
# 从 v5 升级到 v6

> 核心提醒：想在小程序中使用 Vue SFC，需要安装 wevu 运行时，并确保 Volar 插件就绪。

## 升级步骤

1. **升级依赖**

   ```sh
   pnpm up weapp-vite@latest
   pnpm install
   ```

2. **安装 wevu（开启 Vue SFC 能力）**
   * 用你惯用的包管理器安装 `wevu`（如执行 `add/install wevu`）。
   * 在页面/组件中直接从 `wevu` 导入 `defineComponent/ref/reactive` 等 API（页面也直接使用 `defineComponent(...)`）。
   * 旧的外置 Vue 插件已不再需要。

3. **Volar/类型提示检查**
   * 确认 `tsconfig.app.json`（或项目主 `tsconfig.json`）里已包含：
     ```json
     {
       "vueCompilerOptions": {
         "plugins": ["weapp-vite/volar"]
       }
     }
     ```
   * VSCode 安装 “Vue - Official (Volar)” 扩展，必要时重启 TS Server。

## 变更要点

* weapp-vite 内置 Vue SFC 编译链；无需额外插件。
* Vue SFC 运行依赖 wevu，请显式安装并从主入口导入。
* 其余配置与 v5 基本兼容，原生小程序代码无须改动。

---

---
url: /wevu/migration/from-native-to-vue-sfc.md
---

# 从原生小程序迁移到 Vue SFC（详细指南）

这是一份面向实际项目的迁移手册，不是概念介绍。目标是让你在**不重写业务**的前提下，把原生小程序稳定迁移到 `weapp-vite + wevu + Vue SFC`。

适用场景：

* 线上已有原生小程序，想提升工程效率与可维护性。
* 新项目计划直接采用 Vue SFC 写法，同时保留小程序原生能力。

## 迁移目标与验收标准

建议先明确“迁移完成”意味着什么，避免只完成了语法替换。

* 功能等价：核心页面流程（浏览、下单、支付、售后）行为与原版一致。
* 稳定性提升：常见空值场景不再出现 `map/forEach of undefined`。
* 结构升级：页面和组件统一为 `.vue` + `<script setup lang="ts">`。
* 可持续迭代：新增需求不再依赖 `setData` 大对象回写。
* 工程闭环：`build + 定向 e2e` 可覆盖关键链路。

## 迁移前准备（必须做）

### 1. 版本与工程基线

* 升级到 `weapp-vite@6.x`（Vue SFC 支持前提）。
* 安装并启用 `wevu` 运行时。
* 确认 `tsconfig.app.json` 已配置：
  * `"vueCompilerOptions.plugins": ["weapp-vite/volar"]`
  * `"vueCompilerOptions.lib": "wevu"`

### 2. 冻结阶段策略

迁移周期内，建议对核心页面采用“冻结功能、只修缺陷”的策略。

* 先控制变量，再改技术栈。
* 每次迁移只涉及一个页面族（如订单、优惠券），避免并发大改。

### 3. 建立对照样本

至少挑 1 个“中等复杂度页面”做试点：

* 有列表渲染（`map/forEach`）
* 有异步请求
* 有页面参数（`onLoad(query)`）
* 有导航/分享/滚动等页面事件

## 总体迁移路线（推荐 4 阶段）

```mermaid
flowchart LR
  A[阶段 0<br/>接入 weapp-vite] --> B[阶段 1<br/>机械迁移到 .vue]
  B --> C[阶段 2<br/>语义迁移到 Composition API]
  C --> D[阶段 3<br/>收口与回归]
```

### 阶段 0：只替构建链路，不改业务行为

先接入 `weapp-vite` 并保证原功能可跑，不立即重构逻辑。

验证最小闭环：

* `pnpm build`
* 在开发者工具中打开并手测 1 到 2 个核心页面

### 阶段 1：机械迁移（重点是“等价”）

先把原 `js + wxml + wxss + json` 聚合成单个 `.vue`，不追求代码优雅。

### 阶段 2：语义迁移（重点是“可维护”）

把 `this.data + this.setData + methods` 逐步替换为 `ref/reactive/computed/watch`。

### 阶段 3：收口（重点是“可持续”）

统一风格、补齐测试、清理历史写法，沉淀迁移规范。

## 原生到 Vue SFC 映射表（高频）

| 原生小程序                 | Vue SFC / wevu 对应                                                  | 迁移建议                             |
| -------------------------- | -------------------------------------------------------------------- | ------------------------------------ |
| `Page({...})`              | `<script setup>` + `definePageJson` + wevu hooks                     | 页面不再写原生构造器                 |
| `Component({...})`         | `<script setup>` + `defineComponentJson` + `defineProps/defineEmits` | 组件声明聚合到 SFC                   |
| `data: {}`                 | `ref/reactive`                                                       | 细粒度状态更易维护                   |
| `this.setData({...})`      | 直接赋值：`state.xxx = y`                                            | 由 wevu 负责最小更新                 |
| `onLoad/onShow/onHide/...` | `onLoad/onShow/onHide/...`（从 `wevu` 导入）                         | 生命周期迁移成本低                   |
| `observers`                | `watch` / `watchEffect`                                              | 逻辑更明确，易测试                   |
| `properties`               | `defineProps`（推荐）或兼容 `properties`                             | 新代码优先 Vue 风格                  |
| `triggerEvent`             | `defineEmits` + `emit(...)`                                          | 类型更清晰                           |
| `usingComponents`          | `definePageJson/defineComponentJson` 或 `<json>`                     | 不要在脚本里 `import` 注册小程序组件 |

## 实操：从 4 文件迁移为 1 个 SFC

### 迁移前（原生页面）

```js
// pages/coupon/coupon-activity-goods/index.js
Page({
  data: {
    goods: [],
    detail: {},
  },
  onLoad(query) {
    const id = Number(query.id)
    this.id = id
    this.getCouponDetail(id)
    this.getGoodsList(id)
  },
  getGoodsList(id) {
    fetchGoodsList(id).then((goods) => {
      this.setData({ goods })
    })
  },
})
```

### 迁移后（Vue SFC 页面）

```vue
<script setup lang="ts">
import { onLoad, ref } from 'wevu'
import { fetchGoodsList } from '../../../services/good/fetchGoods'

definePageJson(() => ({
  navigationBarTitleText: '活动商品',
  usingComponents: {
    'goods-list': '/components/goods-list/index',
  },
}))

const goods = ref<any[]>([])
const couponId = ref<number>(0)

onLoad(async (query) => {
  couponId.value = Number(query?.id ?? 0)
  await getGoodsList(couponId.value)
})

async function getGoodsList(id: number) {
  const list = await fetchGoodsList(id)
  goods.value = Array.isArray(list) ? list : []
}
</script>

<template>
  <goods-list :goods-list="goods" />
</template>
```

> 迁移第一步允许“结构升级但逻辑不重构”。先跑通，再优化。

## 两种落地策略：渐进式 vs 直接式

### 方案 A：渐进式（推荐）

先用 `<script setup>` + `defineOptions({...})` 保持原对象风格，再逐步迁移到组合式 API。

适合：存量页很多、业务变更频繁、团队迁移经验不足。

### 方案 B：直接式

一步到位改成 `ref/reactive/watch + hooks`。

适合：页面规模小、测试完善、迁移窗口集中。

## 最容易出错的 8 个点（含修复方式）

### 1. `map/forEach of undefined`

根因：接口字段为空、类型不稳定、参数解析失败。

修复：

* 所有列表统一 `Array.isArray` 兜底。
* JSON 参数反序列化加 `try/catch`。
* 模板里避免对可空对象深链访问。

```ts
const skuDetailVos = Array.isArray(ele.skuDetailVos) ? ele.skuDetailVos : []
const specs = Array.isArray(item.skuSpecLst)
  ? item.skuSpecLst.map(s => s?.specValue).filter(Boolean)
  : []
```

### 2. 组件不渲染

根因：只在脚本里 `import`，没有写 `usingComponents`。

修复：把注册写到 `definePageJson/defineComponentJson` 或 `<json>`。

### 3. `v-model` 行为不符合预期

根因：小程序不是 DOM 事件模型，且存在标签映射限制。

修复：复杂组件改为显式 `:value` + `@input/@change`；必要时使用 `useBindModel`。

### 4. 生命周期没触发

根因：迁移后把页面事件写成普通函数，未通过 wevu hooks 注册。

修复：从 `wevu` 导入 `onLoad/onPageScroll/onShareAppMessage/...`。

### 5. 页面参数类型错乱

根因：`query` 全是字符串，直接当 number/object 使用。

修复：统一做 parse 层和默认值层。

### 6. 本地开发能跑，但构建后页面崩溃

根因：只验证了 dev 场景，没有验证 build 产物与真机行为。

修复：每轮迁移都执行“开发调试通过 -> 构建验证通过 -> 真机关键路径回归”。

### 7. 一次迁移太多页面导致回滚困难

根因：提交粒度过大。

修复：按“页面族”迁移，每次只处理一个业务域并可单独回滚。

### 8. 先重构再迁移，问题难定位

根因：把“技术迁移”和“业务重构”耦合。

修复：先机械迁移，再结构优化。

## 推荐目录与分层（迁移后）

建议每个页面按“页面 SFC + 同目录服务/工具”组织，避免继续堆在大 `index.vue`。

```text
pages/order/order-confirm/
  index.vue
  pay.ts
  mapper.ts
  guards.ts
```

拆分规则：

* `mapper.ts`：接口 DTO -> 视图模型转换。
* `guards.ts`：空值保护、参数合法化、兜底逻辑。
* `pay.ts`：支付等副作用流程。

## 页面迁移清单（可直接执行）

### 清单 A：机械迁移

1. 合并 `index.js/wxml/wxss/json` 到 `index.vue`。
2. 保留原函数名与流程，不动业务逻辑。
3. 补齐 JSON 配置（导航栏、组件注册、页面配置）。
4. build 并手测页面主路径。

### 清单 B：语义升级

1. 用 `ref/reactive` 替代 `this.data`。
2. 用直接赋值替代 `setData`。
3. 用 `watch/watchEffect` 替代 `observers`。
4. 抽离 `mapper/guards`，减少页面脚本复杂度。

### 清单 C：发布前联调

1. 把迁移页面按真实用户路径串起来联调一遍（进入、操作、返回、再进入）。
2. 对核心接口做异常场景验证（空数组、空对象、字段缺失、接口超时）。
3. 确认构建产物在开发者工具与真机表现一致。

## 验证策略（从小到大）

### 1. 单页面冒烟

* 进入页面
* 请求成功/失败分支
* 操作按钮
* 页面返回与再次进入

### 2. 目标构建验证

```bash
pnpm build
```

### 3. 关键链路 e2e

只覆盖高价值路径，不建议迁移阶段就跑全量：

* 下单确认
* 优惠券活动商品
* 地址选择/回填

## 团队协作建议（通用）

* 一次提交只做一类改动：迁移或重构二选一。
* 每次改动都要记录“迁移前后行为对照”和“回滚点”。
* 页面新增或调整后，及时更新团队调试文档与常用入口配置。

## 最终验收（Definition of Done）

当以下条件都成立，迁移可以视为完成：

* 核心页面已迁移到 `<script setup lang="ts">`，不再使用 `Page/Component` 原生构造器。
* 页面逻辑不依赖大面积 `setData`，状态更新路径可追踪。
* 常见空值崩溃点（数组/对象）有统一防御策略。
* 开发调试、构建产物、真机表现三者一致。
* 有最小 e2e 用例覆盖关键业务链路。

## 延伸阅读

* [Vue SFC：基础与组成](/wevu/vue-sfc/basics)
* [Vue SFC：配置与宏](/wevu/vue-sfc/config)
* [Vue SFC：模板与指令](/wevu/vue-sfc/template)
* [Vue SFC：调试与排错](/wevu/vue-sfc/troubleshoot)
* [运行时与生命周期](/wevu/runtime)

---

---
url: /wevu/vue-sfc/migrate-from-native.md
---

# 章节已迁移

本章节已迁移为独立迁移指南，不再归属到“Vue SFC 开发”子章节。

请访问新地址：

* [从原生小程序迁移到 Vue SFC（详细指南）](/wevu/migration/from-native-to-vue-sfc)

---

---
url: /community/showcase.md
---
# 优秀案例展示

## xiaomusic 小程序客户端

> 开源小程序音乐播放器，可控制小爱音箱播放本地/NAS音乐

![xiaomusic](/cases/0.jpeg)

`GitHub 地址`: https://github.com/F-loat/xiaoplayer

---

---
url: /guide/json-enhance.md
---
# 使用 TS/JS 生成 JSON

小程序项目里有很多结构相似的 `json` 配置（页面/组件/App）。`weapp-vite` 在兼容原生 `json/jsonc` 的基础上，允许你用 `json.ts` / `json.js` 生成最终配置，让配置也能享受模块化、类型提示和复用能力。

一个组件若名为 `custom`，框架会按以下优先级查找配置文件：`custom.jsonc` → `custom.json` → `custom.json.ts` → `custom.json.js`。因此你可以在需要时逐步升级为脚本驱动的配置。

## 为什么要用脚本生成 JSON？

* **复用与拆分**：直接 `import` 共享配置，避免复制粘贴。
* **类型安全**：借助 TypeScript 或 JSDoc 获得智能提示、错误提示。
* **动态拼装**：在同一文件中根据条件判断、合并配置，更易维护。

## 快速示例

下面示例展示了同一个组件的三种写法。`defineComponentJson` 只是为了提供类型提示，不会修改你传入的内容。

> 如果你使用的是 Vue SFC（`.vue`）并希望把配置写在 `<script setup>` 里（而不是单独写 `*.json.ts`），可以使用 `definePageJson / defineComponentJson` 等 build-time 宏，详见：[Vue SFC · Script Setup JSON 宏](/wevu/vue-sfc/config#script-setup-json-macros)。

::: code-group

```json [navigation-bar.json]
{
  "component": true,
  "styleIsolation": "apply-shared",
  "usingComponents": {}
}
```

```ts [navigation-bar.json.ts]
import { defineComponentJson } from 'weapp-vite/json'

export default defineComponentJson({
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
})
```

```js [navigation-bar.json.js]
import { defineComponentJson } from 'weapp-vite/json'

export default defineComponentJson({
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
})
```

:::

同理，你可以使用 `defineAppJson`、`definePageJson`、`defineSitemapJson`、`defineThemeJson` 等帮助函数（详见 `@/snippets/export-json.ts`）。

> \[!WARNING]
> 这些 `defineXXX` 函数只提供类型辅助，不会自动补齐字段。例如组件配置仍需显式写出 `"component": true`。

## 获得类型提示

`weapp-vite/json` 导出了多种类型定义，支持直接在 TypeScript 或 JSDoc 中使用。

::: code-group

```ts [navigation-bar.json.ts]
import type { Component } from 'weapp-vite/json'

export default <Component>{
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
}
```

```js [navigation-bar.json.js]
/**
 * @type {import('weapp-vite/json').Component}
 */
export default {
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
}
```

:::

更多导出类型可在 `@/snippets/export-json-type.ts` 中查看。

## 组合与复用配置

使用脚本后，可以像写普通模块一样组合配置、引入别名路径：

```ts
import type { Page } from 'weapp-vite/json'
import sharedTheme from '@/assets/shared.config'
import sharedLocal from './shared.json.ts'

export default <Page>{
  usingComponents: {
    't-button': 'tdesign-miniprogram/button/button',
    't-divider': 'tdesign-miniprogram/divider/divider',
    'ice-avatar': '@/avatar/avatar',
  },
  ...sharedTheme,
  ...sharedLocal,
}
```

* `@/assets/shared.config` 通过别名引入，weapp-vite 会根据 `tsconfig.json` 的 `baseUrl` 和 `paths` 自动解析。
* 多个配置对象会被合并后再输出到最终的 `page.json`。

## 提示与最佳实践

* 优先使用 `jsonc`：需要简单注释时，`jsonc` 就足够；当出现跨模块复用、条件拼装时再升级到 `json.ts`。
* 保持纯函数：尽量让 `json.ts` 导出的对象保持幂等，避免引入与构建环境相关的副作用。
* 配合 `lint-staged`：如果团队使用格式化工具，记得把 `.json.ts`、`.json.js` 也纳入格式化与校验流程。

---

---
url: /deep/scan.md
---
# 依赖分析扫描流程

当 weapp-vite 启动构建或监听时，会先确定哪些文件属于入口，然后递归分析它们之间的引用关系。理解这一流程有助于调试“页面没有被构建”“组件样式缺失”等问题。本页以文字和示意图梳理扫描逻辑，方便贡献者和高级用户参考。

## 入口类型判定

1. **应用入口（App）**
   * 默认查找 `app.json`（支持 `.json/.jsonc/.json.ts/.json.js`），并解析其中的 `pages`、`subPackages`、`usingComponents` 作为后续扫描起点。
   * 入口脚本优先解析 `app.ts/js`；若不存在则回退到 `app.vue`，并尝试从 `<json>` 提取配置。
2. **页面入口（Page）**
   * 由 `app.json.pages` / `subPackages.pages` 提供的路径决定（若路径无扩展名，会优先解析到 `.vue`，其次是 `.ts/.js`）。
   * 若同目录存在 `page.json` / `page.wxss` / `page.wxml` 会一并纳入构建；`.vue` 内的 `<json>` 也可作为页面配置来源。
3. **组件入口（Component）**
   * 来自 `usingComponents` / 自动导入 / `<script setup>` 自动注册。
   * 组件通常具备 `*.json` 且 `component: true`；缺失时可从 `.vue` 中的 `<json>` 提取。
4. **WXML 片段（Fragment）**
   * 通过 `import` / `include` 引入的 `.wxml` 文件。
   * 动态拼接路径不会被静态分析捕获，需保证模板能被固定路径引用或在构建阶段手动补充产物。

## 引用边与递归规则

* App → Page：来自 `app.json.pages`。
* App → Component：来自 `app.json.usingComponents`。
* App → SubPackage：来自 `app.json.subPackages`。（分包内再递归页面与组件。）
* Page → Component：来自页面 `json` 的 `usingComponents`。
* Component → 子组件：同样来自组件 `json` 的 `usingComponents`。

weapp-vite 使用静态分析完成上述递归，因此运行时动态拼接的路径不会被自动识别。

```mermaid
---
title: weapp-vite 依赖扫描流程
---
flowchart TB
App -- pages --> Page
App -- usingComponents --> Component
App -- subPackages --> SubPackage
SubPackage -- pages --> Page
Page -- usingComponents --> Component
Component -- usingComponents --> Component
```

## 调试建议

* **确认入口是否完整**：缺少 `.json` 或 `json.component === true` 会导致节点被跳过。
* **关注静态路径**：尽量避免在运行时拼接 `import` 路径；若必须使用，建议提供固定入口或自定义构建脚本补充产物。
* **结合 `weapp.debug`**：使用 [`watchFiles`、`resolveId`](/config/shared.md#weapp-debug) 查看是否扫描到对应文件，快速定位异常。

---

---
url: /guide/chunks.md
---

# 共享 Chunk 策略（weapp.chunks）

`weapp.chunks` 用于控制 **复用模块的输出位置和形态**，常用于分包优化、避免不必要的 `common.js`、或减少重复体积。

你可以把它理解成两层策略：

* **sharedStrategy**：共享模块“落在哪里”（主包 vs 分包）。
* **sharedMode**：共享模块“长什么样”（common.js / 按路径 / 内联）。

## 基础示例

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

export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'common',
      dynamicImports: 'preserve',
      logOptimization: true,
    },
  },
})
```

## sharedStrategy：共享模块落盘策略

* `duplicate`（默认）：跨分包共享模块复制到各自分包，避免分包首开时回主包取依赖。
* `hoist`：共享模块统一提到主包，减少重复体积。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'hoist',
    },
  },
})
```

## sharedMode：共享模块输出形态

### 1) common（默认）

共享模块会汇总为 `common.js`，入口会自动改写引用该文件。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'common',
    },
  },
})
```

### 2) path（按源码路径输出）

共享模块按源码相对路径输出，避免 `common.js`，同时保持路径稳定。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'path',
      sharedPathRoot: 'src',
    },
  },
})
```

### 3) inline（禁用共享 chunk）

复用模块会被内联到引用方，完全不生成共享 chunk。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'inline',
    },
  },
})
```

## sharedOverrides：针对模块覆盖输出形态

你可以为特定目录或模块设置不同的 `sharedMode`：

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'common',
      sharedOverrides: [
        { test: 'components/**', mode: 'path' },
        { test: /legacy\//, mode: 'inline' },
      ],
    },
  },
})
```

* `test` 支持 glob 字符串或正则表达式
* 匹配基于 `srcRoot` 相对路径或绝对路径

## sharedPathRoot：路径型共享输出的根目录

当 `sharedMode = 'path'` 时，`sharedPathRoot` 用于计算输出路径的根目录（相对 `cwd`）。

* 未设置时默认使用 `srcRoot`
* 若设置的目录不在 `srcRoot` 内，构建会自动回退到 `srcRoot`

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedMode: 'path',
      sharedPathRoot: 'src/shared',
    },
  },
})
```

## dynamicImports：动态 import 的处理方式

* `preserve`（默认）：保留独立的动态 chunk。
* `inline`：尽量内联动态 import，减少额外 chunk。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      dynamicImports: 'inline',
    },
  },
})
```

## forceDuplicatePatterns：强制复制共享模块

当共享模块的直接导入方命中这些规则时，即使主包也引用该模块，仍会按 `duplicate` 策略复制到分包：

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      forceDuplicatePatterns: ['action/**', /services\//],
    },
  },
})
```

## duplicateWarningBytes：冗余体积告警

当共享模块复制后的冗余体积超过阈值时输出警告：

```ts
export default defineConfig({
  weapp: {
    chunks: {
      duplicateWarningBytes: 768 * 1024,
    },
  },
})
```

设置为 `0` 或 `undefined` 可关闭提醒。

## logOptimization：输出优化日志

启用后会在构建日志中输出共享模块的复制/回退信息，便于确认策略是否生效。

```ts
export default defineConfig({
  weapp: {
    chunks: {
      logOptimization: true,
    },
  },
})
```

## 组合示例：禁用 common.js 并保持路径

```ts
export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'path',
      sharedPathRoot: 'src',
      dynamicImports: 'preserve',
    },
  },
})
```

这样会避免生成 `common.js`，同时让共享模块保持与源码一致的相对路径。

---

---
url: /config/shared.md
---
# 共享配置 {#shared-config}

除了 WXML/WXS 这些“底层开关”，`weapp-vite` 还有一些通用增强能力：比如自动路由、调试钩子等。这页主要讲：

* `weapp.autoRoutes`：生成路由清单与类型，供 `app.json.ts` 或业务代码使用
* `weapp.debug`：遇到“为什么没扫描到 / 为什么没输出”时怎么定位

组件自动导入已经拆到 [自动导入组件配置](/config/auto-import-components.md) 单独说明。

\[\[toc]]

## `weapp.autoRoutes` {#weapp-autoroutes}

* **类型**：`boolean`
* **默认值**：`false`
* **适用场景**：
  * 希望从目录结构自动生成 `pages` 清单，不再手动维护 `app.json.pages`。
  * 希望在 TypeScript 里拿到“页面路径”的类型提示，避免字符串拼错。

### 配置示例

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

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

开启后 weapp-vite 会：

* 持续扫描主包和分包下的页面目录，维护 `routes`、`entries`、`pages`、`subPackages` 等清单；
* 在配置文件同级输出 `typed-router.d.ts`，提供 `AutoRoutes` 等类型；
* 自动暴露虚拟模块 `weapp-vite/auto-routes`，支持在代码中直接导入最新的路由数据。

> \[!NOTE]
> 自动路由只扫描 `srcRoot` 下的 `pages/` 目录（含 `packages/foo/pages` 这类分包结构），**不支持 `include/exclude` 自定义规则**。若目录结构完全不同，请继续手写 `app.json.pages`，或在 `app.json.ts` 中手动引入 `weapp-vite/auto-routes` 生成页面清单。

## `weapp.debug` {#weapp-debug}

* **类型**：
  ```ts
  {
    watchFiles?: (files: string[], meta?: SubPackageMetaValue) => void
    resolveId?: (id: string, meta?: SubPackageMetaValue) => void
    load?: (id: string, meta?: SubPackageMetaValue) => void
    inspect?: WrapPluginOptions
  }
  ```
* **适用场景**：排查“监听了哪些文件”“模块是怎么解析的”“某个文件有没有走到预期插件”“产物为什么没生成”等问题。

### 调试示例

```ts
export default defineConfig({
  weapp: {
    debug: {
      watchFiles(files, meta) {
        const scope = meta?.subPackage.root ?? 'main'
        console.info(`[watch:${scope}]`, files)
      },
      resolveId(id) {
        if (id.includes('lodash')) {
          console.log('[resolveId]', id)
        }
      },
      load(id) {
        if (id.endsWith('.wxml')) {
          console.log('[load wxml]', id)
        }
      },
      inspect: { hooks: 'all', threshold: 16 },
    },
  },
})
```

* `watchFiles`: 构建结束时返回监听到的文件，可区分主包与分包。
* `resolveId`: 追踪模块解析路径，适合定位别名、入口解析或分包引用问题。
* `load`: 监听模块加载，常用于确认模板、脚本等是否经过预期的转换。
* `inspect`: 基于 `vite-plugin-performance` 的 `wrapPlugin` 能力，记录插件钩子的耗时与调用情况（默认输出到控制台）。

### 常见调试技巧

1. **确认分包有没有参与构建**：用 `watchFiles` 看看独立分包的 `miniprogram_npm` 是否生成、文件是否被监听到。
2. **定位构建卡顿**：在 `resolveId` / `load` 里打时间戳，快速找出慢的模块或目录。
3. **排查组件自动导入**：组件没被识别时，先确认 `.json` 是否包含 `component: true`，再看 `autoImportComponents.globs` 是否命中。

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

* **类型**：`WevuDefaults`
* **作用**：在编译 `app.vue` 时自动注入 `setWevuDefaults()`，统一控制 wevu 的 `createApp/defineComponent` 默认值。
* **适用场景**：
  * 希望全局配置 `setData` 策略（例如 `includeComputed` / `strategy`）。
  * 希望统一小程序 `Component` 选项默认值（例如 `options.addGlobalClass`）。

### 配置示例

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

export default defineConfig({
  weapp: {
    wevu: {
      defaults: {
        app: {
          setData: {
            includeComputed: false,
            strategy: 'patch',
          },
        },
        component: {
          options: {
            addGlobalClass: true,
          },
          setData: {
            strategy: 'patch',
          },
        },
      },
    },
  },
})
```

### 注意事项

* 仅对 `app.vue` 生效：weapp-vite 会在编译产物中插入 `setWevuDefaults()`，并确保它在 `createApp()` 之前执行。
* 配置必须可序列化（JSON 兼容）：不支持函数、`Symbol`、循环引用。
* 局部显式配置会覆盖默认值；`setData` 与 `options` 会做浅合并，其余字段按对象顶层合并。
* 若你希望手动控制时机，可以在 `app.vue` 顶层显式调用 `setWevuDefaults()`，并关闭此配置以避免重复注入。
* 当 `app.vue`/组件导出为对象字面量时，weapp-vite 会把默认值直接合并进编译产物，方便排查与调试；若导出是变量或函数，仍会回落到运行时合并。
* 若设置了 `component.options.virtualHost = true`，weapp-vite 会在 **页面** 入口自动补上 `virtualHost: false`，避免页面虚拟节点导致的渲染层错误；需要为页面开启时请在页面内显式配置。

> \[!TIP]
> 如果你不通过 weapp-vite 构建，也可以在运行时手动调用 `setWevuDefaults()`（见 `/wevu/runtime`）。

## `weapp.hmr.sharedChunks` {#weapp-hmr-sharedchunks}

* **类型**：`'full' | 'auto' | 'off'`
* **默认值**：`'auto'`
* **适用场景**：开发态 HMR 时控制共享 chunk 的重建策略。

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

export default defineConfig({
  weapp: {
    hmr: {
      sharedChunks: 'auto',
    },
  },
})
```

* `full`: 每次更新都重新产出全部 entry（最稳、最慢）。
* `auto`: 只在共享 chunk 可能被覆盖时回退 full（折中）。
* `off`: 仅更新变更 entry（最快，但可能导致共享 chunk 导出不一致）。

## `weapp.hmr.touchAppWxss` {#weapp-hmr-touchappwxss}

* **类型**：`boolean | 'auto'`
* **默认值**：`'auto'`
* **适用场景**：开发态构建结束后，额外触碰 `app.wxss`，触发微信开发者工具的热重载。

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

export default defineConfig({
  weapp: {
    hmr: {
      touchAppWxss: 'auto',
    },
  },
})
```

* `true`: 总是启用。
* `false`: 关闭。
* `auto`: 检测到安装 `weapp-tailwindcss` 时启用。

## `weapp.chunks` {#weapp-chunks}

* **类型**：`ChunksConfig`
* **适用场景**：控制跨分包共享代码如何输出，降低重复体积或减少主包依赖。

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

export default defineConfig({
  weapp: {
    chunks: {
      sharedStrategy: 'duplicate',
      sharedMode: 'common',
      sharedOverrides: [{ test: 'components/**', mode: 'path' }],
      sharedPathRoot: 'src',
      dynamicImports: 'preserve',
      logOptimization: true,
      forceDuplicatePatterns: ['components/**', /legacy\//],
      duplicateWarningBytes: 512 * 1024,
    },
  },
})
```

字段说明：

* `sharedStrategy`: `duplicate`（默认）复制到各分包，或 `hoist` 提到主包。
* `sharedMode`: `common`（默认）输出 `common.js`，`path` 按源码路径输出，`inline` 内联到引用方。
* `sharedOverrides`: 针对特定模块覆盖 `sharedMode` 的规则数组（`test` 支持字符串或正则）。
* `sharedPathRoot`: `sharedMode: 'path'` 时用于计算输出路径的根目录（相对 `cwd`）。
* `dynamicImports`: `preserve`（默认）保留动态 chunk，`inline` 尝试内联动态 import。
* `logOptimization`: 输出分包优化日志，帮助确认复制/回退位置。
* `forceDuplicatePatterns`: 强制按分包复制的模块匹配规则（字符串或正则）。
* `duplicateWarningBytes`: 冗余体积超过阈值时发出警告；设置为 `0` 关闭。

详细用法与示例请参考：[共享 Chunk 策略](/guide/chunks)。

## 关联阅读

* [WXML 配置](/config/wxml.md)：了解模板增强与组件扫描的协作方式。
* [WXS 配置](/config/wxs.md)：掌握脚本增强开关与调试方法。
* [npm 配置](/config/npm.md)：在调试过程中同时控制 npm 构建策略。

---

---
url: /wevu/compatibility.md
---

# 兼容性与注意事项

这页用于快速排雷：哪些能力能用、有哪些限制是小程序环境带来的，以及哪些点最容易踩坑。

* **运行环境**：wevu 依赖 `Proxy` / `WeakMap` / `Symbol` 等能力，建议微信小程序基础库 ≥ 3.0.0；模板/样式/配置通常配合 weapp-vite 构建产物使用。
* **无 DOM/浏览器 API**：不要使用 `window`/`document`，请使用小程序原生能力（如 `wx.request`）。
* **defineComponent 的前提**：`defineComponent()` 会直接调用全局 `Component()`，请确保代码在小程序运行时执行（或测试环境自行 stub）。
* **createApp 的行为**：`createApp()` 只会在检测到全局 `App()` 时自动注册；否则仅返回运行时对象，适用于测试或自定义适配。
* **生命周期钩子约束**：所有钩子必须在 `setup()` 同步阶段调用；分享/收藏/退出状态等“返回值型钩子”为单实例（后注册覆盖先注册）。
* **页面事件按需派发**：如 `onPageScroll`/分享/朋友圈/收藏等，只有定义了对应页面方法才会触发；wevu 也仅在你定义了这些页面方法时桥接 `setup()` 中注册的同名 hooks。
* **Vue 别名的差异**：`onBeforeMount/onBeforeUnmount` 在 `setup()` 同步阶段立即执行；`onBeforeUpdate/onUpdated` 会在每次 `setData` 前/后触发（用于补齐“小程序缺少更新生命周期”的语义）。
* **Provide/Inject 的限制**：当前版本没有组件树父子指针，`inject()` 不会向上查找祖先组件；组件内只会命中“当前实例提供的值”，否则回落到全局存储。
* **watch 深度策略**：`deep` 默认采用“版本信号”策略（不做深层遍历），可通过 `setDeepWatchStrategy('traverse')` 切换为遍历策略。
* **setData diff 规则**：缺失字段与 `undefined` 会被归一化为 `null`；运行时只下发 state + computed 的差量路径；`setData()` 返回 Promise 时会吞掉 reject 以避免阻塞更新链路。
* **组件与模板规则**：小程序组件必须声明 `usingComponents`（可写在 `<json>`，也可用 Script Setup JSON 宏注入）；`@tap`、`v-if`、`v-for` 等语法由编译侧（如 weapp-vite）转换为 WXML。
* **样式**：输出为 `wxss`；即使使用 SFC 的 `scoped`，仍需遵守小程序样式能力与选择器限制。

---

---
url: /guide/subpackage.md
---
# 分包指南

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

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

如果你需要原理级配置（`weapp.subPackages`、`weapp.chunks` 等），请继续阅读 [配置文档 · 分包配置](/config/subpackages.md) 与 [配置文档 · Worker 配置](/config/worker.md)。

先记住 3 句话：

* **只想开启分包**：直接沿用官方 `app.json.subPackages` 写法即可，weapp-vite 会识别并按分包输出。
* **想共享主题/基础样式**：用 [`weapp.subPackages[].styles`](/config/subpackages.md#subpackages-styles) 交给构建器注入，别手写一堆相对路径 `@import`。
* **想控制共享代码怎么落盘**：关注 `weapp.chunks.sharedStrategy`（`duplicate` vs `hoist`）。

官方说明可参考：[分包加载 - 微信官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages.html)。以下内容聚焦于 `weapp-vite` 的行为和调优手段。

::: tip 分包配置入口
通过 [`weapp.subPackages`](/config/subpackages.md#weapp-subpackages) 可以为每个 `root` 单独开启独立编译、裁剪 `dependencies` 或注入 `inlineConfig`。当需要强制开启独立分包、给特定分包设置额外的 `define`、或为某些分包关闭自动组件导入时，优先在 `vite.config.ts` 中调整该项。
:::

> \[!NOTE]
> 文档里提到的 **Rolldown** 是 `weapp-vite` 内置的打包器：语法与 Vite/Rollup 插件体系兼容，但针对小程序做了额外的“分包产物分发”优化。你可以把它理解成「为小程序量身定制的 Rollup」；同一个 Rolldown 上下文意味着编译出的模块、样式和资源可以互相复用。

## 普通分包

普通分包会被视为和整个 `app` 是一个整体：主包 + 所有普通分包在**同一个 Rolldown 上下文**里构建，因此“共享/复制模块”这类优化是可行的。

微信运行时的限制（简化版）：

* `packageA` 不能直接 `require` `packageB` 的 JS，但可以引用主包与自身分包内的 JS。（使用“分包异步化”时此限制会放宽）
* `packageA` 不能引用 `packageB` 的模板（WXML），但可以引用主包与自身分包内的模板。
* `packageA` 不能直接使用 `packageB` 的静态资源，但可以使用主包与自身分包内的资源。

### 代码产物的位置

当一段可复用的 JS（例如 `utils`）被不同位置引用时，它最终会被输出到哪里，取决于“引用它的页面/组件”分布在哪里。下面用 `utils` 举例说明：

1. `utils` 只在 `packageA` 内被使用：产物只会出现在 `dist/packageA/` 内。
2. `utils` 同时在 `packageA` 和 `packageB` 内被使用：默认 `duplicate` 策略会把它复制到各分包的 `__shared__/common.js`，避免分包首开时再去拉主包；如果希望统一提炼到主包，请在 `vite.config.ts` 中设置 `weapp.chunks.sharedStrategy = 'hoist'`。
3. `utils` 同时在主包和 `packageA` 内被使用：`utils` 会被提炼到主包中，保证主包可以直接使用。

另外，`node_modules` 中的第三方依赖与 Vite 注入的 `commonjsHelpers.js` 也会参与相同的统计：在默认的 `duplicate` 策略下，它们会随着引用方复制到对应分包；只有在 `sharedStrategy: 'hoist'` 时，这些依赖才会统一落到主包的 `common.js`。

#### 详细示例

下面以 `test/fixtures/subpackage-dayjs` 为例，展示一次真实的分包拆分过程。项目结构与配置精简如下：

```text
src/
  app.ts
  utils/shared.ts                 # 主包与 packageA、packageB 同时引用
  packageA/
    pages/foo.ts                  # 引入 utils/shared.ts，并使用第三方 dayjs
  packageB/
    pages/bar.ts                  # 引入 utils/shared.ts，并使用第三方 dayjs
  workers/index.ts                # （可选）worker 入口

// vite.config.ts
export default defineConfig({
  weapp: {
    subPackages: [
      { root: 'packageA' },
      { root: 'packageB' },
    ],
    chunks: {
      sharedStrategy: 'duplicate',
    },
  },
})
```

构建完成后，测试夹具会分别生成 `dist-duplicate/` 与 `dist-hoist/` 两个目录，核心产物与模块来源对应关系如下：

| 产物位置                                                                                        | 说明                                                                                  |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `dist-duplicate/__weapp_shared__/packageA_packageB/common.js`                                   | `packageA` 与 `packageB` 共同引用的模块（如 `utils/shared.ts`），被标记为虚拟共享块。 |
| `dist-duplicate/packageA/__shared__/common.js`                                                  | 复制自虚拟共享块，供 `packageA` 使用。                                                |
| `dist-duplicate/packageB/__shared__/common.js`                                                  | 复制自虚拟共享块，供 `packageB` 使用。                                                |
| `dist-duplicate/packageA/pages/foo.js`                                                          | 入口被自动改写为 `require('../__shared__/common.js')`。                               |
| `dist-duplicate/packageB/pages/bar.js`                                                          | 入口被自动改写为 `require('../__shared__/common.js')`。                               |
| `dist-duplicate/packageA/__shared__/common.js` / `dist-duplicate/packageB/__shared__/common.js` | 内含 `dayjs` 等来自 `node_modules` 的依赖代码，因为它们仅被两个分包使用。             |
| `dist-hoist/common.js`                                                                          | 切换为 `hoist` 策略后，跨分包共享模块统一落在主包。                                   |
| `dist-hoist/packageA/pages/foo.js` / `dist-hoist/packageB/pages/bar.js`                         | 入口被改写为引用 `../common.js`。                                                     |
| `dist-hoist/app.js`                                                                             | 主包独享的逻辑，仍留在主包目录。                                                      |

若某个共享模块或 `node_modules` 依赖同样被主包引用，则它会被提炼到主包下的 `common.js`。将 `sharedStrategy` 切换为 `duplicate` 时，上述跨分包共享模块（包括 `dayjs` 等第三方依赖）会复制回各自分包的 `weapp-shared/common.js`，以换取更低的冷启动开销。位于某个分包目录下的源码如果被其它分包引用，构建器会直接报错，提示先把该模块移动到主包或公共目录，再进行跨分包共享。

> 提示：主仓库的演示项目 `apps/vite-native` 也在 `packageA` 与 `packageC` 中引入了 `dayjs`，可以结合 `dist` 产物直观观察默认的 `duplicate` 策略与手动切换为 `hoist` 后的差异。

默认的 `duplicate` 策略可以在分包首次打开时避免回到主包拉取共享模块；若更在意控制整体包体、希望统一落到主包，也可以设置 `weapp.chunks.sharedStrategy = 'hoist'`，或结合 [advanced-chunks](https://rolldown.rs/guide/in-depth/advanced-chunks) 做更精细的拆分。

在实际项目中，跨分包共享逻辑往往会抽象到 `src/action/`、`src/services/` 等目录。若这些模块只被分包页面（或其它共享 chunk）间接引用，weapp-vite 会把位于根目录的“伪主包”导入者排除在统计之外，使共享代码仍然复制到各自的 `pages/*/weapp-shared/common.js`。例如下列最小复现：

```ts
// src/pages/index1/index.ts & src/pages/index3/index.ts
import { test1 } from '@/action/test1'

// src/action/test2.ts
import { test1 } from './test1'
```

在旧版本中，`test1` 会因为 `action/test2.ts` 的存在而被迫回退到主包 `common.js`。升级后构建日志会提示：

```
[subpackages] 分包 pages/index1、pages/index3 共享模块已复制到各自 weapp-shared/common.js（2 处引用，忽略主包引用：action/test2.ts）
```

如果扫描阶段拿不到完整的导入图，也可以通过 `weapp.chunks.forceDuplicatePatterns` 手动声明哪些目录始终视为可复制的共享库。

当复制出的共享模块越来越多时，也可以结合 `weapp.chunks.duplicateWarningBytes` 设定冗余体积的提醒阈值（默认约 `512 KB`），超过后构建日志会给出告警，便于提前关注包体膨胀。

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

export default defineConfig({
  weapp: {
    chunks: {
      // 若项目更关注分包首屏性能，可以显式复制共享模块
      sharedStrategy: 'duplicate',
      // 强制忽略 action/ 下的导入方，防止伪主包引用拖回主包 common.js
      forceDuplicatePatterns: ['action/**'],
      // 调整冗余体积告警阈值
      duplicateWarningBytes: 768 * 1024,
    },
  },
})
```

## 独立分包

独立分包和整个 `app` 是隔离的：它们会在**不同的 Rolldown 上下文**里构建，因此不会和主包/其他分包共享复用的 JS 代码。

* **独立分包不能依赖主包和其他分包的内容**，包括 JS、模板、WXSS、自定义组件、插件等。（使用“分包异步化”时，JS/自定义组件/插件会放宽）
* 主包的 `app.wxss` 对独立分包无效：不要依赖主包全局样式。
* `App` 只能在主包里定义：独立分包里不要定义 `App()`，否则行为不可预期。
* 独立分包中暂时不支持使用插件。

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

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

1. 在 `app.json` 里把目标分包标记为 `independent: true`（并确保分包 `pages` 指向你要调试的页面）：

```jsonc
// src/app.json
{
  "pages": ["pages/index/index"],
  "subPackages": [
    {
      "root": "packages/order",
      "pages": ["pages/index", "pages/detail"],
      "independent": true,
      // 可选：分包级入口（基于 root 的相对路径），用于放分包初始化逻辑
      "entry": "index.ts"
    }
  ]
}
```

2. 在 `vite.config.ts` 里为该 `root` 配置 `weapp.subPackages`（关键是 `independent` + `dependencies`，其余按需）：

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

export default defineConfig({
  weapp: {
    subPackages: {
      'packages/order': {
        independent: true,
        inlineConfig: {
          // 在这里添加独立分包的大包配置
          define: {
            'import.meta.env.ORDER_DEV': JSON.stringify(true),
          },
        },
      },
    },
  },
})
```

> \[!TIP]
> 如果你不想把“独立分包开发”的配置长期留在主配置里，可以单独新建一个 `vite.config.order.ts`，再用 `weapp-vite dev -c vite.config.order.ts` 运行；生产构建仍用默认的 `vite.config.ts`。

## 分包样式共享

[`weapp.subPackages[].styles`](/config/subpackages.md#subpackages-styles) 能把重复的 `@import` 交还给构建器处理：声明一次主题、设计令牌或基础布局，普通分包与独立分包都会在生成样式时自动插入对应的共享入口。

> \[!TIP]
> 分包根目录下若存在 `index.*` / `pages.*` / `components.*`（默认扫描 `.wxss`/`.css`），weapp-vite 会自动识别它们作为共享入口，零配置即可复用。

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

export default defineConfig({
  weapp: {
    subPackages: {
      'packages/member': {
        // 普通分包：共享主题变量和页面级样式
        styles: [
          'styles/tokens.css',
          { source: 'styles/layout.wxss', scope: 'pages' },
        ],
      },
      'packages/offline': {
        independent: true,
        // 独立分包：会在独立上下文重新编译并注入 @import
        styles: [
          {
            source: 'styles/offline-theme.scss',
            include: ['pages/**/*.wxss', 'components/**/*.wxss'],
          },
        ],
      },
    },
  },
})
```

* 普通分包与主包共享 Rolldown 上下文，样式产物只生成一次，并在分包页面/组件头部自动注入 `@import`。
* 独立分包会在专属上下文重新编译同一份源文件，保持样式同步且无需手动维护相对路径。
* `scope` / `include` / `exclude` 可精准控制注入范围，配合 HMR 调试体验与主包一致。

更多细节（如产物位置与对象写法）可查看[配置文档 · 样式共享实战](/config/subpackages.md#subpackages-styles)。

### 调试建议

1. 确认 `app.json` 中的 `independent: true` 是否与 `vite.config.ts` 中的 `weapp.subPackages` 保持一致。
2. 利用 `weapp.debug.watchFiles` 查看产物位置，确认独立分包是否生成独立的 `miniprogram_npm`。
3. 如果分包引用到了主包路径，构建会报错提示，请及时调整引用方式或拆分公共模块。

### 分析产物布局

若要快速核对“哪些源码最终落到了主包 / 分包 / 共享 chunk”，可以在 `package.json` 中添加脚本：

```json
{
  "scripts": {
    "analyze": "weapp-vite analyze"
  }
}
```

然后执行：

```bash
pnpm run analyze
```

命令会读取当前 `vite.config.ts` 与 `app.json` 配置，进行一次只在内存写入的打包，并输出：

* 每个主包或分包包含的 chunk / 资源数量；
* 跨包复用、被复制到共享 chunk 的源码列表；
* `app.json` 中声明的分包及其 `independent` 状态。

需要与其他工具联动时，可以加上 `--json` 输出完整的 JSON 结果，或搭配 `--output <file>` 将结果写入磁盘：

```bash
pnpm run analyze -- --json --output report/analyze.json
```

写入文件时会自动创建缺失的目录，路径默认为相对项目根目录。JSON 中同时包含主包、各分包、虚拟共享 chunk 与源码映射的详细信息，可直接用于体积分析或预警脚本。

## 常见问题

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

---

---
url: /config/subpackages.md
---
# 分包配置 {#subpackages-config}

`weapp-vite` 会读取 `app.json.subPackages` 来生成分包产物；`weapp.subPackages` 则用于 **构建期补充配置**（独立分包、依赖裁剪、共享样式等）。

\[\[toc]]

## `weapp.subPackages` {#weapp-subpackages}

* **类型**：
  ```ts
  Record<string, {
    independent?: boolean
    dependencies?: (string | RegExp)[]
    inlineConfig?: Partial<InlineConfig>
    autoImportComponents?: AutoImportComponents | false
    watchSharedStyles?: boolean
    styles?: SubPackageStyleConfigEntry | SubPackageStyleConfigEntry[]
  }>
  ```
* **默认值**：`undefined`

示例：

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

export default defineConfig({
  weapp: {
    subPackages: {
      marketing: {
        independent: true,
        dependencies: [/^tdesign-miniprogram/],
        autoImportComponents: false,
        styles: [
          'styles/shared.wxss',
          { source: 'styles/pages.wxss', scope: 'pages' },
        ],
      },
    },
  },
})
```

### 字段说明

* `independent`：启用 **独立分包构建上下文**。常与 `app.json` 中的 `independent: true` 搭配使用。
* `dependencies`：**独立分包 npm 依赖裁剪**。用于从主包构建好的 `miniprogram_npm` 中筛选子集。
* `inlineConfig`：为该分包注入额外 Vite 配置（Rolldown/Rollup 插件、define 等）。
* `autoImportComponents`：为该分包单独配置/禁用自动导入。
* `watchSharedStyles`：分包文件变更时是否强制重新生成共享样式（默认 `true`）。
* `styles`：分包共享样式入口，详见下文。

> \[!NOTE]
> `weapp.subPackages` 的 key 必须与 `app.json.subPackages[].root` 对应，否则不会生效。

## `subPackages.*.styles` {#subpackages-styles}

**类型**：`string | SubPackageStyleConfigObject | (string | SubPackageStyleConfigObject)[]`

`SubPackageStyleConfigObject` 结构：

```ts
{
  source: string
  scope?: 'all' | 'pages' | 'components'
  include?: string | string[]
  exclude?: string | string[]
}
```

说明：

* `source` 支持 **相对分包 root / 相对 srcRoot / 绝对路径**。
* `scope` 提供快捷范围：
  * `all`（默认）分包内所有页面/组件
  * `pages` 仅 `pages/**`
  * `components` 仅 `components/**`
* `include/exclude` 用于精确匹配（基于分包 root 的相对路径）。

***

更多分包实践与产物示例，请阅读 [分包指南](/guide/subpackage)。

---

---
url: /guide/alias.md
---
# 别名 {#alias}

`weapp-vite` 同时支持 **JS/TS 别名** 与 **JSON/JSONC 别名**，让你在脚本和配置文件里都能用同一套路径前缀。本页先给出最常见的配置方式，再补充一些使用建议；更细的字段说明请参考 [配置文档 · JSON 配置](/config/json.md) 与 [配置文档 · JS 配置](/config/js.md)。

## 适用场景

* 统一业务组件、工具方法的导入路径，避免深层级的 `../../`。
* 让 JSON 配置和 TypeScript 源码共享同一套别名，减少路径维护成本。
* 按团队约定快速切换不同的路径前缀（如 `@components/*`、`@shared/*`）。

设置完成后，Vite Dev Server 与小程序产物都会自动替你做路径转换，不需要在不同环境下手动调整。

## JS/TS 别名

项目默认启用了 `vite-tsconfig-paths`，所以你只要在 `tsconfig.json` / `jsconfig.json` 里配置 `baseUrl` 和 `paths`，就能在代码中直接使用别名。

例如：

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

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

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

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

> \[!TIP]
> 如果需要控制 `vite-tsconfig-paths` 的行为（例如指定多个 `tsconfig` 或忽略某些目录），可在 `vite.config.ts` 中调整 [`weapp.tsconfigPaths`](/config/js.md#weapp-tsconfigpaths)。

## JSON / JSONC 别名

`weapp-vite` 对所有 JSON 配置文件做了增强，既允许使用注释，也支持别名映射，帮助你更好地组织大型项目。

首先，`weapp-vite` 允许你在应用/页面/组件的 `json/jsonc` 文件里写注释，例如：

* `// 这是注释`
* `/* 这也是注释 */`

```json
{
  "pages": [
    // 首页
    "pages/index/index"
  ],
  "usingComponents": {
    // 全局组件
    "navigation-bar": "/components/navigation-bar/navigation-bar"
  },
  "subPackages": [
    // 分包 A
    {
      "root": "packageA",
      "name": "pack1",
      "pages": [
        "pages/cat",
        "pages/dog"
      ]
    },
    // 分包 B 是独立分包
    {
      "root": "packageB",
      "name": "pack2",
      "pages": [
        "pages/apple",
        "pages/banana"
      ],
      // "entry": "index.js",
      // 独立分包应该特殊处理, 单独创建上下文
      "independent": true
    }
  ]
}
```

这些注释不会触发构建错误，并会在产物阶段被剔除。

要启用 JSON 别名，可在 `vite.config.ts` 中配置 [`weapp.jsonAlias.entries`](/config/json.md#weapp-jsonalias)。语法与 Vite 的 `resolve.alias` 完全一致：

> `weapp.jsonAlias.entries` 配置项传入的参数，同原先 `vite` 的 `resolve.alias` 配置项，[详见地址](https://vite.dev/config/shared-options.html#resolve-alias)

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

export default <UserConfig>{
  weapp: {
    jsonAlias: {
      entries: [
        {
          find: '@',
          replacement: path.resolve(import.meta.dirname, 'components'),
        },
      ],
    },
  },
}
```

配置完成后，就可以在 `usingComponents` 中直接书写别名（仅该字段会被重写）：

```json
{
  "usingComponents": {
    "navigation-bar": "@/navigation-bar/navigation-bar",
    "ice-avatar": "@/avatar/avatar"
  }
}
```

构建时会自动转化成相对路径：

```json
{
  "usingComponents": {
    "navigation-bar": "../../components/navigation-bar/navigation-bar",
    "ice-avatar": "../../components/avatar/avatar"
  }
}
```

最终产物的路径拼装取决于你在 `entries` 中的替换逻辑；如果希望使用绝对路径，也可以直接以 `/` 开头：

```json
{
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar"
  }
}
```

该写法会被解析为项目根目录下的实际文件。

## 常见问题排查

* **别名未生效？** 请确认 `pnpm dev` 重启过——`tsconfig` 修改后需要重新启动进程，Rolldown 才能读取新的 `paths`。
* **JSON 中提示路径不存在？** 开发者工具的校验不理解别名是正常现象，编译产物仍会替换为真实路径。若想在 IDE 内消除警告，可借助自定义类型定义或在 `usingComponents` 上方写注释标记。
* **同时使用多个 `tsconfig`？** 可以在 `vite.config.ts` 中配置 [`weapp.tsconfigPaths.projects`](../config/js.md#weapp-tsconfigpaths) 指定额外的配置文件，让 monorepo 子包共享同一套别名。

---

---
url: /community/group.md
---
# 加入技术交流群

如果你在使用中遇到什么问题，也欢迎你进入交流群进行提问。提问时请尽量携带最小复现案例，我们会更快定位问题。

:::tip
注意⚠️: 添加时注明来自 `GitHub: weapp-vite` 项目
:::

> \[!NOTE]
> 参与社区交流时，请遵守项目的 [行为准则](https://github.com/weapp-vite/weapp-vite/blob/main/CODE_OF_CONDUCT.md) 与 Issue 模板，一起维护良好的讨论氛围。

> \[!IMPORTANT]
> 为了确保二维码与入群指引保持最新，请访问 [社区交流群指南](https://tw.icebreaker.top/docs/community/group)。按照文档提示即可加入微信或 QQ 群。

---

---
url: /packages/rolldown-require/cache.zh.md
---
# 加载流程与缓存策略

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

本文梳理 `bundleRequire` 在内部如何打包、落盘与加载，并介绍缓存相关的实用配置。

## 整体流程

1. **解析入口**：根据 `filepath` 与 `cwd` 生成绝对路径，并用后缀/`package.json.type` 推断 `format`（可手动覆盖）。
2. **rolldown 打包**：
   * 固定 `platform: 'node'`、`inlineDynamicImports: true`、`treeshake: false`，保证生成单入口产物并完整收集依赖。
   * 注入 `__dirname`/`__filename`/`import.meta.url`，让运行时代码感知源文件真实路径。
   * 通过 `externalize-deps` 插件外部化大部分 `node_modules` 依赖，同时保留 JSON 内联；尊重 `module-sync` 条件导出。
3. **执行临时产物**：
   * ESM：写入临时 `.mjs`/`.cjs` 或 data URL，再用 `import()` 加载。
   * CJS：通过 `_require.extensions` 临时钩子编译源文件。
4. **结果返回**：提供 `mod` 与 `dependencies`（包含入口以外的打包依赖）便于监听或调试。

## 外部化与解析

* 解析行为与 Vite/rolldown 对齐：使用相同的主字段优先级与 `tsconfig` 路径解析（若未禁用）。
* Node 内置与 `node:`/`npm:` 命名空间依赖会被直接标记为 external。
* 若依赖处于入口目录下的嵌套 `node_modules` 中，为保证临时产物可执行，会自动内联而非 external。
* JSON 资源暂不外部化，始终交给 rolldown 处理。

## 临时产物控制

* 默认写入最近的 `node_modules/.rolldown-require`，找不到时退回系统临时目录；文件名会包含随机哈希，避免并发冲突。
* 通过 `getOutputFile` 可自定义写入路径；`preserveTemporaryFile` 设为 `true` 时不会自动清理，便于直接查看产物。
* 若所有落盘尝试失败且目标为 ESM，会回退到 `data:` URL 写入。

## 缓存策略

缓存默认关闭。`cache: true` 或传入对象即可开启，包含持久化与进程内缓存：

* **缓存位置**：默认选择最近的 `node_modules/.rolldown-require-cache`，否则使用 `os.tmpdir()/rolldown-require-cache`。可通过 `cache.dir` 指定。
* **缓存键**：入口路径、`mtime`/`size`、`format`、`tsconfig` 路径、Node 版本以及 `rolldownOptions` 摘要共同决定。
* **有效性校验**：在命中缓存后，会逐个比对入口与依赖的 `mtime`/`size`；任意文件变化即视为失效。
* **内存缓存**：默认开启（`cache.memory !== false`），命中后直接返回已加载模块，避免额外的文件系统读写。
* **重置与事件**：
  * `cache.reset: true` 会在写入前清理旧的 code/meta 文件。
  * `cache.onEvent` 可获取 `hit`/`miss`/`store`/`skip-invalid` 事件，`skip-invalid` 的 `reason` 可能是 `missing-entry`、`format-mismatch`、`stale-deps` 等。

示例：记录缓存事件并自定义目录

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

## 调试建议

* 监听 `dependencies`，在文件变更后决定是否重新调用 `bundleRequire`。
* 配合 `preserveTemporaryFile: true` 检查生成的临时代码，或在缓存目录里直接比对 `*.code.mjs/cjs`。
* 若需要排查缓存误命中，可临时设置 `cache.reset: true` 或直接关闭缓存。
* 当入口后缀与 `package.json.type` 不匹配时，手动传入 `format` 可以避免 Node/rolldown 解析差异。

---

---
url: /packages.md
---
# 周边包总览

`weapp-vite` 不只是一个构建器，`packages/*` 里还提供了脚手架、CLI、编译器、跨端 API、实验运行时和性能分析工具。

如果你正在做技术选型，可以先看这页，再进入对应子页面。

## 选型建议（先看这个）

* 新建项目：优先用 `create-weapp-vite`
* 在 CI/脚本里调用微信开发者工具：用 `weapp-ide-cli`
* 需要“打包后执行配置文件”：用 `rolldown-require`
* 想追踪 Vite 插件耗时瓶颈：用 `vite-plugin-performance`
* 想在非 Vite 场景复用 Wevu 编译能力：用 `@wevu/compiler`
* 想统一多端小程序 API 调用风格：用 `@wevu/api`
* 想在浏览器里做小程序语法实验运行：用 `@weapp-vite/web`（实验）
* 想学习 MCP 服务封装方式：用 `@weapp-vite/mcp`（示例）
* 想增强 `<json>` 配置块智能提示：用 `@weapp-vite/volar`

## 包能力矩阵

| 包名                      | 定位                                     | 适用场景                       | 文档入口                                                                   |
| ------------------------- | ---------------------------------------- | ------------------------------ | -------------------------------------------------------------------------- |
| `create-weapp-vite`       | 官方脚手架                               | 快速创建模板项目、统一模板版本 | [/packages/create-weapp-vite](/packages/create-weapp-vite)                 |
| `weapp-ide-cli`           | 微信开发者工具 CLI 增强封装              | 本地自动化、CI 预览/上传       | [/packages/weapp-ide-cli](/packages/weapp-ide-cli)                         |
| `rolldown-require`        | 以 Rolldown 为核心的 bundle+require 工具 | 加载 TS/MJS/CJS 配置文件       | [/packages/rolldown-require/index.zh](/packages/rolldown-require/index.zh) |
| `vite-plugin-performance` | Vite 插件 Hook 耗时分析                  | 定位构建慢点、插件调优         | [/packages/vite-plugin-performance](/packages/vite-plugin-performance)     |
| `@wevu/compiler`          | Wevu 编译能力底座                        | 复用 SFC/模板编译管线          | [/packages/wevu-compiler](/packages/wevu-compiler)                         |
| `@wevu/api`               | 跨平台小程序 API 封装                    | Promise 风格统一调用           | [/packages/weapi](/packages/weapi)                                         |
| `@weapp-vite/web`         | Web 端实验运行时与插件                   | 浏览器侧验证小程序语法/页面    | [/packages/web](/packages/web)                                             |
| `@weapp-vite/mcp`         | MCP 示例服务                             | 学习 MCP 工具注册和 stdio 通信 | [/packages/mcp](/packages/mcp)                                             |
| `@weapp-vite/volar`       | Volar 语言插件                           | `<json>` 配置块补全与校验      | [/packages/volar](/packages/volar)                                         |

## 已有独立文档模块

* `weapp-vite` 主包：见 [指引](/guide/) 与 [配置](/config/)
* `wevu` 运行时：见 [wevu 专区](/wevu/)

## 说明

* `rolldown-require-bench` 主要用于基准测试，不建议直接作为业务依赖。
* `@weapp-vite/web`、`@weapp-vite/mcp` 当前更偏实验/示例用途，适合技术验证与学习。

---

---
url: /config/paths.md
---
# 基础目录与资源收集 {#paths-config}

本页涵盖：

1. **源码根目录**（`app.json` 在哪）
2. **插件根目录**（是否同时构建小程序插件）
3. **静态资源收集与复制**（哪些文件会被搬进 `dist/`）
4. **额外 WXML**（可选，当前版本为预留字段）

\[\[toc]]

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

* **类型**：`string`
* **默认值**：项目根目录（`''` 等价于 `.`）
* **适用场景**：`app.json` 不在仓库根目录，或你希望把源码统一放在 `src/`、`miniprogram/` 等目录。

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

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

说明：

* `srcRoot` 会影响 **扫描入口**、**产物路径**、**资源复制** 与 **自动路由** 等行为。
* 构建时会从该目录寻找 `app.json`，找不到会直接报错。

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

* **类型**：`string`
* **默认值**：`undefined`
* **适用场景**：项目中同时维护“小程序插件”，需要一起打包 `plugin.json` 与插件代码。

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

export default defineConfig({
  weapp: {
    srcRoot: '.',
    pluginRoot: './plugin',
  },
})
```

说明：

* `pluginRoot` 指向 `plugin.json` 所在目录。
* 插件产物输出路径会根据 `project.config.json` 的 `pluginRoot`（若有）或构建输出目录自动推导。
* 插件构建与主应用构建复用同一套 alias/TS/依赖处理能力。

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

* **类型**：`{ include?: string[]; exclude?: string[]; filter?: (filePath: string) => boolean }`
* **默认值**：`undefined`
* **适用场景**：把字体/证书/自定义数据等 **非代码资源** 复制到 `dist/`。

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

export default defineConfig({
  weapp: {
    copy: {
      include: ['**/*.ttf', '**/*.cer'],
      exclude: ['**/examples/**'],
      filter(filePath) {
        return !filePath.includes('README')
      },
    },
  },
})
```

行为说明：

* 默认会收集常见静态资源后缀（如 `png/jpg/svg/mp3/mp4/wasm`），并排除 `node_modules`、`miniprogram_npm`、`.wevu-config` 等目录。
* `include` / `exclude` 是 glob 列表，匹配范围基于 `srcRoot`（主应用）或 `pluginRoot`（插件构建）。
* `filter` 会在 glob 命中后再次过滤。

> \[!TIP]
> Vite 的 `public/` 目录仍会被原样复制。如果资源已经放在 `public/`，通常不需要再配置 `weapp.copy`。

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

* **类型**：`(wxmlFilePath: string) => boolean`
* **默认值**：`() => false`
* **状态**：**当前版本为预留字段**（尚未接入扫描/产物流程）。

如果你的项目依赖“运行时动态拼接 WXML 路径”，建议 **改用显式文件引用** 或在构建阶段自行补充产物；该字段目前不会影响构建图谱。

***

下一步：需要构建输出与兼容策略？请前往 [构建输出与兼容](./build-and-output.md)。

---

---
url: /troubleshoot.md
---
# 常见问题排查

遇到构建或运行异常？先从以下问题入手自检，大多数情况都能在几分钟内定位原因。若仍未解决，可携带日志在 Issue 或社区群反馈。

## 启动开发时出现 `EMFILE` / `ENOSPC` 或 `unable to start FSEvent stream`？

* **症状**：执行 `pnpm dev` / `pnpm dev:open` 时报监听相关错误，例如：
  * `EMFILE: too many open files`
  * `ENOSPC: System limit for number of file watchers reached`
  * `unable to start FSEvent stream`
* **原因**：系统文件描述符或文件监听器上限不足，构建器无法继续创建 watch。

### 临时处理（当前终端生效）

macOS / Linux 可先执行：

```bash
ulimit -n 65536
```

然后重新运行 `pnpm dev`。

### 长期处理（推荐）

#### macOS

1. 新建并加载 `launchd` 配置（将软/硬限制都提到 `65536`）：

```bash
sudo tee /Library/LaunchDaemons/limit.maxfiles.plist >/dev/null <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>limit.maxfiles</string>
    <key>ProgramArguments</key>
    <array>
      <string>launchctl</string>
      <string>limit</string>
      <string>maxfiles</string>
      <string>65536</string>
      <string>65536</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>ServiceIPC</key>
    <false/>
  </dict>
</plist>
EOF

sudo launchctl bootstrap system /Library/LaunchDaemons/limit.maxfiles.plist
sudo launchctl enable system/limit.maxfiles
```

2. 重启系统后，用 `ulimit -n` 或 `launchctl limit maxfiles` 检查是否生效。

#### Linux（inotify 上限）

```bash
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
echo fs.inotify.max_user_instances=1024 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```

### 仍有问题时建议一并检查

1. 是否在同一终端里重复启动了多个 `pnpm dev`；
2. 微信开发者工具是否打开了过多项目；
3. 项目根目录是否包含超大体量临时文件且未被忽略。

## 构建产物里只有 WXML？

* **症状**：`dist/` 中只有 `.wxml`，缺失 `.js`、`.wxss`、`.json`。
* **常见原因**：页面未在 `app.json.pages` 注册，或组件缺少 `json.component = true`。
* **排查步骤**：
  1. 打开 `app.json` 是否包含该页面路径；
  2. 检查组件是否位于 `usingComponents`，以及是否具备同名 `.json`；
  3. 使用 [`weapp.debug.watchFiles`](/config/shared.md#weapp-debug) 输出监听列表确认扫描情况。

> \[!TIP]
> 依赖扫描流程详见 [依赖分析扫描流程](/deep/scan.md)。了解入口判定规则可以更快定位遗漏。

## 目录结构正确仍报 `require()` 错误？

这通常是微信开发者工具缓存造成的。试试：

1. 在开发者工具中临时开启「将 JS 编译成 ES5」，触发一次重新编译；
2. 再关闭该选项并重启工具；
3. 若仍未恢复，可删除项目目录下的 `miniprogram_npm`、`dist` 后重新执行 `pnpm build`。

## 引入 UMD/CJS 模块时报错？

* 例如 `visactor` 的 `index-wx-simple.min.js` 体积较大并依赖 CommonJS，直接 `import` 会导致 ESM 分析失败。
* 解决方案：将文件重命名为 `.cjs` 或在源码中显式 `require()`，提示 bundler 将其按 CommonJS 处理。
* 参考案例：[issue #115](https://github.com/weapp-vite/weapp-vite/issues/115)。

## `custom-tab-bar` 不生效？

确保同时满足两点：

1. `custom-tab-bar/` 文件夹与 `app.json` 位于同级目录（例如二者都在 `src/` 下）。
2. `app.json.tabBar.custom` 设置为 `true`。

> \[!NOTE]
> Skyline 的 [全局工具栏](https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/skyline/appbar.html#%E4%BD%BF%E7%94%A8%E6%B5%81%E7%A8%8B) 也遵循同样的目录要求。

***

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

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

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

---

---
url: /guide/plugin.md
---
# 微信小程序插件开发

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

::: tip TL;DR

1. 在 `vite.config.ts` 中设置 `weapp.pluginRoot` 指向插件目录。
2. 将 `plugin.json`、公共组件与页面放在该目录下，结构与官方要求保持一致。
3. 执行 `pnpm dev` / `pnpm build` 后，`dist-plugin/**` 会生成完整插件包，可直接导入微信开发者工具或配合 `weapp-ide-cli` 上传。
   :::

## 适用场景

* 主应用和插件需要共享工具链、依赖、IDE 提示。
* 想在插件中也享受 auto-import、样式预处理、自动构建 npm 等能力。
* 希望统一构建流程，在 CI 中一次产出应用 + 插件。

## 开启插件目录

```ts [vite.config.mts]
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    srcRoot: 'miniprogram',
    pluginRoot: 'plugin', // plugin.json 所在目录
  },
})
```

`pluginRoot` 可以是相对或绝对路径。`weapp-vite` 会：

* 读取该目录下的 `plugin.json`，自动根据 `main`、`publicComponents`、`pages` 等字段构建入口图；
* 监听插件目录中的 JS/WXML/WXSS 及配置文件，配合主应用实现热更新；
* 在构建阶段将插件产物输出到 `dist-plugin/**`，保持与原目录一致的层级。

若未设置 `pluginRoot`，则插件相关流程不会启用。

## 目录约定

以下是示例仓库（`apps/plugin-demo`）的插件目录结构，可作为参考：

```text
plugin
├── plugin.json
├── index.js           # 插件入口(main)
├── pages
│   └── hello-page
│       ├── hello-page.js
│       ├── hello-page.wxml
│       └── hello-page.wxss
└── components
    └── hello-component
        ├── hello-component.js
        ├── hello-component.json
        ├── hello-component.wxml
        └── hello-component.wxss
```

* 目录和文件命名与微信小程序插件规范完全一致；
* WXSS/WXML 会被在构建时复制到 `dist-plugin/**`，不会再污染源目录；
* 插件的静态资源（图片、字体等）建议放在插件目录下，`weapp-vite` 会一并复制。

## 开发流程

### 启动本地开发

```sh
# monorepo 场景下的示例（apps/plugin-demo）
pnpm --filter plugin-demo dev
# 或在独立项目中：
pnpm dev
```

* 主应用与插件会同时监听并增量构建。
* 插件入口产生的页面/组件同样支持热更新，输出目录为 `dist-plugin/**`。
* 可配合 `pnpm dev --open` 自动拉起微信开发者工具，进行真机或模拟器调试。

### 构建与上传

```sh
pnpm --filter plugin-demo build
```

构建完成后会看到类似结构：

```text
dist/
├── app.js
├── app.json
└── pages/…

dist-plugin/
├── plugin.json
├── index.js
├── pages/hello-page/…
└── components/hello-component/…
```

* 将 `dist` 目录作为项目根导入微信开发者工具即可预览；
* 若只需要上传插件，可根据微信官方要求打包 `dist-plugin` 内容；
* 插件产物会自动同步到 `project.config.json` 中配置的 `pluginRoot` 路径，无需额外脚本。
* 也可以搭配 [`weapp-ide-cli`](https://github.com/weapp-vite/weapp-vite/tree/main/packages/weapp-ide-cli) 实现命令行上传/预览。

## 示例项目

仓库内置了完整示例，可直接参考或复制：

* 路径：`apps/plugin-demo`
* 主要文件：`plugin/plugin.json`、`plugin/components/hello-component/*`、`plugin/pages/hello-page/*`
* 封装了常用脚本：
  ```json
  {
    "scripts": {
      "dev": "weapp-vite dev",
      "dev:open": "weapp-vite dev -o",
      "build": "weapp-vite build",
      "open": "weapp-vite open"
    }
  }
  ```

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

## 常见问题

### 插件 WXSS 没有生成？

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

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

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

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

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

---

---
url: /wevu/quick-start.md
---

# 快速上手 wevu

这页给你一条“最短可跑通”的路线：装包 → 写一个页面/组件 → （可选）接入 Store。示例以 weapp-vite + Vue SFC 为主；如果你不使用 SFC，也可以只参考运行时 API 的用法。

## 1. 安装

```bash
pnpm add wevu
# npm i wevu
# yarn add wevu
# bun add wevu
```

:::tip
运行时 API 均从 `wevu` 主入口导入，无需（也不支持）`wevu/store` 等子路径；`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` 类型提示。
:::

:::note wevu@1.2.0 起的 vue 依赖说明
从 wevu@1.2.0 开始，`wevu` 会依赖 `vue`，但只用于获取其 `dts` 类型定义，不会引入任何 Vue 运行时代码。这样做是为了让 Volar 在 `<script setup>` 下正确解析 `props`、宏类型与 IDE 跳转（此前尝试过多种方案仍无法稳定解决）。业务代码仍应从 `wevu` 导入运行时 API。
:::

## 3. 写一个页面（SFC 示例）

`defineComponent()` 会在运行时通过小程序全局 `Component()` 注册页面/组件；`setup()` 返回的状态会参与快照 diff，并最小化 `setData`。

```vue
<!-- pages/counter/index.vue -->
<script setup lang="ts">
import { computed, onPageScroll, ref } from 'wevu'

definePageJson(() => ({
  navigationBarTitleText: '计数器',
}))

const count = ref(0)
const doubled = computed(() => count.value * 2)
const reachedTop = ref(true)

onPageScroll(({ scrollTop }) => {
  reachedTop.value = scrollTop < 40
})

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

<template>
  <view class="page">
    <text>count: {{ count }} / doubled: {{ doubled }}</text>
    <text v-if="!reachedTop">
      正在滚动...
    </text>
    <button @tap="inc">
      +1
    </button>
  </view>
</template>
```

## 4. 引入自定义组件（小程序规则）

推荐使用 Script Setup JSON 宏声明 `usingComponents`；脚本里无需（也不推荐）`import` 子组件：

```vue
<script setup lang="ts">
definePageJson(() => ({
  usingComponents: {
    'my-card': '/components/MyCard/index',
  },
}))
</script>
```

模板中直接 `<my-card />` 使用即可。

## 5. 组件 props / emit（运行时约定）

`setup` 与 Vue 3 对齐，仅支持 `setup(props, ctx)`。
若不需要 `props`，可写 `setup(_, ctx)`；若不需要 `ctx`，可只写 `setup(props)`。

`ctx.props` 来自小程序 `properties`；`ctx.emit(event, ...args)` 会调用小程序 `triggerEvent` 触发自定义事件。

```vue
<!-- components/Stepper/index.vue -->
<script lang="ts">
import { computed, defineComponent } from 'wevu'

export default defineComponent({
  properties: { modelValue: { type: Number, value: 0 } },
  setup(props, ctx) {
    const value = computed({
      get: () => props.modelValue ?? 0,
      set: v => ctx.emit('update:modelValue', v),
    })
    const inc = () => (value.value += 1)
    const dec = () => (value.value -= 1)
    return { value, inc, dec }
  },
})
</script>
```

```vue
<!-- 使用 -->
<template>
  <Stepper v-model="amount" />
</template>
```

## 6. 接入 Store（可选但常用）

```ts
// stores/counter.ts
import { computed, defineStore, ref } from 'wevu'

export const useCounter = defineStore('counter', () => {
  const count = ref(0)
  const doubled = computed(() => count.value * 2)
  const inc = () => count.value++
  return { count, doubled, inc }
})
```

```ts
// pages/counter/index.ts
import { defineComponent, storeToRefs } from 'wevu'
import { useCounter } from '@/stores/counter'

export default defineComponent({
  setup() {
    const counter = useCounter()
    const { count, doubled } = storeToRefs(counter)
    return { count, doubled, inc: counter.inc }
  },
})
```

下一步建议阅读：

* `defineComponent` / 生命周期 / `bindModel`：`/wevu/runtime`
* Store API：`/wevu/store`

---

---
url: /guide.md
---

# 快速开始 {#getting-started}

> \[!IMPORTANT]
> 使用前请确保安装 **Node.js `^20.19.0 || >=22.12.0`**。建议使用 [Node.js 官网](https://nodejs.org/) 的 LTS，并全局安装 `pnpm`（`npm i -g pnpm`）。

## 0. 准备工作

1. 下载并安装最新版 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)。
2. 启动开发者工具，在「设置 > 安全设置」中勾选 **服务端口**。这是 `pnpm dev --open`、`pnpm open` 等命令能唤起 IDE 的前提。
3. 第一次使用建议先手动打开一次项目，确认开发者工具可用，避免后续命令行提示 *“请先在微信开发者工具中开启服务端口”*。

## 1. 使用内置模板

### 1. 选择模板

执行以下命令，快速创建一个集成了 `weapp-vite` 的原生微信小程序项目：

::: code-group

```sh [pnpm]
pnpm create weapp-vite
```

```sh [yarn]
yarn create weapp-vite
```

```sh [npm]
npm create weapp-vite@latest
```

```sh [bun]
bun create weapp-vite
```

:::

::: details 生成的 `my-app` 项目中，默认包含以下内容:

```sh
.
├── README.md
├── package.json
├── project.config.json
├── project.private.config.json
├── src
│   ├── app.json
│   ├── app.scss
│   ├── app.ts
│   ├── components
│   │   └── HelloWorld
│   │       ├── HelloWorld.json
│   │       ├── HelloWorld.scss
│   │       ├── HelloWorld.ts
│   │       └── HelloWorld.wxml
│   ├── pages
│   │   └── index
│   │       ├── index.json
│   │       ├── index.scss
│   │       ├── index.ts
│   │       └── index.wxml
│   ├── sitemap.json
│   ├── theme.json
│   ├── utils
│   │   └── util.ts
│   └── vite-env.d.ts
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts
```

:::

### 2. 切换到目录中，执行安装命令

::: code-group

```sh [pnpm]
pnpm i
```

```sh [yarn]
yarn
```

```sh [npm]
npm i
```

```sh [bun]
bun i
```

:::

### 3. 开始开发

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

::: code-group

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

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

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

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

:::

### 4. 开发者工具预览

#### 执行 `open` 命令

::: code-group

```sh [pnpm]
pnpm open
```

```sh [yarn]
yarn open
```

```sh [npm]
npm run open
```

```sh [bun]
bun open
```

:::

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

## 2. 手动集成

### 1. 创建项目

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

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

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

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

![](../images/create-project.png)

> 如果你创建的是 **TS 模板项目**，请在 `vite.config.ts` 中设置 [`weapp.srcRoot`](../config/paths.md#weapp-srcroot) 为 `'./miniprogram'`。

### 2. 手动接入 weapp-vite

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

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

::: code-group

```sh [pnpm]
pnpm i
```

```sh [yarn]
yarn
```

```sh [npm]
npm i
```

```sh [bun]
bun i
```

:::

这样微信开发小程序的智能提示(`types`)，也都被安装进来

这样小程序 API 的类型声明（typings）也会一起装好，编辑器里就有补全和校验了。

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

## 预置命令

### 开发命令

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

命令会启动文件监听器，保存代码后会自动重新编译并同步到 `dist` 目录，无需手动刷新。

### 构建命令

```sh
pnpm build
pnpm build --open # 打开微信开发者工具，见下方
pnpm build -o # 打开微信开发者工具，见下方
```

此时会启用 `vite` 自带的 `build` 模式，删除整个 `dist` 目录重新生成，并进行代码压缩

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

```sh
pnpm open
```

使用该命令直接打开微信开发者工具（需要先开启服务端口）。

> \[!WARNING]
> 请在 `微信开发者工具` → `设置` → `安全设置` → 勾选 `服务端口`。

> \[!WARNING]
> Linux 目前没有官方微信开发者工具，请安装社区版：[msojocs/wechat-web-devtools-linux](https://github.com/msojocs/wechat-web-devtools-linux)，并把 `wechat-devtools-cli` 链接到系统 `PATH`，例如：

```sh
sudo ln -s /opt/apps/io.github.msojocs.wechat-devtools-linux/files/bin/bin/wechat-devtools-cli /usr/local/bin/
```

### 生成组件命令

```sh
pnpm g [filename]
```

用于快速生成页面/组件/App 等基础文件，详见 [生成脚手架](/guide/generate)。

## 简易配置项

如果你用微信开发者工具创建的是 **TypeScript 模板**（源码目录为 `miniprogram/`），需要把 `weapp.srcRoot` 指向它；否则按模板默认的 `src/` 即可。

配置项可以与 `vite` 通用，同时加入了 `weapp-vite` 的扩展:

`vite.config.[m]ts`:

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

export default defineConfig({
  weapp: {
    // 让 weapp-vite 知道 app.json / pages/ 在哪个目录下
    srcRoot: './miniprogram',
  },
})
```

你也可以在 `defineConfig` 里继续使用其他 Vite 插件（例如 `weapp-tailwindcss`）。

更多配置见：[/config/](/config/)

---

---
url: /guide/manual-integration.md
---
# 手动集成 weapp-vite

已经有运行中的微信小程序？可以按下面步骤在不依赖脚手架的情况下把 `weapp-vite` 接进来。整体思路就三步：补齐配置文件 → 安装依赖 → 调整目录。

> 以下命令示例使用 `pnpm`，切换为 `npm`/`yarn`/`bun` 时语法相同。

## 1. 安装依赖

在项目根目录执行：

```sh
pnpm add -D weapp-vite vite typescript @types/node sass
```

如果你计划使用 Tailwind、Less、Vue Runtime 等，可以一并安装，但这里保持最小化。

## 2. 初始化必需文件

### package.json

确认 `package.json` 中存在以下脚本（没有就添加）：

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

后续运行时只需执行 `pnpm run dev` / `pnpm run build` 等常规命令。

### tsconfig

如果项目还没有 TS 配置，创建 `tsconfig.json` 与 `tsconfig.node.json`：

```json
// tsconfig.json
{
  "extends": "@tsconfig/recommended/tsconfig.json",
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "allowJs": true,
    "types": ["miniprogram-api-typings"]
  },
  "include": ["src/**/*", "typed-router.d.ts", "typed-components.d.ts"]
}
```

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

### vite.config.ts

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

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

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

`srcRoot` 指向你存放 `app.*`、`pages/` 的目录；如果想继续在根目录开发，可以把 `srcRoot` 改成 `'.'`。

### 项目配置

确保 `project.config.json` 中的 `miniprogramRoot` 指向打包目录（默认 `dist`）：

```json
{
  "miniprogramRoot": "dist/",
  "compileType": "miniprogram",
  "appid": "tour-app-id",
  "setting": {
    "es6": true,
    "minified": true
  }
}
```

## 3. 调整目录

1. 新建 `src/`（或 `srcRoot` 对应目录），并把原项目的 `app.*`、`pages/`、`packages/` 等文件全部移动到该目录。
2. 如果存在 `sitemap.json`、`theme.json` 等静态文件，可放在 `src/` 或 `public/`，`weapp-vite` 都会自动处理。
3. 若项目包含分包，把每个分包放在 `src/packages/<name>/`，再在 `app.json` 中保持原本定义即可。

建议同步创建以下结构（可参考 [目录结构](/guide/directory-structure)）：

```
src/
├─ app.ts / app.json / app.scss
├─ pages/
├─ packages/
├─ components/
├─ config/
└─ utils/
```

## 4. 验证运行

1. 在命令行执行 `pnpm run dev`，等待 `dist/` 生成。
2. 打开微信开发者工具，导入当前项目，勾选「服务端口」后可选用 `pnpm run dev -- --open` 自动唤起 IDE。
3. 构建上传使用 `pnpm run build`，需要分析分包时执行 `pnpm run analyze`。

## 5. 可选增强

* **自动导入组件**：默认扫描 `components/**` 与各分包 `components/**`；如需扩展，配置 [`weapp.autoImportComponents`](/guide/auto-import)。
* **自动路由**：在 `vite.config.ts` 中开启 `weapp.autoRoutes: true` 后，会生成路由清单与类型；如需同步到 `app.json`，请改用 `app.json.ts` 读取 `weapp-vite/auto-routes`。
* **脚手架生成**：可在 `package.json` 中增加 `"g": "weapp-vite generate"`，之后执行 `pnpm run g pages/dashboard` 快速生成页面文件夹。

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

---

---
url: /config/build-and-output.md
---
# 构建输出与兼容 {#build-and-output}

这页说明 **产物输出目录** 与 **JS 输出格式/兼容策略**。它们直接决定：

* `dist/` 的目录结构
* 是否输出 CommonJS 或 ESM
* 是否启用 ES5 兼容降级

\[\[toc]]

## 输出目录来源

`weapp-vite` 的输出目录默认由 `project.config.json`（或多端配置）中的 **miniprogramRoot** 决定：

* 若 `build.outDir` **未显式配置**，`weapp-vite` 会将 `build.outDir` 设置为 `miniprogramRoot`。
* 若 `build.outDir` **已配置**，则以你的配置为准。

> \[!NOTE]
> 当启用 `weapp.multiPlatform` 且 `miniprogramRoot` 为相对路径 `dist` 时，输出会自动调整为 `dist/<platform>/dist`，以避免不同平台互相覆盖。

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

* **类型**：`'cjs' | 'esm'`
* **默认值**：`'cjs'`
* **作用**：控制 Rolldown/Rollup 的输出格式。

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

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

行为说明：

* `cjs`（默认）：输出 CommonJS，兼容性最好。
* `esm`：输出 ESM；在微信开发者工具中建议开启「ES6 转 ES5」以降低预览差异。

> \[!WARNING]
> 如果你手动把 `build.target` 设为 **ES2015 以下**，会直接报错；只有启用 `weapp.es5` 才允许降级到 ES5。

## `weapp.es5` {#weapp-es5}

* **类型**：`boolean`
* **默认值**：`false`
* **作用**：在输出 CommonJS 的基础上，用 `@swc/core` 进行 **ES5 降级**。

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

export default defineConfig({
  weapp: {
    jsFormat: 'cjs',
    es5: true,
  },
})
```

使用须知：

* 仅支持 `jsFormat: 'cjs'`，与 `esm` 同用会直接报错。
* 需要安装 `@swc/core`：`pnpm add -D @swc/core`。
* 开启后，`build.target` 会被强制收敛到 `es2015`，再由 SWC 降级到 ES5。

***

完成配置后建议重新执行 `pnpm build`，并在开发者工具内验证预览与上传流程。

---

---
url: /guide/module.md
---
# 模块化风格

`weapp-vite` 基于 ESM（ECMAScript Modules）进行构建。建议在业务代码里尽量统一使用 `import` / `export`，这样类型推导、Tree Shaking、热更新都会更稳定。

这页总结了小程序项目里常见的模块写法坑，以及对应的更稳妥写法。

## 统一改用 ESM

推荐在业务代码中全部采用 ESM，而不是混用 CommonJS (`require` / `module.exports`)。

```ts
// ✅ 推荐写法
import foo from '@/utils/foo'
import './register-global-components'

export default foo
export const bar = 'bar'

// ❌ 不推荐
const foo = require('@/utils/foo')
module.exports = foo
```

ESM 具备静态依赖图，打包器可以在构建期分析模块边界、自动移除未使用的导出，性能和可维护性都会更好。

## 处理路径差异

原生小程序里经常能见到 `import x from 'a/b/c'` 或 `import x from '/x/y/z'` 这种写法，但在标准 ESM 中它们并不总是合法（尤其是以 `/` 开头时会被当作 URL/根路径语义）。建议遵循以下约定：

* 使用 `./` 或 `../` 引入同目录、上级目录代码。
* 使用别名（如 `@/`）指向 `src` 根目录，避免 `/foo/bar` 这种会被当作 URL 解析的写法。

```ts
// 推荐
import util from './utils'
import config from '@/config'

// 可能导致路径解析错误
import util from 'utils'
import config from '/config'
```

别名配置请参考 [路径别名指南](/guide/alias)。

## 混合 ESM 与 CJS 时的注意事项

如果引用的第三方包仍然使用 CommonJS，请避免直接解构导入。标准的方式是使用命名空间导入，然后再手动解构：

```js
// apple.js (CommonJS)
module.exports = {
  a,
  b,
  c,
}

// ESM 中引用
import * as apple from './apple'
const { a, b, c } = apple
```

或者使用默认导入：

```js
import apple from './apple'
const { a, b, c } = apple
```

> \[!TIP]
> 如果第三方库同时提供 `module` 字段，weapp-vite 会优先使用其 ESM 版本。仍然遇到导入问题时，可以考虑通过 [`optimizeDeps.include`](/config/npm.md#weapp-npm) 或转换插件提前处理。

## 其他最佳实践

* **保持文件后缀明确**：在导入本地文件时保留 `.ts`/`.js` 后缀可以减少构建器的解析工作，但不是必需；保持团队一致即可。
* **避免动态 `require`**：这会导致打包时无法静态分析依赖，推荐改用 `import()` 动态导入或显式列出需要的模块。
* **导出命名更清晰**：优先使用命名导出（`export const foo = ...`），默认导出保留给“文件只提供一个核心实体”的场景。

---

---
url: /guide/generate.md
---
# 生成脚手架

`weapp-vite` 自带一个生成器，用来一键生成页面/组件/App 的基础文件（页面/组件包含 `js/ts`、`wxml`、`wxss`、`json`；App 不生成 `wxml`）。它适合两类情况：

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

## 快速上手

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

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

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

默认会创建如下结构：

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

> \[!TIP]
> `weapp-vite init` 会自动把脚本添加到 `package.json`。如果你在现有项目中手动安装了 weapp-vite，也可以自行补上 `"g": "weapp-vite generate"`。

## 自定义文件后缀与目录

很多团队会使用 TypeScript + Sass/SCSS 等组合。可以在 [`weapp.generate.extensions`](/config/generate.md#weapp-generate) 中指定默认后缀：

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

export default <UserConfig>{
  weapp: {
    generate: {
      extensions: {
        js: 'ts',
        wxss: 'scss',
        json: 'jsonc',
      },
    },
  },
}
```

此时再次执行 `pnpm g components/avatar`，生成的文件会自动变成 `.ts`、`.scss`、`.jsonc`。

> \[!TIP]
> 当 `extensions.json` 设为 `js/ts` 时，会生成 `*.json.js` / `*.json.ts`，便于配合脚本化 JSON 配置。

## 自定义模板内容

除了后缀，你还可以自定义“生成出来的默认内容”。`weapp.generate.templates` 支持四种写法：

* 字符串：视为模板文件路径（相对路径基于 CLI 当前工作目录）；
* `content`: 直接写入字符串；
* `path`: 指定已有模板文件（相对路径基于 CLI 当前工作目录）；
* 工厂函数：接收生成上下文，返回字符串（返回 `undefined` 时回退到默认模板）。

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

export default defineConfig({
  weapp: {
    generate: {
      templates: {
        shared: {
          wxss: () => '.root { color: red; }',
          json: { content: '{ "component": true }' },
        },
        component: {
          js: { content: 'Component({})' },
          wxml: { path: './templates/component.wxml' },
        },
        page: {
          js: async ({ fileName }) => `Page({ pageName: '${fileName}' })`,
          wxml: ({ outDir, fileName, defaultCode }) =>
            `<!-- ${outDir}/${fileName}.wxml -->\n${defaultCode ?? ''}`,
        },
      },
    },
  },
})
```

生成器会优先查找 `type` 对应的模板（`component`、`page`、`app`），找不到时回退到 `shared`。模板上下文包含 `type`、`fileType`、`fileName`、`outDir`、`extension` 以及默认代码 `defaultCode`，方便你按不同目录/文件类型做差异化输出。

## 调整生成文件名

默认情况下文件名与目录名一致。例如 `pnpm g components/avatar` 会生成 `avatar.ts / avatar.wxml`。若想生成目录和文件名不同的结构，可以使用 `-n` / `--name`：

```sh
pnpm g components/avatar -n index
```

输出：

```text
└── components
    └── avatar
        ├── index.jsonc
        ├── index.scss
        ├── index.ts
        └── index.wxml
```

## 生成不同类型的模板

* 生成 **组件**（默认）：`pnpm g components/avatar`
* 生成 **页面**：`pnpm g pages/home -p`（或 `--page`）
* 生成 **app 入口**：`pnpm g src/app -a`（或 `--app`，仅生成 `js/ts`、`wxss`、`json` 三类文件）

你可以自由组合 `--page` / `--app` 与自定义模板，实现差异化的初始化内容。

## CLI 参数速查

| 参数         | 类型     | 说明                                                  |
| ------------ | -------- | ----------------------------------------------------- |
| `[outDir]`   | `string` | 目标目录，支持多级路径，例如 `pages/profile/settings` |
| `-a, --app`  | `bool`   | 生成 `app` 类型，仅创建脚本、样式、配置文件           |
| `-p, --page` | `bool`   | 生成 `page` 类型模板                                  |
| `-n, --name` | `string` | 指定生成文件名，默认为 `outDir` 最末级目录            |

想深入了解更多字段（例如 `dirs`、`filenames`、`templates`），请查看 [配置文档 · 生成脚手架配置](/config/generate.md)。

---

---
url: /config/generate.md
---
# 生成脚手架配置 {#generate-config}

`weapp-vite generate` 用来快速生成页面/组件/App 基础文件。这页列出 `weapp.generate` 的字段，帮你把生成出来的目录结构、文件名、后缀和模板内容对齐到团队习惯。**这些配置仅影响 CLI 生成器，不影响构建流程。**

\[\[toc]]

## `weapp.generate` {#weapp-generate}

* **类型**：
  ```ts
  {
    extensions?: Partial<{ js: string; json: string; wxml: string; wxss: string }>
    dirs?: Partial<{ app: string; page: string; component: string }>
    filenames?: Partial<{ app: string; page: string; component: string }>
    templates?: TemplatesConfig
  }

  type TemplatesConfig = Partial<Record<'shared' | 'component' | 'page' | 'app', GenerateTemplateEntry>>

  type GenerateTemplateEntry = Partial<Record<'js' | 'json' | 'wxml' | 'wxss', TemplateSource>>

  type TemplateSource =
    | string
    | { path: string }
    | { content: string }
    | ((ctx: TemplateContext) => string | undefined | Promise<string | undefined>)

  interface TemplateContext {
    type: 'component' | 'page' | 'app'
    fileType: 'js' | 'json' | 'wxml' | 'wxss'
    fileName: string
    outDir: string
    extension: string
    cwd: string
    defaultCode?: string
  }
  ```
* **默认值**：`undefined`
* **适用场景**：
  * 用命令行创建页面/组件时，希望生成结果符合团队目录结构（而不是每次手动挪文件）。
  * 想在生成时就带上团队常用的模板内容（例如通用样式、占位配置、国际化骨架等）。

### 配置示例

```ts
export default defineConfig({
  weapp: {
    generate: {
      extensions: {
        js: 'ts',
        json: 'jsonc',
        wxss: 'scss',
      },
      dirs: {
        page: 'src/pages',
        component: 'src/components',
      },
      filenames: {
        app: 'app',
        page: 'index',
      },
      templates: {
        shared: {
          wxss: () => '.root { color: red; }',
        },
        component: {
          js: { content: 'Component({ custom: true })' },
        },
      },
    },
  },
})
```

### 字段说明

* `extensions`: 覆写生成文件的默认后缀，例如将 JS 切换为 TS、将 WXSS 改为 SCSS。`json` 允许设置为 `js/ts`，生成的文件名会变成 `*.json.js` / `*.json.ts`。
* `dirs`: 定义生成文件的默认目录。支持分别指定 `app`、`page`、`component` 的输出路径。未配置时以命令行传入的 `filepath` 为准。
* `filenames`: 定制生成文件的默认文件名。未显式传入 `--name` 时会优先使用该配置，否则回退到 `filepath` 的最后一段。
* `templates`: 为不同类型生成自定义文件内容。支持字符串、文件路径或工厂函数：
  * `string`: 视为模板文件路径（相对 `cwd`）。
  * `{ path: './template.wxml' }`: 从指定文件读取。
  * `{ content: '...' }`: 直接提供内容对象。
  * 函数：根据 `TemplateContext` 运行时返回字符串或 `undefined`，可结合条件逻辑灵活生成。

### CLI 说明与常见问题

生成器默认创建 **组件**，`-p/--page` 切换为页面，`-a/--app` 生成 app 入口（仅包含 `js/json/wxss`，不生成 `wxml`）：

```bash
pnpm weapp-vite g src/components/Avatar
pnpm weapp-vite g src/pages/home -p
pnpm weapp-vite g src -a
```

* **CLI 会覆盖已有文件吗？** 不会，生成命令只对全新文件生效，若目标文件已存在会提示冲突。
* **如何生成带注释的 JSON？** 把 `extensions.json` 设为 `jsonc` 即可，然后在模板里写注释/占位内容。
* **模板如何复用？** 用 `templates.shared` 提供全局基础模板，再在 `component`、`page`、`app` 里按需覆写。

***

接下来，可结合 [基础目录与资源收集](./paths.md#paths-config) 调整生成目标目录，或阅读 [共享配置](/config/shared.md) 在生成后自动注册组件与路由。

---

---
url: /guide/directory-structure.md
---
# 目录结构

`weapp-vite` 默认沿用原生小程序的目录习惯：`app.*` 放在 `src/`，页面在 `pages/`，分包在 `packages/`。在这个基础上，框架提供了一些“可选但推荐”的约定目录，让自动路由、自动导入组件、分包增强等能力能直接生效。

```text
.
├─ vite.config.ts
├─ project.config.json
├─ typed-router.d.ts          # 自动生成：页面/分包路由类型
├─ public/                    # 静态资源，会直接拷贝到 dist
└─ src/
   ├─ app.ts / app.json / app.scss
   ├─ pages/
   │  └─ index/
   ├─ packages/
   │  ├─ order/
   │  └─ profile/
   ├─ components/
   ├─ shared/
   ├─ action/
   ├─ config/
   ├─ utils/
   └─ workers/
```

> 大多数模板会把 `weapp.srcRoot` 显式设置为 `src/`，让下面这些目录约定开箱即用。如果你的源码位于其他目录（例如 `miniprogram/`），只要在 `vite.config.ts` 里调整 `weapp.srcRoot`，其余能力依旧可用。

## 根目录必备文件

| 路径                  | 说明                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `vite.config.ts`      | weapp-vite 的主配置。可在 `weapp.subPackages`、`weapp.autoImportComponents` 等字段中定制目录行为。           |
| `project.config.json` | 微信开发者工具项目配置，保持与原生项目一致。                                                                 |
| `typed-router.d.ts`   | 由 `weapp-vite` 自动生成的页面/分包路由类型声明。每次编译会根据 `pages/` 与 `packages/` 更新。               |
| `public/`             | 任意静态资源（icon、字体等）。构建时会原样拷贝到输出目录，适合存放 `sitemap.json`、`theme.json` 的模板文件。 |

## `src/` 内的默认约定

### App 基础文件

| 文件       | 作用                                                                            |
| ---------- | ------------------------------------------------------------------------------- |
| `app.ts`   | 小程序入口脚本，可自由使用 TypeScript、ESM。                                    |
| `app.json` | 仍是微信规范，`weapp-vite` 会原样解析 `pages`、`subPackages`、`tabBar` 等字段。 |
| `app.scss` | 全局样式，框架支持 Sass/Less/Stylus 等预处理器。                                |

> `app.json` 的 `pages` 与 `subPackages` 可以继续手写；也可以开启 [`weapp.autoRoutes`](/guide/auto-routes) 生成路由清单，并在 `app.json.ts` 中自动组装。

### `pages/` —— 主包页面

* 每个页面占一个目录（例如 `pages/index/`），通常包含 `index.ts`、`index.wxml`、`index.json`、`index.scss`。
* 自动路由会扫描 `pages/` 下的页面文件，只要该路径存在脚本/模板/配置之一即可被识别并生成类型。

### `components/` —— 主包组件

* 所有 `components/**/` 下的 `.wxml` 组件会被 **默认自动导入**，无需再手写 `usingComponents`。详见 [自动导入组件](/guide/auto-import)。
* 推荐将复用组件放在此处，框架也会为每个分包生成 `subPackages/<root>/components/**/*.wxml` 的默认扫描规则。

### `packages/` —— 分包

* 目录名直接对应 `app.json` 中的 `root`。
* 在 `vite.config.ts` 中设置 `weapp.subPackages['packages/order']` 可为每个分包开启独立构建、共享样式、定制 `autoImportComponents` 等高级能力，详见 [分包指南](/guide/subpackage)。
* 每个分包内部继续沿用 `pages/`、`components/` 等结构。

### `shared/`

* 非必需，常用于存放跨分包共享的样式、工具模块、设计令牌等。
* 在 `subPackages.<root>.styles` 中引用 `../shared/styles/theme.scss` 即可把主题样式注入到多个分包。

### `action/`、`config/`、`utils/`

* `action/`: 存放抽象的业务动作（如 `action/test1.ts`），便于多个页面调用。
* `config/`: 全局配置或埋点开关，常与 `inlineConfig` 配合，按分包注入常量。
* `utils/`: 公共工具函数。若主包与多个分包同时引用，`weapp-vite` 会根据 [`chunks.sharedStrategy`](/guide/subpackage#代码产物的位置) 自动决定落盘位置。

### `workers/`

* 微信 Worker 入口目录。若在 `app.json` 中配置了 `workers`，再在 `vite.config.ts` 里设置 `weapp.worker.entry` 即可让 weapp-vite 代为打包 worker 代码（参考 [Worker 配置](/config/worker)）。

## 快速生成目录

使用官方模板或 `weapp-vite generate` 脚手架时，以上目录会自动创建。想自定义路径/后缀，可在 `vite.config.ts` 配置 [`weapp.generate`](/config/generate)。

> 希望迁移既有项目？参考[《手动集成》](/guide/manual-integration) 把原小程序源码移动到 `src/`（或你的 `srcRoot`），再补齐配置即可。

---

---
url: /guide/lib-mode.md
---

# 组件库构建（lib 模式）

`weapp-vite` 的 **lib 模式** 用于打包小程序组件库或业务模块。它和应用模式的最大区别是：

* 只构建你声明的入口（组件/模块），不会生成 `app.json` 与页面路由。
* 输出目录默认保持源码相对路径，方便复用现有结构。
* 可以自动补全组件 JSON，适合批量产出可直接引用的组件库产物。

## 适用场景

* 组件库/模块库（希望被多个小程序复用）
* 多个业务包共享的 UI 或逻辑模块
* 希望把源码路径直接映射到产物路径的输出方式

## 快速开始（官方模板）

1. 生成项目（选择 **组件库模板 (lib 模式)**）：

```sh
pnpm create weapp-vite
```

2. 安装依赖：

```sh
pnpm i
```

3. 本地调试组件（会自动打开微信开发者工具）：

```sh
pnpm dev
```

4. 输出组件库产物：

```sh
pnpm build:lib
```

> \[!TIP]
> 模板会提供 `vite.config.ts`（用于本地调试）与 `weapp-vite.lib.config.ts`（用于库构建）。
> 你可以将应用调试与库构建拆成两个配置文件，互不影响。

## 基础配置

在 `weapp.lib` 中声明入口，即会进入 lib 模式：

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

export default defineConfig({
  weapp: {
    srcRoot: 'src',
    lib: {
      root: 'src',
      outDir: 'dist-lib',
      entry: [
        'components/HelloWorld/HelloWorld.ts',
        'components/sfc-script/index.vue',
        'components/sfc-setup/index.vue',
      ],
      preservePath: true,
      componentJson: 'auto',
    },
  },
})
```

### 核心字段说明

* `entry`：入口配置，支持 `string | string[] | Record<string, string>`。
* `root`：库源码根目录，默认沿用 `weapp.srcRoot`。
* `outDir`：lib 产物输出目录，默认沿用 `build.outDir`。
* `preservePath`：是否保持输出路径与源码路径一致（默认 `true`）。
* `fileName`：自定义 JS 产物路径（不含扩展名）。多入口时必须包含 `[name]`。
* `componentJson`：自动生成组件 JSON 配置（`true | 'auto' | (ctx) => object`）。

### 自定义输出路径

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: {
        button: 'components/button/index.vue',
        card: 'components/card/index.vue',
      },
      fileName: '[name]/index',
      outDir: 'dist-lib',
    },
  },
})
```

### 自动生成组件 JSON

```ts
export default defineConfig({
  weapp: {
    lib: {
      entry: ['components/button/index.vue'],
      componentJson: ctx => ({
        component: true,
        styleIsolation: 'shared',
        usingComponents: {},
      }),
    },
  },
})
```

`componentJson: 'auto'` 会在入口存在模板/样式但缺少 JSON 时自动生成 `{"component": true}`。

## 产物结构示例

假设入口为 `src/components/button/index.vue`，默认 `preservePath: true`：

```text
dist-lib/
  components/button/index.js
  components/button/index.wxml
  components/button/index.wxss
  components/button/index.json
```

如果入口只是纯 JS/TS 文件，则只会输出 `*.js`。

## 与 `weapp.chunks` 联动

lib 模式同样会应用 `weapp.chunks` 配置。若多个入口复用同一模块：

* `sharedMode: 'common'`（默认）会生成 `common.js`
* `sharedMode: 'path'` 会按源码路径输出共享模块（无 `common.js`）
* `sharedMode: 'inline'` 会直接内联到引用方

详见：[共享 Chunk 策略](/guide/chunks)。

## 常见问题

### 为什么没有 `app.json` 与页面产物？

lib 模式只输出你声明的入口及其依赖，不会生成应用页面与路由。

### 输出路径冲突怎么办？

当多个入口计算出同一路径时会报错。检查：

* 是否开启了 `preservePath` 并使用相同的入口目录
* `fileName` 是否在多入口模式下缺少 `[name]`

### 既要调试又要发组件库怎么办？

推荐使用 **两份配置**：

* `vite.config.ts`：本地调试（`pnpm dev`）
* `weapp-vite.lib.config.ts`：组件库构建（`pnpm build:lib`）

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

---

---
url: /config/auto-import-components.md
---
# 自动导入组件配置 {#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
  } | false
  ```
* **默认值**：启用（自动生成默认 `globs`）。

默认扫描规则：

* 主包：`components/**/*.wxml`
* 分包：`<root>/components/**/*.wxml`（若该分包未显式禁用）

### 示例

```ts
import { defineConfig } from 'weapp-vite/config'
import { TDesignResolver, VantResolver } from 'weapp-vite/auto-import-components/resolvers'

export default defineConfig({
  weapp: {
    autoImportComponents: {
      globs: ['components/**/*.wxml'],
      resolvers: [VantResolver(), TDesignResolver()],
      output: true,
      typedComponents: true,
      htmlCustomData: 'dist/mini-program.html-data.json',
      vueComponents: true,
      vueComponentsModule: 'wevu',
    },
  },
})
```

### 字段说明

* `globs`：组件模板扫描范围（glob）。通常要求同目录下存在 `.wxml + .js/ts + .json`，且 JSON 内 `component: true`。
* `resolvers`：第三方组件库解析器，把标签映射到 npm 包路径（如 `<van-button>` → `@vant/weapp/button`）。
* `output`：生成 `auto-import-components.json` 清单。
  * `true` / 未设置：输出到 `vite.config.ts` 同级目录；
  * 字符串：自定义路径；
  * `false`：不生成清单。
* `typedComponents`：生成 `typed-components.d.ts`（WXML props 类型）。
* `htmlCustomData`：生成 `mini-program.html-data.json`（VS Code/DevTools 提示）。
* `vueComponents`：生成 `components.d.ts`（Vue SFC 模板补全）。
* `vueComponentsModule`：`components.d.ts` 的 `declare module 'xxx'` 模块名。使用 wevu 时建议填 `wevu`。

### 禁用与分包覆盖

* 全局禁用：`autoImportComponents: false`
* 单独禁用分包：`weapp.subPackages.<root>.autoImportComponents = false`

> \[!TIP]
> 如需排除额外标签（例如占位标签），可以在 `weapp.wxml.excludeComponent` 中过滤。

更多实践示例请参考 [自动引入组件](/guide/auto-import)。

---

---
url: /guide/auto-import.md
---
# 自动引入组件

`weapp-vite` 可以在构建阶段自动扫描并注册组件，让你在 WXML 里直接写组件标签，而不需要手动维护 `usingComponents`。

你只需要告诉它两件事：

* 组件放在哪些目录（`globs`）
* 是否要接入第三方 UI 库（`resolvers`）

更细粒度的字段说明可参考 [配置文档 · 自动导入组件配置](/config/auto-import-components.md#weapp-autoimportcomponents)。

> \[!NOTE]
> 自动导入默认开启：主包 `components/**/*.wxml` 与每个 `subPackages.<root>` 下的 `components/**/*.wxml` 都会被自动扫描。仅当你需要：
>
> * 额外扩展扫描目录；
> * 关闭自动导入（例如 `autoImportComponents: false` 或 `autoImportComponents: { globs: [] }`）；或
> * 引入第三方 UI Resolver / 生成自定义输出
>
> 时才需要手动配置 `autoImportComponents`。

## 适用场景

* 在模板里直接写 `<HelloWorld />`，而不是每次都去 JSON 里登记一次。
* 组件数量多、目录复杂，希望构建器帮忙维护 `usingComponents`。
* 同时使用 Vant、TDesign 等 UI 库，希望和本地组件一样开箱即用。

## 快速上手：扫描项目组件

虽然无需额外配置即可生效，但你仍可以通过 [`weapp.autoImportComponents.globs`](/config/auto-import-components.md#weapp-autoimportcomponents) 表达更复杂的目录结构。满足“存在 `.wxml` + `.js/ts` + `.json` 且 `json.component === true`”的文件夹就会被自动注册：

::: code-group

```ts [vite.config.ts]
export default <UserConfig>{
  weapp: {
    autoImportComponents: {
      globs: [
        'components/**/*.wxml',
        'shared/design-system/**/*.wxml',
      ],
    },
  },
}
```

:::

默认规则如下：

* 组件名取决于文件名，且大小写敏感。`HelloWorld.{wxml,ts,json}` 会注册为 `HelloWorld`。
* 如果组件命名为 `index.*`，则使用父级目录名（`HelloWorld/index.wxml → HelloWorld`）。
* 当同一目录下既有 `index.*` 又有同名文件（如 `HelloWorld/index.ts` 与 `HelloWorld/HelloWorld.ts`）时，会优先选用 `index.*` 以保证产物路径稳定。

::: warning
内置组件（`view`、`text`、[`navigation-bar`](https://developers.weixin.qq.com/miniprogram/dev/component/navigation-bar.html) 等）会被自动忽略，避免重复注册。请避免把自定义组件命名成内置组件的名字；忽略列表可在 [`builtin.auto.ts`](https://github.com/weapp-vite/weapp-vite/blob/main/packages/weapp-vite/src/auto-import-components/builtin.auto.ts) 查看。
:::

## 第三方 UI 库自动引入

若项目使用 Vant、TDesign 等 UI 组件库，可以通过 **Resolver** 声明“标签名 → npm 包”之间的映射。`weapp-vite` 默认内置常见解析器，也支持自定义：

::: code-group

```ts [vite.config.ts]
import { TDesignResolver, VantResolver } from 'weapp-vite/auto-import-components/resolvers'

export default <UserConfig>{
  weapp: {
    autoImportComponents: {
      globs: ['components/**/*.wxml'],
      resolvers: [
        VantResolver(),
        TDesignResolver(),
      ],
    },
  },
}
```

:::

配置完成后，就能直接在 `wxml` 中书写 `<van-button>`、`<t-tabs>` 等标签，构建器会自动补全 `usingComponents`。

如果你希望接入自己的组件库（或对第三方库做二次封装），可以参考：[自定义 Resolver（自动导入组件）](/guide/auto-import-resolver)。

## 自动生成的辅助文件

除了运行时的自动注册，`weapp-vite` 还会生成一些辅助产物，帮助你在 IDE 内掌控组件列表。

### 组件清单

默认会在配置文件同级目录输出 `auto-import-components.json`，列出所有自动注册的组件：

```json
{
  "HelloWorld": "/components/HelloWorld/index",
  "Navbar": "/components/Navbar/Navbar",
  "van-button": "@vant/weapp/button"
}
```

你可以通过 `autoImportComponents.output` 自定义保存位置，或传入 `false` 关闭输出：

```ts
export default <UserConfig>{
  weapp: {
    autoImportComponents: {
      globs: ['components/**/*.wxml'],
      output: 'dist/auto-import-components.json',
    },
  },
}
```

### 类型声明与 HTML 自定义数据

* `typedComponents`: 生成 `typed-components.d.ts`，提供 `componentProps`、`ComponentProp` 等类型，方便在脚本中推断组件属性。
* `htmlCustomData`: 生成 `mini-program.html-data.json`，供 VS Code、微信开发者工具读取，实现标签/属性智能提示。

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

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

## 常见疑问

* **为什么没自动注册？** 先检查组件 `json` 是否包含 `"component": true`，再确认路径是否命中了 `globs`。修改 `globs` 或新增组件后记得重启 `pnpm dev` 以刷新缓存。
* **Resolver 报错怎么办？** 请确认对应 UI 库的 npm 包已安装，并与 resolver 支持的版本匹配。只想扫描本地组件时，可以临时移除 `resolvers`。
* **如何禁用部分组件？** 结合 `include` / `exclude` 或自定义 resolver 即可实现选择性注册，详见 [自动导入组件配置](/config/auto-import-components.md#weapp-autoimportcomponents)。

---

---
url: /guide/auto-routes.md
---
# 自动路由（`weapp-vite/auto-routes`）

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

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

## 适用场景

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

## 快速开启

自动路由默认关闭，在 `vite.config.ts` 中启用即可：

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

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

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

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

> \[!TIP]
> 扫描的“根目录”受 `weapp.srcRoot` 影响：如果你的源码在 `miniprogram/` 或 `src/`，先把 `weapp.srcRoot` 配对（参考 `/config/paths`），再开启自动路由会更顺滑。

## 监听范围

当自动路由开启后，以下文件会纳入监听：

* 页面脚本：`.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`）都会同步更新路由清单。

路由识别规则（固定逻辑）：

* 只扫描 `srcRoot` 下的 `pages/` 目录（含 `packages/<root>/pages` 这类分包结构）。
* 同一路径下 **只要存在脚本 / 模板 / 配置之一** 即可作为页面；但若 `json.component === true` 会被排除（视为组件）。

## 在代码中使用

自动路由模块默认导出 `routes` 对象，包含主包与分包的完整信息，同时提供若干辅助数组方便按需使用：

```ts
import routes, { entries, pages, subPackages } from 'weapp-vite/auto-routes'

console.log(routes.pages) // 主包页面清单
console.log(routes.entries) // 所有入口（主包 + 分包）
console.log(routes.subPackages) // 分包 root 与页面列表
```

在 TypeScript 项目中，可以直接引用 `typed-router.d.ts` 生成的类型，获得枚举式的路径提示，例如：

```ts
import type { AutoRoutes } from 'weapp-vite/auto-routes'

function jump(route: AutoRoutes.Pages) {
  wx.navigateTo({ url: route })
}
```

随着文件结构变化，类型声明也会自动刷新，无需手动维护。

## 写入 `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,
})
```

## 常见问题

* **为什么没有生成路由？**
  * 确认页面文件位于 `srcRoot/pages/**` 或 `<root>/pages/**`。
  * 确认页面目录下至少存在脚本 / 模板 / `json` 文件之一，且 `json.component !== true`。
  * 确认 `autoRoutes: true` 已开启。
  * 首次开启后如果没看到变化，重启一次 `pnpm dev`，让监听器重新初始化。
* **如何支持自定义目录结构？** 当前版本不支持自定义扫描规则。可改为手写 `app.json.pages`，或调整目录结构回到 `pages/**` 规范；monorepo 场景可为不同子项目分别设置 `weapp.srcRoot`。
* **`typed-router.d.ts` 要不要提交到仓库？** 它会随构建自动更新，通常建议加入 `.gitignore`；只有在你确实想把类型“固定下来”时再提交。

---

---
url: /guide/auto-import-resolver.md
---
# 自定义 autoImportComponents Resolver

`weapp.autoImportComponents.resolvers` 用来把 WXML 里的组件标签（例如 `<van-button>`）解析成小程序 `usingComponents` 需要的 `from` 路径（例如 `@vant/weapp/button`）。

这篇文档给出一个“可直接复制”的 Resolver 实现模板，并解释哪些能力会影响：

* 自动写入 `usingComponents`
* 生成 `auto-import-components.json`
* 生成 `typed-components.d.ts` / `mini-program.html-data.json`

## Resolver 是什么

Resolver 支持两种写法（推荐对象写法）：

```ts
// 函数写法：返回 { name, from } 或 void
type ResolverFn = (componentName: string, baseName: string) => { name: string, from: string } | void

// 对象写法：提供 components 映射表，或提供 resolve() 方法
interface ResolverObject {
  components?: Record<string, string>
  resolve?: (componentName: string, baseName: string) => { name: string, from: string } | void
  resolveExternalMetadataCandidates?: (from: string) => {
    packageName: string
    dts: string[]
    js: string[]
  } | undefined
}
```

> \[!TIP]
> weapp-vite 内置的 `VantResolver` / `TDesignResolver` / `WeuiResolver` 也是对象 resolver。自定义 resolver 推荐优先用对象写法：结构更清晰，也更方便提供 `components` / metadata 信息。

* `componentName`: 模板中的标签名（如 `van-button`、`t-tabs`、`HelloWorld`）
* `baseName`: 当前处理的文件名（用于进阶场景：按页面/组件上下文做差异化映射）
* 返回值：告诉 weapp-vite 把该标签注册到哪个 `from`

## 推荐：对象写法（静态映射）

如果你已经有一份“标签名 → from”的静态表，推荐直接用对象写法（无需写函数逻辑）：

```ts
import type { Resolver } from 'weapp-vite/auto-import-components/resolvers'
import { defineConfig } from 'weapp-vite/config'

const resolver: Resolver = {
  components: {
    'x-button': 'my-ui/button/button',
    'x-dialog': 'my-ui/dialog/dialog',
  },
}

export default defineConfig({
  weapp: {
    autoImportComponents: {
      resolvers: [resolver],
    },
  },
})
```

> \[!TIP]
> 这个实现已经足够让 weapp-vite 在构建时自动补全 `usingComponents`，并且便于参与 `auto-import-components.json` / `typed-components.d.ts` 等产物生成。

## 建议增强 1：暴露 `resolver.components`（用于“全量生成”）

当你开启 `typedComponents` / `htmlCustomData` 或希望输出的 `auto-import-components.json` 里包含第三方库组件时，建议维护 `resolver.components`：

```ts
import type { Resolver } from 'weapp-vite/auto-import-components/resolvers'

const components = ['button', 'tabs', 'dialog'] as const

const map = Object.fromEntries(
  components.map(name => [`x-${name}`, `my-ui/${name}/${name}`]),
)

export const MyUiResolver: Resolver = {
  components: Object.freeze({ ...map }),
  resolve(componentName) {
    const from = map[componentName]
    if (!from) {
      return
    }
    return { name: componentName, from }
  },
}
```

* `resolver.components` 会被 weapp-vite 用来收集“该 resolver 支持哪些组件”。
* 如果你只写了动态解析逻辑但没有 `components` 映射，通常仍能自动注册 `usingComponents`，但“全量类型/补全文件”可能无法覆盖到这些组件。

## 建议增强 2：支持第三方组件库 props 类型解析

如果你的 `from` 指向 npm 包（例如 `@vant/weapp/button`），并且希望 weapp-vite 在生成 `typed-components.d.ts` 时能从第三方库读取 `.d.ts` / `.js` 里的 props 信息，可以实现：

```ts
resolver.resolveExternalMetadataCandidates = (from) => {
  // 命中该 resolver 管理的包时返回候选路径
  return {
    packageName: 'my-ui',
    dts: ['dist/button/index.d.ts'],
    js: ['dist/button/index.js'],
  }
}
```

完整示例（简化版）：

```ts
import type { Resolver } from 'weapp-vite/auto-import-components/resolvers'

const resolver: Resolver = {
  components: {
    'x-button': 'my-ui/button',
  },
  resolve(componentName) {
    const from = componentName === 'x-button' ? 'my-ui/button' : undefined
    if (!from) {
      return
    }
    return { name: componentName, from }
  },
  resolveExternalMetadataCandidates(from) {
    if (!from.startsWith('my-ui/')) {
      return
    }
    const component = from.slice('my-ui/'.length)
    if (!component) {
      return
    }
    return {
      packageName: 'my-ui',
      dts: [`dist/${component}/index.d.ts`],
      js: [`dist/${component}/index.js`],
    }
  },
}
```

> \[!NOTE]
> `resolveExternalMetadataCandidates` 的目标不是“让组件能被解析”，而是“告诉 weapp-vite 到第三方依赖包里去哪里找 metadata 文件”，用于类型与补全产物。

## 进阶：函数写法（按需动态解析）

如果你需要按上下文动态解析（例如同一个标签在不同页面映射不同 `from`），可以使用函数写法：

```ts
import type { Resolver } from 'weapp-vite/auto-import-components/resolvers'

export function DynamicResolver(): Resolver {
  return (componentName, baseName) => {
    if (componentName !== 'x-button') {
      return
    }
    const from = baseName.includes('admin')
      ? 'my-ui-admin/button/button'
      : 'my-ui/button/button'
    return { name: componentName, from }
  }
}
```

## 参考实现

* `weapp-vite` 内置 Resolver：`VantResolver`、`TDesignResolver`、`WeuiResolver`
* 配置入口：[`weapp.autoImportComponents`](/config/auto-import-components.md#weapp-autoimportcomponents)

---

---
url: /llms.md
description: 兼容入口（/llms），与 /ai 共享同一套 AI 学习页面。
---


---

---
url: /guide/debug.md
---
# 调试与贡献

这份指南面向想要参与 `weapp-vite` 开发或排查源码问题的伙伴。按照下面的步骤准备环境，就可以在本地命中断点、验证修改，并把贡献发送到社区。

## 1. Fork 与克隆仓库

1. 登录 GitHub，访问 [`weapp-vite`](https://github.com/weapp-vite/weapp-vite) 仓库。
2. 点击右上角 **Fork**（或直接访问 [快捷链接](https://github.com/weapp-vite/weapp-vite/fork)），选择目标账号并命名仓库。
3. 完成后，在本机克隆你自己的 Fork：

```sh
git clone https://github.com/<your-name>/weapp-vite.git
cd weapp-vite
```

> \[!TIP]
> 首次 Fork 后建议添加上游仓库，后续可以方便地同步最新改动：
>
> ```sh
> git remote add upstream https://github.com/weapp-vite/weapp-vite.git
> ```

## 2. 安装依赖并准备调试

1. `package.json` 中记录了推荐的包管理器版本，例如：
   ```json
   {
     "packageManager": "pnpm@9.7.1"
   }
   ```
   建议执行 `corepack enable`，确保使用与仓库一致的工具链。
2. 在仓库根目录安装依赖：
   ```sh
   pnpm install
   ```
3. 仓库内的 `apps/` 目录准备了多个演示项目（`vite-native`、`vite-native-skyline` 等），可以任选一个作为调试入口。
4. VS Code 用户可以直接使用仓库内置的 `.vscode/launch.json`，也可以在“调试和运行”面板选择需要的配置，一键启动并命中 TypeScript 源码断点。

![](../images/vscode-debug.png)

> \[!NOTE]
> 如果你更喜欢终端调试，也可以运行 `pnpm --filter apps/vite-native dev` 再配合浏览器/IDE 附加调试，会同样命中源码断点。

## 3. 提交贡献

1. 在本地创建分支并完成改动，写好测试或文档：
   ```sh
   git checkout -b fix/my-change
   pnpm lint --filter ...
   pnpm test --filter ...
   ```
2. 提交后推送到自己的 Fork：
   ```sh
   git push origin fix/my-change
   ```
3. 打开仓库的 **Pull requests** 页面，点击 **New pull request**，选择你的分支 → 上游 `main`。
4. 在 PR 模板中说明动机、做了哪些验证，并附上截图或日志（如果适用）。

提交后维护者会安排 Review，并和你沟通改进建议。PR 合并后，你的改动就会进入 weapp-vite 的主线版本。

> \[!TIP]
> 想持续参与社区？欢迎在 Issue 区挑选 `good first issue`、`help wanted` 标签的任务，也可以加入讨论区提出想法。

---

---
url: /migration.md
---
# 迁移

1. [从 v5 升级到 v6](./v6.md)
2. [从 v4 升级到 v5](./v5.md)
3. [从 v3 升级到 v4](./v4.md)
4. [从 v2 升级到 v3](./v3.md)

---

---
url: /wevu/runtime.md
---

# 运行时与生命周期

这页主要讲 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` 与 `default` / `value`）。

如果你使用 weapp-vite 的 SFC 编译产物，通常会走 `createWevuComponent(options)`（见下节），并直接携带小程序 `properties`。

### 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 影响已创建的实例。

### 在 app.vue 顶层手动调用

如果你不使用 `weapp.wevu.defaults`，可以在 `app.vue` 顶层直接调用：

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

setWevuDefaults({
  component: {
    options: {
      addGlobalClass: true,
    },
  },
})
</script>
```

> 关键点：必须是**顶层语句**（不要放进 `setup()`/hook 里），这样才能早于 `createApp()` 执行。

> \[!TIP]
> 使用 weapp-vite 时，可以通过 `weapp.wevu.defaults` 在编译期自动注入 `setWevuDefaults()`（见 `/config/shared#weapp-wevu-defaults`）。

## setup：签名与上下文

`setup` 与 Vue 3 对齐，仅支持 `setup(props, ctx)` 签名。
若不需要 `props`，可使用 `setup(_, ctx)`；若不需要 `ctx`，可只写 `setup(props)`。

其中 `props` / `ctx.props` 来自小程序实例的 `properties`（页面通常为空对象）。

`ctx`（关键字段）：

* `ctx.runtime`：运行时实例（暴露 `bindModel` / `watch` / `snapshot` / `unmount` 等）
* `ctx.state`：响应式 state（包含 `data()` 与 `setup()` 返回的非函数值）
* `ctx.proxy`：公开实例代理（也是 `methods/computed` 的 `this`）
* `ctx.emit(event, ...args)`：触发自定义事件（内部调用 `triggerEvent`）
* `ctx.bindModel(path, options?)`：创建模型绑定（见下文）
* `ctx.watch(source, cb, options?)`：等价于 `ctx.runtime.watch`
* `ctx.instance`：小程序原生实例（高级/调试用途）

:::warning 同步调用约束
生命周期钩子必须在 `setup()` **同步执行阶段**调用，否则会抛错。
:::

## 生命周期钩子

### 通用钩子（页面/组件）

* `onShow` / `onHide` / `onReady` / `onUnload`

### 组件钩子（来自 lifetimes/pageLifetimes）

* `onMoved`（`lifetimes.moved`）
* `onError`（`lifetimes.error`）
* `onResize`（`pageLifetimes.resize`，组件场景）

### 页面钩子（Page 事件）

* `onPullDownRefresh`
* `onReachBottom`
* `onPageScroll`
* `onRouteDone`
* `onTabItemTap`
* `onResize`（页面场景）
* `onShareAppMessage`
* `onShareTimeline`
* `onAddToFavorites`

注意：分享/朋友圈/收藏是否触发由微信官方机制决定（例如右上角菜单/`open-type="share"`；朋友圈通常需配合 `wx.showShareMenu()` 开启菜单项）。
此外，小程序会对部分页面事件做“按需派发”：只有定义了对应页面方法，事件才会从渲染层派发到逻辑层；wevu 也仅在你定义了这些页面方法时才桥接 `setup()` 中注册的同名 hooks。
如果你使用 weapp-vite 构建，默认会在编译阶段根据你是否调用 `onPageScroll/onShareAppMessage/...` 自动补齐对应 `features.enableOnXxx = true`，以降低手动配置成本。

### 返回值型钩子（单实例）

以下钩子按“单实例”注册（后注册覆盖先注册），并允许返回值：

* `onSaveExitState`
* `onShareAppMessage`
* `onShareTimeline`
* `onAddToFavorites`

### Vue 风格别名（语义对齐为主）

* `onMounted` → `onReady`
* `onUnmounted` → `onUnload`
* `onActivated` → `onShow`
* `onDeactivated` → `onHide`
* `onErrorCaptured` → `onError`
* `onBeforeMount` / `onBeforeUnmount`：在 `setup()` 同步阶段立即执行（小程序无精确对应时机）
* `onBeforeUpdate` / `onUpdated`：在每次 `setData` 前/后触发（小程序没有“更新生命周期”，wevu 通过在更新链路里补齐语义）

## bindModel：模型绑定

`ctx.bindModel(path, options?)` 返回一个 `ModelBinding`：

* `binding.value` / `binding.update(value)`：读取或更新目标路径
* `binding.model(modelOptions?)`：生成事件 handler / value 字段（默认 `value` + `onInput`）

```ts
// setup(props, ctx) 内
const { model } = ctx.bindModel('form.price', {
  event: 'blur',
  formatter: v => Number(v) || 0,
})
const onPriceBlur = model().onBlur
```

```vue
<input :value="form.price" @blur="onPriceBlur" />
```

在 `<script setup>` 里可以用 `useBindModel()` 获取同一个能力，避免直接访问内部实例：

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

const bindModel = useBindModel()
const onPriceChange = bindModel<number>('form.price').model({ event: 'change' }).onChange
```

```vue
<t-input :value="form.price" @change="onPriceChange" />
```

默认解析器会优先取 `event.detail.value`，其次取 `event.target.value`；你也可以通过 `parser` 自定义解析逻辑。

> 注意：weapp-vite 模板编译目前不支持 `v-bind="object"` 的对象展开语法（不会生成任何属性），建议使用显式 `:value` + `@change/@input` 绑定。

## watch：组合式与选项式

### 组合式 watch

`watch()` / `watchEffect()` 与 Vue 3 类似，调度使用微任务队列；`deep` 默认采用“版本信号”策略（只订阅根版本号，不做深层遍历）：

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

setDeepWatchStrategy('traverse')
```

watch 返回的 stop handle 兼容旧写法，同时支持 `pause / resume` 暂停与恢复监听：

```ts
const { pause, resume, stop } = watch(() => state.form, () => {
  // handle changes
})

pause() // 暂停监听（避免同步循环）
resume() // 恢复监听
stop() // 停止监听
```

## 批处理：batch / startBatch / endBatch

当你需要在一次交互中同步修改很多字段（尤其是大列表、复杂表单）时，可以显式批处理以减少调度与 diff 次数：

```ts
import { batch, endBatch, ref, startBatch } from 'wevu'

const a = ref(0)
const b = ref(0)

batch(() => {
  a.value += 1
  b.value += 1
})

startBatch()
a.value += 1
b.value += 1
endBatch()
```

一般情况下不需要手动 batch：wevu 默认会在微任务中批量调度，但“同一 tick 内修改非常多字段”的场景，显式批处理更稳定。

### 选项式 watch（defineComponent/watch）

`defineComponent({ watch: { 'a.b': descriptor } })` 支持点路径表达式与三种描述符：

* 函数：`watch: { count(n, o) {} }`
* 方法名：`watch: { count: 'onCountChange' }`
* 对象：`watch: { count: { handler: 'onCountChange', immediate: true, deep: true } }`

## Provide / Inject

* `provide(key, value)` / `inject(key, defaultValue?)`：优先读写“当前实例”的 provide 域，找不到会回落到全局存储
* `provideGlobal` / `injectGlobal`：显式的全局读写（组件外调用场景）

:::warning 重要限制
当前版本没有组件树父子指针，`inject()` 不会向上查找“祖先组件”；组件内注入只能命中“当前实例提供的值”，否则回落到全局存储。
:::

## createApp：应用运行时与插件

`createApp(options)` 创建运行时，并在检测到全局 `App()` 时自动完成应用注册；插件通过 `app.use()` 安装：

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

const app = createApp({ data: () => ({}) })
app.use((runtime) => {
  runtime.config.globalProperties.$log = (...args: any[]) => console.log(...args)
})
```

`app.config.globalProperties` 会注入到公开实例 `proxy`，可通过 `this.$log`（或 `ctx.proxy.$log`）访问。

## 在测试环境使用（Vitest/Node）

wevu 的 `defineComponent()` 依赖全局 `Component()`（以及部分小程序实例方法）。在 Vitest/Node 环境测试时，通常有两条路：

* 把业务逻辑下沉到纯函数/composable/service，避免直接依赖小程序构造器（最推荐）
* 对测试用例 stub 全局 `Component` 并断言注册参数（只测“桥接层”）

示例（只展示思路）：

```ts
import { expect, test, vi } from 'vitest'
import { defineComponent } from 'wevu'

test('defineComponent registers Component()', () => {
  const Component = vi.fn()
  // @ts-expect-error test stub
  globalThis.Component = Component

  defineComponent({ setup: () => ({}) })
  expect(Component).toHaveBeenCalledTimes(1)
})
```

---

---
url: /blog/release1_7.md
---

![bg](/1.7.x-release.png)

# 这段时间 `weapp-vite` 的功能更新与优化

自从上次宣布 `weapp-vite` 的发布，已经过去三个月；`weapp-vite` 也逐渐迭代至 `1.7.6` 版本。

在此期间，我对其进行了多项功能的增强和优化，接下来我将为大家详细介绍近期的阶段性成果。

> 下面列出的功能皆为增强特性，开发者可自由选择启用或关闭，不影响原生小程序的兼容性。

## 核心功能更新

### 1. 自动构建 `npm`

在项目启动时，`weapp-vite` 会自动构建 `npm` 依赖，无需再手动点击微信开发者工具中的 构建 `npm`，提升了一定程度的开发体验。

详细信息请参考：[自动构建 npm 文档](https://vite.icebreaker.top/guide/npm.html)。

### 2. 语法增强

#### 2.1 `JSON` 文件增强

##### 1. 支持注释

`weapp-vite` 支持在项目中的 `JSON` 文件中添加注释。例如：

```jsonc
{
  /* 这是一个组件 */
  "component": true,
  "styleIsolation": "apply-shared",
  "usingComponents": {
    // 导航栏组件
    "navigation-bar": "@/navigation-bar/navigation-bar"
  }
}
```

这些注释会在最终产物内被去除。

> **注意：** `project.config.json` 和 `project.private.config.json` 不支持注释，因为这些文件直接由微信开发者工具读取。

##### 2. 智能提示

我生成了许多小程序的 `$schema` 文件，部署在 `vite.icebreaker.top` 上。

通过指定 `JSON` 的 `$schema` 字段，实现了配置文件的智能提示功能，优化了一点点开发体验。

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

详见：[JSON 配置文件的智能提示](https://vite.icebreaker.top/guide/json-intelli-sense.html)。

##### 3. 别名支持

可以在 `vite.config.ts` 中配置 `jsonAlias.entries` 字段, 在 `usingComponents` 中使用别名定义路径，这些在构建时会自动转化为相对路径。

例如:

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

export default <UserConfig>{
  weapp: {
    jsonAlias: {
      entries: [
        {
          find: '@',
          replacement: path.resolve(import.meta.dirname, 'components'),
        },
      ],
    },
  },
}
```

那么就可以在 `json` 中这样编写:

```json
{
  "usingComponents": {
    "navigation-bar": "@/navigation-bar/navigation-bar",
    "ice-avatar": "@/avatar/avatar"
  }
}
```

构建结果：

```json
{
  "usingComponents": {
    "navigation-bar": "../../components/navigation-bar/navigation-bar",
    "ice-avatar": "../../components/avatar/avatar"
  }
}
```

##### 4. 编程支持

`weapp-vite` 支持使用 `JS/TS` 文件来编写 `JSON`，你需要将 `component.json` 更改为 `component.json.ts`：

> 智能提示定义 `API` 都在 `weapp-vite/json` 中导出

比如普通写法:

```ts
import { defineComponentJson } from 'weapp-vite/json'

export default defineComponentJson({
  component: true,
  styleIsolation: 'apply-shared',
  usingComponents: {},
})
```

还支持引入异步数据、编译时变量或其他文件：

```ts
import type { Page } from 'weapp-vite/json'
import fs from 'node:fs/promises'
import path from 'node:path'
import shared0 from '@/assets/share'
import shared1 from './shared.json'

console.log('import.meta.env: ', import.meta.env)
console.log('import.meta.dirname: ', import.meta.dirname)
console.log('PLATFORM: ', import.meta.env.PLATFORM)
console.log(import.meta.env.DEV, import.meta.env.MODE, import.meta.env.PROD)
const key = await fs.readFile(
  path.resolve(import.meta.dirname, 'x.txt'),
  'utf8'
)

export default <Page>{
  usingComponents: {
    't-button': 'tdesign-miniprogram/button/button',
    't-divider': 'tdesign-miniprogram/divider/divider',
    'ice-avatar': '@/avatar/avatar',
  },
  ...shared0,
  ...shared1,
  key,
}
```

#### 2.2 `WXML` 文件增强

##### 事件绑定语法糖

`weapp-vite` 借鉴了 `Vue` 的事件绑定风格，为 `WXML` 增加了事件绑定语法糖：

这里我们以最常用的 `tap` 事件为例:

```html
<!-- 原始代码 -->
<view @tap="onTap"></view>
<!-- 编译后 -->
<view bind:tap="onTap"></view>
```

支持的事件绑定增强规则如下：

| 源代码                                      | 编译结果            |
| ------------------------------------------- | ------------------- |
| `@tap`                                      | `bind:tap`          |
| `@tap.catch`                                | `catch:tap`         |
| `@tap.mut`                                  | `mut-bind:tap`      |
| `@tap.capture`                              | `capture-bind:tap`  |
| `@tap.capture.catch` / `@tap.catch.capture` | `capture-catch:tap` |

详见：[事件绑定增强文档](https://vite.icebreaker.top/guide/wxml.html)。

这部分还能做的更多，欢迎与我进行讨论！

#### 2.3 `WXS` 增强

##### 编程支持（实验性）

`weapp-vite` 为 `WXS` 提供了 `JS/TS` 编程支持，支持通过更改 `wxs` 后缀为 `wxs.js` 或 `wxs.ts` 文件定义逻辑：

比如 `index.wxs.ts`:

```ts
export const foo = '\'hello world\' from hello.wxs.ts'

export const bar = function (d: string) {
  return d
}
```

另外内联 `WXS` 也支持使用 `lang="js"` 或 `lang="ts"` 直接启用编译功能:

```html
<view>{{test.foo}}</view>
<view @tap="{{test.tigger}}">{{test.abc}}</view>

<wxs module="test" lang="ts">
const { bar, foo } = require('./index.wxs.js')
const bbc = require('./bbc.wxs')
export const abc = 'abc'

export function tigger(value:string){
  console.log(abc)
}

export {
  foo,
  bar,
  bbc
}
</wxs>
```

详情请参考：[Wxs 增强](https://vite.icebreaker.top/guide/wxs.html)。

### 3. 生成脚手架

`weapp-vite` 内置了生成脚手架工具，可快速生成一系列文件（如 `js`、`wxml`、`wxss` 和 `json`），用于提升开发效率。

最基础的用法只需要 `weapp-vite g [outDir]`

详情请参考：[生成脚手架文档](https://vite.icebreaker.top/guide/generate.html)。

### 4. 分包支持

针对普通分包和独立分包的加载需求进行了优化，用户几乎无需额外配置即可实现分包加载。

尤其是独立分包的场景，创建了独立的编译上下文。

详情请参考：[分包指南](https://vite.icebreaker.top/guide/subpackage.html)。

## 不忘初心，持续改进

`weapp-vite` 的初衷是实现对原生小程序的增强，现有原生小程序几乎可以零成本地迁移过来，并享受更高效的开发体验。

在此，希望各位开发者试用，欢迎反馈与参与。

如果您对文中的任何功能或增强有疑问、建议，欢迎到  [Github Discussions](https://github.com/weapp-vite/weapp-vite/discussions) 提出讨论！

---

---
url: /deep/config-service.md
---
# 配置服务内部结构

想在 weapp-vite 中扩展配置加载或贡献新能力？这一页梳理了配置服务的核心文件，帮助你快速定位到对应模块。即便不准备修改源码，也能借此了解 `defineConfig` 背后的执行流程。

## createConfigService.ts

* 位置：`packages/weapp-vite/src/runtime/config/createConfigService.ts`
* 负责初始化配置状态、导出 `ConfigService` 对外 API，并将内部工具组合在一起。
* 统一维护 `defineEnv`、包管理器信息以及路径相关的辅助方法。

## internal/alias.ts

* 负责维护与注入内置别名，保证 `@oxc-project/runtime` 与内置依赖能被正确解析。
* 提供 `createAliasManager`，供配置加载与合并阶段复用。

## internal/loadConfig.ts

* 专注从用户工程、weapp 配置文件与默认设置中生成最终的 `InlineConfig`。
* 同时处理增强迁移、`rolldown` 插件注入以及输出后缀推导等逻辑。

## internal/merge.ts

* 抽离运行时合并逻辑，包含 `mergeWorkers`、`merge`、`mergeWeb` 与 `mergeInlineConfig`。
* 对运行平台做统一的环境标记，并复用别名处理能力。

通过以上拆分，`createConfigService.ts` 体积控制在 300 行以内，同时文档化了各模块职责，方便在需要扩展配置时快速定位到对应实现。想进一步了解实际代码，可直接浏览仓库中的实现并结合调试能力（`weapp.debug.inspect`）验证行为。

---

---
url: /config.md
---
# 配置概览 {#config-overview}

`weapp-vite` 使用 **Vite 配置模型**：在 `vite.config.ts` 中增加一个 `weapp` 字段即可。你也可以把小程序专属配置拆到 `weapp-vite.config.*`，两者会合并。

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

export default defineConfig({
  // 这里依然可以写任意 Vite 配置
  weapp: {
    // 小程序专属配置写在这里
  },
})
```

> \[!NOTE]
> 配置文件以 **ESM** 方式执行。若需要绝对路径，推荐使用 `import.meta.dirname`（本仓库与脚手架默认提供）或 `fileURLToPath(import.meta.url)`。

> \[!TIP]
> 你可以额外创建 `weapp-vite.config.ts`（或 `.mts/.cts/.js/.mjs/.cjs/.json`）。`weapp-vite` 会先读取其中的 `weapp` 配置，再与 `vite.config.*` 合并，便于把「小程序配置」与「通用 Vite 配置」分开维护。

\[\[toc]]

## 你最可能先要改的 3 项

1. **源码目录**：`app.json` 不在根目录时，先配 [`weapp.srcRoot`](./paths.md#weapp-srcroot)。
2. **输出目录**：由 `project.config.json` 的 `miniprogramRoot` 决定，详见 [构建输出与兼容](./build-and-output.md)。
3. **自动导入组件**：默认已开启（扫描 `components/**/*.wxml`），详见 [自动导入组件配置](./auto-import-components.md)。

## 配置索引

| 主题 | 内容概览 |
| --- | --- |
| [基础目录与资源收集](./paths.md) | `srcRoot` / `pluginRoot` / 静态资源拷贝 / 预留字段 |
| [构建输出与兼容](./build-and-output.md) | `jsFormat` / `es5` / 输出目录推导 / 多端输出规则 |
| [JSON 配置](./json.md) | `jsonAlias` / JSON 默认值 / 合并策略 |
| [JS 配置](./js.md) | `tsconfigPaths`（vite-tsconfig-paths） |
| [Vue SFC 配置](./vue.md) | `weapp.vue` 模板编译与 class/style 运行时 |
| [分包配置](./subpackages.md) | 独立/普通分包、依赖裁剪、共享样式 |
| [Worker 配置](./worker.md) | Worker 入口与构建输出 |
| [生成脚手架配置](./generate.md) | `weapp.generate` 目录结构、后缀与模板定制 |
| [npm 配置](./npm.md) | 自动/手动构建、`weapp.npm` 字段、缓存与优化 |
| [WXML 配置](./wxml.md) | WXML 扫描与模板处理行为 |
| [WXS 配置](./wxs.md) experimental | WXS 处理与调试建议 |
| [自动导入组件配置](./auto-import-components.md) | `weapp.autoImportComponents` 字段与产物输出 |
| [共享配置](./shared.md) | 自动路由、调试钩子、HMR 与共享 chunk 策略 |
| [Web 运行时配置](./web.md) experimental | `weapp.web` 浏览器端预览与调试 |

> 仍在寻找 Vite 原生配置？可直接参考 [Vite 官方配置文档](https://cn.vitejs.dev/config/)。

***

如果你不确定从哪里开始，建议先看 **基础目录与资源收集** 和 **构建输出与兼容** 两页。

---

---
url: /guide/image-optimize.md
---
# 静态资源的处理与优化

`weapp-vite` 在静态资源方面沿用了 Vite 的约定：`import` 语句、`public` 目录、插件生态都可以直接使用。本页总结了新手最常遇到的场景，并给出优化建议。

## 何时放入 `public`

* 放在 `public/` 的文件会原样复制到产物目录（默认同级的 `dist/`），不会参与打包。
* 适合体积较大、无需通过模块系统处理的资源，例如应用图标、`tabbar` 图标、`sitemap.json`。
* 引用方式使用根路径：`/icon.png`、`/static/logo.svg`。对于 `app.json` 中的字段（例如 `tabBar.iconPath`），可按官方要求使用相对或绝对路径。

> \[!TIP]
> 可以通过 Vite 的 [`publicDir`](https://cn.vite.dev/config/shared-options#publicdir) 调整目录位置，也可以完全禁用该行为。

## 通过 `import` 引用的资源

当在脚本、样式中使用 `import img from './logo.png'` 或 `background: url('./banner.png')` 时，会由 Rolldown 负责拷贝并生成哈希文件名。这类资源会自动记录在依赖图中，适合页面局部使用的图片。

若需要在运行时根据条件加载，可结合 `new URL('./foo.png', import.meta.url)` 等方式。不过仍建议把静态文件纳入仓库管理，确保构建可重复、可回滚。

## 图片压缩与 CDN

针对图片体积，可从两方面入手：

1. **构建时压缩**：使用 Vite 插件在打包阶段压缩图片。
2. **发布到 CDN/OSS**：将图片上传到静态资源服务，代码中只保留 URL。

### 使用 `vite-plugin-image-optimizer`

该插件会在打包时使用 `sharp`、`svgo` 等工具对图片做无损/有损压缩。示例：

```sh
pnpm add -D vite-plugin-image-optimizer sharp svgo
```

```ts
import { ViteImageOptimizer } from 'vite-plugin-image-optimizer'
import { defineConfig } from 'weapp-vite'

export default defineConfig({
  plugins: [
    ViteImageOptimizer({
      // 按需定制压缩选项，例如：
      png: { quality: 80 },
      jpg: { quality: 80 },
    }),
  ],
})
```

> \[!NOTE]
> `sharp` 需要 Node.js 原生依赖，安装失败时可参考插件文档或切换到 `wasm` 方案。

### 与 CDN/OSS 协同

* 在构建脚本中上传资源后，可使用环境变量或配置文件将 URL 注入到页面。
* 保持仓库内仍有源文件，便于回滚与重新构建。
* 若启用自动上传，注意处理好缓存与失效时间，避免小程序端长时间引用旧资源。

## 常见问题

* **开发环境访问不到 `public` 资源？** 请确保以 `/` 开头引用。如果仍然 404，检查资源是否位于 `public/` 根目录而非 `src/public/`。
* **编译后图片路径错乱？** 对于通过 `import` 引入的资源，请避免手动编写相对路径字符串，改用 `import` 或 `new URL`，让构建器接管路径计算。
* **需要自动生成多尺寸图标？** 可以结合 Vite 插件或自定义脚本（如 `sharp`）在构建阶段批量生成。

---

---
url: /guide/multi-platform.md
---

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

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

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

> \[!WARNING]
> 执行命令前请先安装对应平台的 IDE；如果你需要用命令行唤起 IDE，请在 IDE 里开启“服务端口”。

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

```sh
pnpm dev -- --platform alipay
pnpm build -- --platform alipay
pnpm open -- --platform alipay
# 也可以直接调用 CLI，省去额外的 --
pnpm exec weapp-vite dev --platform alipay
pnpm exec weapp-vite build --platform alipay
pnpm exec weapp-vite open --platform alipay
```

* 产物扩展名自动变更为 `axml` / `acss` / `sjs`。
* 在支付宝 IDE 中导入 `dist/` 目录即可预览。
* `open --platform alipay` 会自动通过 `minidev ide` 打开支付宝开发者工具（需先安装 `minidev`）。

## 字节系（抖音 / 今日头条）小程序 {#platform-tt}

```sh
pnpm dev -- --platform tt
pnpm build -- --platform tt
pnpm exec weapp-vite dev --platform tt
pnpm exec weapp-vite build --platform tt
```

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

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

```sh
pnpm dev -- --platform swan
pnpm build -- --platform swan
pnpm exec weapp-vite dev --platform swan
pnpm exec weapp-vite build --platform swan
```

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

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

```sh
pnpm dev -- --platform jd
pnpm build -- --platform jd
pnpm exec weapp-vite dev --platform jd
pnpm exec weapp-vite build --platform jd
```

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

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

```sh
pnpm dev -- --platform xhs
pnpm build -- --platform xhs
pnpm exec weapp-vite dev --platform xhs
pnpm exec weapp-vite build --platform xhs
```

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

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