# 规则参考

共 73 个诊断代码。每条诊断都有固定的 `code`、级别和位置。源码文件中的问题给出 `文件:行:列`，配置文件中的问题给出 JSON 路径（如 `$.usingComponents["thumb"]`）。

级别含义：

- **error**：编译、打包会失败，或运行时跳转/加载必然失败。默认退出码 `1`。
- **warning**：真机上大概率出错，或是明确的隐患，项目仍能编译。加 `--strict` 时也会导致退出码 `1`。
- **info**：优化建议，不影响退出码。

## 分包边界（依赖图规则）

依据：[使用分包](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/basic.html)、[独立分包](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/independent.html)、[分包异步化](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html)。

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `main-package-references-subpackage` | error | 主包内的文件通过 require / import / 组件 / WXML import·include / WXS / WXSS @import / 图片引用了分包内的文件。主包启动时分包尚未下载。 |
| `cross-subpackage-reference` | error | 分包 A 的文件引用了分包 B 的文件。分包之间只能通过主包共享代码。 |
| `independent-subpackage-dependency` | error | 独立分包引用了主包或其他分包的任何文件。独立分包运行时主包可能未加载。 |

`require.async(...)` 以及在 `componentPlaceholder` 中声明了占位组件的跨包组件属于分包异步化，不报告。判断依据是每条依赖边两端文件所属的包：包归属由 `app.json` 中最长匹配的分包 `root` 决定。

## 页面跳转

