mpbuild

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

简介

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

特性

• 图驱动流水线 — 建图 → 归属分析 → 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。全部配置项见文档站配置参考。

文档

文档站：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	v5/packages/core	图驱动编译器核心
@mpbuild/cli	v5/packages/cli	命令行 mpb

v5 代码位于 v5/ 下的独立 pnpm workspace；金样示例在 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!