mpbuild

图驱动的微信小程序构建工具

简介

mpbuild 5.x 是一次图驱动的整体重写：从源文件出发构建依赖图，经归属分析、Output Plan 到变换写盘，四段流水线职责清晰。历史上的 mpbuild@4（无作用域包）已冻结，不会再发布新版本；当前发布的包是 @mpbuild/core 与 @mpbuild/cli，命令行为 mpb。

为什么是图驱动

小程序不是「一个 JS bundle」，而是页面、组件、模板、样式、JSON、npm 互相引用的一张网。4.x 用 loader 链顺序处理文件，分包归属和增量更新都很难推理。

5.x 先把这张网建成图，再在图上染色（谁属于主包 / 分包 / shared），再生成一份确定性的 Output Plan，最后才做 SWC / Lightning CSS 变换并写盘。watch 是图上的 patch，不是整盘重跑。

特性

图驱动流水线 — 建图 → 归属分析 → Output Plan → 变换写盘，行为可推理、可检查
SWC + Lightning CSS — JS/CSS 变换原生级速度，无沉重的前端编译链负担
精准分包 — 多源染色归属模型，shared 模块复制进分包或提升到主包可配
增量 watch + 磁盘缓存 — 内容 hash 增量建图，差量写盘，重启后缓存复用
条件编译与多态 — 文件级 infix（name.wx.js）+ 块级 @ifdef，编译时拆分多端代码
npm 支持 — 内置 npmCompat 变换，海量 npm 包开箱即用
插件体系 — load / generate 两段钩子，官方提供 SCSS、projectConfig、copy 插件
可观测 — mpb analyze 产物分析、mpb inspect graph 逐节点图检查、16 个语义化诊断码

要求

Node.js >= 20
包为纯 ESM

快速开始

npm i -D @mpbuild/cli

@mpbuild/cli 依赖 @mpbuild/core，装这一个即可。

在项目根目录新建 mpbuild.config.mjs：

import { defineConfig } from '@mpbuild/core'

export default defineConfig({
  entry: './entry.js',
  src: 'src',
  platform: 'wx',
  output: { dir: 'dist' },
})

对应的 entry.js（router 形态——由 entry 直接生成产物 app.json，无需磁盘 src/app.json）：

module.exports = {
  router: [
    { root: '', pages: { 'pages/index/index': '/pages/index/index' } },
  ],
}

src 目录下必须存在 app.js 或 app.ts，否则报 MISSING_APP_JS。entry 另有经典形态（{ pages, subPackages }），其页面结构以磁盘 src/app.json 为准且该文件必须存在，entry 里的字段不会被消费——两种形态的差异与坑点见文档站 entry 与路由。

mpb build   # 构建一次
mpb dev     # 构建并进入 watch

完整可运行示例见 example/demo。全部配置项见文档站配置参考。

命令

命令	作用
`mpb build`	全量构建。`--minify` 覆盖 `compile.minify`；`--no-cache` 跳过磁盘变换缓存
`mpb dev`	首次构建后进入 watch，诊断打到 stderr，进程保持
`mpb analyze`	写出 `<output.dir>/mpbuild-analyze.json`（图 + plan）
`mpb inspect graph`	把每个节点的 id / owner / 出边打印到 stdout

mpb --watch 与 mpb build --watch 等价于 mpb dev（watch 分支不应用 --minify）。退出码：0 成功 / 1 含 error 级诊断 / 2 配置错误。

官方插件

import { defineConfig, legacyScss, projectConfig, copy } from '@mpbuild/core'

export default defineConfig({
  src: 'src',
  entry: './entry.js',
  plugins: [
    legacyScss(),
    projectConfig({ projectname: 'demo', appId: 'touristappid' }),
    copy(['src/**/*.png']),
  ],
})

插件	作用
`legacyScss()`	用 postcss-scss 解析类 SCSS（变量 / 嵌套 / mixin）
`projectConfig()`	生成 `project.config.json`，不覆盖已有文件
`copy(patterns)`	把 glob 匹配的 extras 拷进产物（`**` 含零层目录）

npm 兼容变换是内置的，不必再加插件。插件 API 与 4.x Tapable 不兼容，见插件 API。

文档

文档站：https://ximing.github.io/mpbuild/

常用入口：

从 4.x 迁移

Warning

5.x 与 4.x 不兼容，升级前请至少注意以下 breaking changes：

包名变更：mpbuild → @mpbuild/core + @mpbuild/cli，无作用域的 mpbuild 包不再发布
配置文件改名：只读取 mpbuild.config.{ts,mts,js,mjs}，不再读取 mpb.config.js（报 LEGACY_CONFIG，退出码 2）
require('./x.json') 不再内联：JSON 作为模块入图处理，产物形态与 4.x 不同
插件 API 全新：load / generate 两段钩子，与 4.x 插件不兼容