依据：[wx.navigateTo](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.navigateTo.html)、[wx.switchTab](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.switchTab.html)、[navigator](https://developers.weixin.qq.com/miniprogram/dev/component/navigator.html)。

检查对象：JS 中 `wx.navigateTo / redirectTo / reLaunch / switchTab({ url })`，以及 WXML 中 `<navigator url open-type>`。`url` 为字符串字面量，或 `?` 之前不含 `${}` 的模板字符串时才检查；查询参数会被去掉。相对路径按所在页面的路由解析；非页面文件（如 `utils/`）中的相对路径因为无法确定当前页面而跳过。空 `url`、以 `#` 开头、`javascript:` 和网络地址（含 `//host`）不是页面路径，WeUI 等组件库把它们用作占位链接，不检查。`open-type` 也接受驼峰写法 `openType`。

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `unknown-navigation-target` | error | 目标路由未在 `pages` 或任何分包的 `pages` 中注册。 |
| `invalid-navigation-target` | error | 目标路径越出小程序根目录或为空。 |
| `navigate-to-tab-page` | error | `navigateTo`/`redirectTo`（或 `open-type` 为 `navigate`/`redirect`）打开了 tabBar 页面。 |
| `switch-tab-to-non-tab-page` | error | `switchTab` 打开了不在 `tabBar.list` 中的页面。 |

## 模块与引用解析

解析规则：`/a/b` 相对小程序根目录；`./`、`../` 相对当前文件目录；裸路径先在当前目录及各级父目录的 `miniprogram_npm` 中查找，再按相对当前目录处理。JS 会补全 `.js` 和 `/index.js`；组件以 `.json` 定位，可补全 `/index.json`。网络地址、`plugin://`、`cloud://`、`data:` 和包含 `{{ }}` 的值视为外部引用，不检查。

`app.json` 的 `useExtendedLib.weui` 开启时，`weui-miniprogram/...` 组件由开发者工具在构建时提供，视为外部引用。

**编译插件**：`project.config.json` 的 `setting.useCompilerPlugins` 包含 `typescript`、`less` 或 `sass` 时，按开发者工具的编译结果分析：`a.ts` 视为 `a.js`，`a.less`、`a.scss`、`a.sass` 视为 `a.wxss`（同名的编译产物已存在时以产物为准，`.d.ts` 不参与）。诊断仍指向源文件。TypeScript 中的 `import type`、`import { type T }`，以及绑定名只出现在类型位置（`:`、`<`、`|`、`&`、`as`、`implements` 之后）的 import 会像 `tsc` 一样被删除，不检查目标；Less / Sass 中的 `//` 注释会被跳过。配置读取自小程序根目录或项目目录下的 `project.config.json`。

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `unresolved-module` | error | `require` / `import` / `export ... from` 的目标不存在。 |
| `unresolved-component` | error | `usingComponents` 或 `componentGenerics.*.default` 的组件不存在。 |
| `unresolved-wxml-reference` | error | `<import src>`、`<include src>`、`<wxs src>` 的目标不存在。 |
| `unresolved-style-import` | error | WXSS `@import` 的目标不存在。 |
| `missing-asset` | error | `<image>`、`<cover-image>`、`<video>`、`<audio>` 的本地 `src` 不存在。 |
| `missing-config-file` | error | `sitemapLocation`、`themeLocation` 指向的文件不存在。 |
| `missing-custom-tab-bar` | error | `tabBar.custom` 为 `true`，但没有 `custom-tab-bar/index` 组件。 |

## 组件

依据：[自定义组件](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/)。

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `missing-component-flag` | error | 被当作组件引用的 JSON 中缺少 `"component": true`。 |
| `incomplete-component` | error | 组件缺少 `.js` 或 `.wxml`。 |
| `invalid-component-path` | error | `usingComponents` 不是对象，或值不是字符串。 |
| `unused-component` | warning | 页面或组件声明了组件，但其 WXML 及其 import / include 的 WXML 中都没有使用该标签，也没有作为 `generic:*` 的值使用。未使用的组件仍会被打包和初始化。`app.json` 中的全局组件不检查。 |

## WXML / WXS / WXSS

依据：[WXML 引用](https://developers.weixin.qq.com/miniprogram/dev/reference/wxml/import.html)、[WXS 模块](https://developers.weixin.qq.com/miniprogram/dev/reference/wxs/01wxs-module.html)、[WXSS](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxss.html)。

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `wxml-syntax-error` | error | 未闭合或错配的标签、未闭合的注释、属性值或 `{{ }}`、重复属性、文本中多余的 `<`。WXML 要求标签严格闭合。 |
| `unknown-template` | error | `<template is="x">` 中的 `x` 既不在本文件定义，也不在本文件直接 import 的文件中定义。import 不具传递性；被 include 的文件可以使用 include 方可见的模板。`is` 为数据绑定时跳过。 |
| `wxs-missing-module` | error | `<wxs>` 缺少 `module` 属性。 |
| `wxs-requires-non-wxs` | error | WXS 中 `require` 了非 `.wxs` 文件。 |
| `local-wxss-resource` | warning | WXSS 中的 `url()` 指向本地文件。WXSS 背景图只支持网络图片、base64 或改用 `<image>`，本地路径在真机上无法加载。 |
| `script-syntax-error` | warning | JS / WXS 词法错误：未闭合的字符串、模板字符串、正则或注释，非法转义。 |
| `wxss-syntax-error` | warning | WXSS 中未闭合的注释、字符串或 `url()`。 |

## 模块循环

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `require-cycle` | warning | 同步 `require` / `import` 构成环（含自引用）。CommonJS 循环中先加载的一方会拿到未初始化完的 `module.exports`。每个强连通分量只报告一次。 |

## 体积与清理建议

依据：分包文档中"单个分包/主包大小不能超过 2M，整个小程序所有分包大小不超过 20M"。体积按源文件字节数估算，不含开发者工具的压缩和 `packOptions.ignore`，`project.config.json`、`package.json`、`.md`、`.ts` 和以 `.` 开头的路径不计入。

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `package-size-exceeded` | error | 主包或某个分包超过 `--max-package-kb`（默认 2048）。 |
| `total-size-exceeded` | error | 所有包合计超过 `--max-total-kb`（默认 20480）。 |
| `move-to-subpackage` | info | 主包中的文件不被主包的任何入口同步引用，只被一个分包使用。移入该分包可直接减小主包体积，具体步骤见下方迁移清单。 |
| `unreferenced-file` | info | 可打包的文件（代码、配置、图片）不被任何入口引用。`miniprogram_npm/` 和 `app.json` 中 `workers` 指定目录下的文件不检查。动态拼接路径引用的图片也会出现在这里，需人工确认。 |

### 迁移清单

报告的 `moves`（JSON）和文本报告末尾给出执行 `move-to-subpackage` 建议的具体步骤：

- 文件移到 `<分包 root>/<原路径>`，例如 `utils/chart.js` → `packageGoods/utils/chart.js`。目标位置已有文件时 `conflict` 为 `true`。
- 页面或组件的 `.json`、`.js`、`.wxml`、`.wxss` 只能一起移动；其中任何一个仍被主包使用时，整个组件都不列入清单（建议本身仍会报告）。`miniprogram_npm` 中的文件不列入，应改为在分包中构建 npm。
- `rewrites` 包括其他文件对被移动文件的引用，以及被移动文件自身中因位置变化而失效的相对引用；同时移动、相对位置不变的引用不列出。新写法保留原来的风格：`/` 开头的仍写根路径，相对路径重新计算为最短的 `./` 或 `../` 形式，省略的 `.js`、`/index` 等后缀继续省略。
- 无法确定新写法的引用 `replacement` 为空，需要人工处理。动态拼接的路径不在依赖图中，也不会列出。

## 插件

依据：[使用插件](https://developers.weixin.qq.com/miniprogram/dev/framework/plugin/using.html)。

插件在 `app.json` 的 `plugins` 或某个分包的 `plugins` 中以“引用名 → `{ version, provider }`”声明。使用处包括：`usingComponents` 中的 `plugin://引用名/组件`、跳转 `url` 为 `plugin://引用名/页面` 的 `wx.navigateTo` 等调用和 `<navigator>`，以及 `requirePlugin('引用名')`。`requirePlugin` 也接受插件的 AppID（基础库 2.14.0 起）。参数不是字符串字面量的 `requirePlugin` 不检查。

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `invalid-plugins` | error | `plugins`（主包或分包）不是对象。 |
| `invalid-plugin` | error | 插件条目不是对象，或 `version`、`provider` 不是非空字符串。 |
| `duplicate-plugin` | error | 同一个插件（相同 `provider`）被多个分包声明。文档：“同一个插件不能被多个分包同时引用”。 |
| `unknown-plugin` | error | 使用的引用名既不在 `app.json` 的 `plugins` 中，也不在任何分包的 `plugins` 中。 |
| `plugin-not-in-package` | error | 插件只在分包 A 中声明，却在其他包中使用。文档：“默认情况下，仅能在这个分包内使用该插件，除非通过分包异步化进行异步的跨分包引用”，因此声明了 `componentPlaceholder` 的组件不报告。 |
| `unused-plugin` | info | 声明的插件没有任何静态使用。插件代码包仍会随所在的包下载。跳转地址为动态拼接时也会出现在这里，需人工确认。 |

## Worker

依据：[多线程 Worker](https://developers.weixin.qq.com/miniprogram/dev/framework/workers.html)。

`app.json` 的 `workers` 可以是目录字符串，也可以是 `{ "path": "workers", "isSubpackage": true }`。目录中的每个 `.js` 文件都作为入口分析（它们会被打包进 Worker），因此不会被报告为未引用文件；它们与主包、分包之间的边不套用分包边界规则，改由下表检查。`wx.createWorker('<路径>')` 的路径从小程序根目录写起，开头的 `/` 可省略。

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `invalid-workers` | error | `workers` 不是可移植的相对目录路径（字符串或对象的 `path`），或 `isSubpackage` 不是布尔值。 |
| `missing-workers-directory` | error | `workers` 指定的目录中没有任何文件。 |
| `invalid-worker-file` | warning | Worker 目录中有非 JS 文件。文档：“Worker 目录内只支持放置 JS 文件，其他类型的静态文件需要放在 Worker 目录外”。 |
| `worker-dependency-outside-directory` | error | Worker 代码 `require` / `import` 了 Worker 目录外的文件。文档：“Worker 内代码只能 require 指定 Worker 路径内的文件，无法引用其它路径”。 |
| `worker-outside-directory` | error | `wx.createWorker` 的入口不在 Worker 目录中，或 `app.json` 没有声明 `workers`。 |
| `unresolved-worker` | error | `wx.createWorker` 的入口文件不存在（路径需带 `.js`），或越出小程序目录。 |

`isSubpackage: true` 时 Worker 代码会被打包为独立的分包，需要先用 `wx.preDownloadSubpackage` 下载。体积统计目前仍把 Worker 目录计入它所在的包，预下载调用也不检查。

## app.json 配置

本节的配置问题均为 error，位置以 JSON 路径给出。

文件与 JSON：

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `missing-app-json` | error | 小程序根目录下没有 `app.json`。 |
| `unreadable-file` | error | 文件不是 UTF-8 文本。 |
| `invalid-json` | error | `app.json` 或组件、页面的 JSON 配置不是合法 JSON，或存在重复键。 |
| `invalid-manifest` | error | `app.json` 的顶层不是 JSON 对象。 |

页面：

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `invalid-pages` | error | `pages` 不是非空的页面路径数组。 |
| `invalid-route` | error | 页面路径不可移植：越界、绝对路径、带扩展名、Windows 保留名等。 |
| `duplicate-route` | error | 同一页面重复注册。 |
| `route-case-collision` | error | 两个页面路径仅大小写不同。 |
| `main-route-inside-subpackage` | error | 主包页面位于分包根目录下。 |
| `missing-page-file` | error | 页面缺少 `.js` 或 `.wxml`。 |
| `page-file-case-mismatch` | error | 页面文件存在，但文件名大小写与注册的路径不一致。 |
| `unknown-entry-route` | error | `entryPagePath` 未注册，或带有查询参数。 |

分包：

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `duplicate-subpackage-field` | error | 同时写了 `subpackages` 和 `subPackages`，只应使用一种写法。 |
| `invalid-subpackages` | error | `subpackages` / `subPackages` 不是数组。 |
| `invalid-subpackage` | error | 分包条目不是对象。 |
| `invalid-subpackage-root` | error | 分包缺少 `root`，或 `root` 不是可移植的相对目录路径。 |
| `overlapping-subpackage-root` | error | 分包根目录相同或相互嵌套。 |

tabBar：

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `invalid-tab-bar` | error | 声明了 `tabBar`，但 `tabBar.list` 不是数组。 |
| `invalid-tab-count` | error | tabBar 项数不在 2–5 之间。 |
| `tab-route-not-in-main-package` | error | tabBar 页面不是主包页面。 |
| `invalid-tab-icon-path` | error | 图标路径不是字符串，或越出小程序目录。深色模式下的 `@变量` 引用不报告。 |
| `missing-tab-icon-file` | error | tabBar 图标文件不存在。 |

分包预下载（`preloadRule`）：

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `invalid-preload-rules` | error | `preloadRule` 不是以页面路径为键的对象。 |
| `unknown-preload-route` | error | `preloadRule` 的键不是已注册的页面。 |
| `invalid-preload-rule` | error | 某条预下载规则不是对象。 |
| `invalid-preload-network` | error | `network` 不是 `wifi` 或 `all`。 |
| `invalid-preload-packages` | error | `packages` 不是数组。 |
| `invalid-preload-package` | error | `packages` 中的项不是字符串。 |
| `unknown-preload-package` | error | `packages` 中的名称既不是任何分包的 `name`，也不是 `root`。 |

聊天位置消息入口（`entranceDeclare`，依据 [app.json 配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html#entranceDeclare)）：

| code | 级别 | 触发条件 |
| --- | --- | --- |
| `invalid-entrance-declare` | error | `entranceDeclare` 或 `locationMessage` 不是对象，`path` 不是字符串，或 `query` 不是字符串。 |
| `unknown-entrance-route` | error | `locationMessage.path` 不是 `app.json` 中注册的页面（不带开头的 `/` 和查询参数）。 |

## 已知局限

- JS 分析基于词法，不做数据流：`const url = '/pages/a'; wx.navigateTo({ url })` 不检查。
- 只分析小程序目录本身。原生 TypeScript / Less / Sass 项目按 `useCompilerPlugins` 直接分析源码；Taro、uni-app 等框架项目请传入编译输出目录。
- TypeScript 的类型导入判断基于词法：作为对象属性值使用的绑定（`{ key: Name }`）会被误认为类型位置，对应 import 不会被检查。
- npm 依赖按开发者工具"构建 npm"后的 `miniprogram_npm` 查找。直接分析未构建的源码仓库时，npm 包会报 `unresolved-module` / `unresolved-component`。
- 体积是源文件字节的近似值，用于在开发阶段提前发现问题，最终以开发者工具的上传结果为准。
