mpbuild

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

文档站 · 快速开始 · 从 4.x 迁移

简介

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'exportdefaultdefineConfig({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'exportdefaultdefineConfig({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/

常用入口：

• 快速开始
• 架构：四段流水线
• 配置参考
• CLI 参考
• 插件 API
• 诊断码
• FAQ

从 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 插件不兼容

完整迁移指南见文档站从 4.x 迁移与 docs/migration-v5.md。

包与仓库布局

包	路径	说明
@mpbuild/core	packages/core	图驱动编译器核心
@mpbuild/cli	packages/cli	命令行 mpb

5.x 代码位于 packages/；金样示例在 example/demo。

生态链接

• CHANGELOG.md — 版本变更记录
• CONTRIBUTING.md — 贡献指南
• Issue 模板 / PR 模板

License

MIT

Contributors ✨

Thanks goes to these wonderful people (emoji key):

席铭 💻📝📖💡🚧

yozosann 🐛💻

liujin123456 🐛💻

Yuchen 🐛💻

This project follows the all-contributors specification. Contributions of any kind welcome!