Belmont：零配置现代JS库构建工具，基于Esbuild与Rollup的极简实践-平芜编程栈

1. 项目概述：一个被低估的现代前端构建工具

如果你最近在GitHub上搜索过前端构建工具，可能会看到一个名为“belmont”的项目，它的star数或许不算惊人，但当你点开它的仓库，看到作者是blake-simpson，并且其设计理念与当前主流工具截然不同时，你可能会像我一样，产生强烈的好奇心。Belmont不是一个试图取代Webpack或Vite的庞然大物，它的定位非常清晰：一个极简、快速、专注于现代JavaScript库开发的构建工具。在如今前端工具链日益复杂，一个简单的项目动辄需要几十个依赖、几百兆node_modules的时代，Belmont的出现像一股清流，它试图回答一个问题：我们真的需要那么复杂的配置才能构建一个高质量的库吗？

我最初接触Belmont是因为一个内部工具库的项目。那个项目不大，但需要同时支持ES模块和CommonJS格式的输出，并且希望构建速度足够快，开发体验足够流畅。当时我尝试了Rollup + 一堆插件，配置起来颇为繁琐；也试了Vite的库模式，虽然体验不错，但总觉得为了一个小库引入整个Vite生态有些“杀鸡用牛刀”。直到发现了Belmont，它的简洁和直接打动了我。它没有配置文件，或者更准确地说，它遵循“约定大于配置”的原则，大部分行为都是智能推断的。你只需要写好你的源码，运行一个命令，它就能帮你处理好从编译、打包到类型声明生成的所有事情。这对于那些追求开发效率、厌恶复杂配置的开发者来说，无疑是一个福音。

Belmont的核心用户画像非常明确：现代JavaScript库和工具包的开发者。无论你是要发布一个到npm的通用工具函数库，还是一个供团队内部使用的React组件库，只要你的代码是基于ES模块编写的，并且希望输出格式干净、构建过程透明，那么Belmont就值得你花时间了解一下。它尤其适合那些崇尚“简单即美”哲学，不愿意在构建配置上耗费过多精力的独立开发者或小团队。接下来，我将带你深入拆解Belmont的设计思路、核心功能，并分享我从零开始用它构建一个真实项目的完整过程与踩坑经验。

2. 核心设计理念与架构解析

2.1 为什么是“零配置”？

Belmont最吸引人的特性就是其宣称的“零配置”体验。但这并不意味着它功能简陋。恰恰相反，它的“零配置”建立在几个非常聪明的设计决策之上。首先，Belmont深度拥抱了现代JavaScript项目的标准结构。它默认你的源码放在src目录下，入口文件是src/index.js（或.ts、.jsx等）。它默认你的项目根目录下有一个符合规范的package.json。通过读取package.json中的main、module、types等字段，Belmont就能自动推断出你需要构建的目标格式（CommonJS、ES模块）以及类型声明文件的位置。

这种设计极大地减少了心智负担。回想一下用Webpack或Rollup的体验：你需要显式地指定入口点、输出路径、输出格式、外部依赖等等。而在Belmont中，这些信息都直接从项目已有的元数据中推导而来。例如，如果你的package.json中定义了"main": "dist/index.cjs.js"和"module": "dist/index.esm.js"，Belmont就会自动为你构建出对应的CommonJS和ES模块包。这种“约定大于配置”的理念，让开发者可以更专注于代码本身，而不是构建脚本。

注意：Belmont的“零配置”是有前提的。它要求你的项目结构是规范的。如果你的源码分散在多个非标准目录，或者入口文件命名特殊，那么你可能需要通过极简的配置文件（如belmont.config.js）或命令行参数来指定。但即便如此，其配置量也远小于传统工具。

2.2 底层引擎：Esbuild与Rollup的强强联合

Belmont并不是又一个从头实现的打包器，它是一个精巧的“集成层”。它的构建核心建立在两个当今最优秀的底层工具之上：Esbuild和Rollup。Belmont根据不同的任务，智能地调用它们，发挥各自的长处。

Esbuild用于极速的转译（Transpilation）：对于TypeScript、JSX等非标准JavaScript语法的转换，Belmont使用Esbuild。Esbuild由Go语言编写，其转译速度是Babel的几十甚至上百倍。这意味着你的.ts或.jsx文件能在眨眼间被转换成纯净的JavaScript，这是开发阶段热更新速度的基石。
Rollup用于精准的打包（Bundling）：对于将多个模块打包成单个文件（或少数几个文件），并实施Tree-shaking（摇树优化）以删除无用代码，Belmont则委托给Rollup。Rollup在生成扁平化包和Tree-shaking方面依然是行业标杆，它能确保最终产物体积最小化。

这种分工协作的架构，使得Belmont在速度和输出质量上取得了很好的平衡。你既享受了Esbuild带来的开发时闪电般的速度，又获得了Rollup产出的高度优化的生产包。相比之下，一些纯基于Esbuild的工具在Tree-shaking的完备性上可能稍逊一筹，而纯Rollup的方案在开发阶段的冷启动和热更新上又不够快。Belmont的聪明之处就在于它没有重复造轮子，而是做了一个优秀的“调度员”。

2.3 开箱即用的完整工具链

一个完整的库构建流程远不止将源代码转换成目标格式。它通常还包括：生成类型声明文件（对TypeScript项目）、启动一个开发服务器用于实时预览和调试、执行代码质量检查（如ESLint）、运行测试等。Belmont将这些功能都集成在了一个统一的命令行接口中。

belmont build：执行生产构建。它会清理旧的dist目录，执行类型检查（如果用了TS），运行转译和打包，并最终生成类型声明文件（.d.ts）。
belmont dev：启动开发模式。这会启动一个开发服务器，并监听文件变化。任何对src目录下文件的修改都会触发极速的重建和浏览器的热更新。这对于开发带有演示页面的组件库尤其方便。
belmont check：执行类型检查（仅TypeScript项目）。这相当于运行tsc --noEmit，但速度可能更快，因为它内部可能也利用了Esbuild。
belmont lint：运行ESLint。这需要你的项目已配置ESLint。

这种一体化的设计，让你无需再在package.json的scripts里写下一长串诸如"build": "rimraf dist && tsc && rollup -c && tsc --emitDeclarationOnly"这样的复杂命令。一个belmont build就搞定一切，标准化了团队的构建流程。

3. 从零开始：使用Belmont构建一个工具库

理论说得再多，不如亲手实践。假设我们现在要构建一个名为color-utils的工具库，它提供一些颜色格式转换和计算的函数。我们将全程使用Belmont。

3.1 项目初始化与结构搭建

首先，创建一个新目录并初始化npm项目。

mkdir color-utils cd color-utils npm init -y

接下来，安装Belmont。由于它主要是一个开发依赖，我们将其安装在devDependencies中。

npm install --save-dev belmont

同时，因为我们计划用TypeScript来获得更好的类型提示，所以也安装TypeScript。

npm install --save-dev typescript

现在，创建标准的项目结构：

color-utils/ ├── package.json ├── src/ │ └── index.ts # 库的主入口 ├── test/ # 测试文件（可选，可用Jest/Vitest等） └── tsconfig.json # TypeScript配置

编辑package.json，设置好入口文件和构建输出目标。这是Belmont读取配置的关键。

{ "name": "color-utils", "version": "1.0.0", "description": "A utility library for color manipulation.", "main": "./dist/index.cjs.js", "module": "./dist/index.esm.js", "types": "./dist/index.d.ts", "exports": { ".": { "import": "./dist/index.esm.js", "require": "./dist/index.cjs.js", "types": "./dist/index.d.ts" } }, "files": ["dist"], "scripts": { "build": "belmont build", "dev": "belmont dev", "check": "belmont check", "lint": "belmont lint" }, "devDependencies": { "belmont": "^0.8.0", "typescript": "^5.0.0" } }

关键字段解析：

main: 指向CommonJS格式的包，供Node.js或老式构建工具使用。
module: 指向ES模块格式的包，供支持ESM的打包器（如Webpack、Rollup、Vite）使用。
types: 指向TypeScript类型声明文件。
exports: 现代包的条件导出，更精确地控制导入路径。这是当前npm包的最佳实践。
files: 发布到npm时包含的文件，通常只有dist目录。
scripts: 我们直接使用Belmont提供的命令。

创建tsconfig.json。这里不需要特别复杂的配置，Belmont对TypeScript有很好的默认支持。

{ "compilerOptions": { "target": "ES2020", "module": "ESNext", "lib": ["ES2020", "DOM"], "declaration": true, "declarationDir": "./dist", "outDir": "./dist", "strict": true, "moduleResolution": "node", "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist", "test"] }

实操心得：在tsconfig.json中，“declaration”: true和“declarationDir”的设置很重要，它们告诉TypeScript生成.d.ts文件并输出到dist目录。但请注意，Belmont在构建过程中会接管类型声明文件的生成流程，最终的.d.ts文件是Belmont调用tsc或类似工具生成的。这里的配置更多是给IDE和类型检查命令提供基础支持。

3.2 编写核心源码

现在，我们在src/index.ts中编写一些简单的颜色工具函数。

// src/index.ts /** * 将16进制颜色字符串转换为RGB数组。 * @param hex 如 `#ff0000` 或 `#f00` * @returns [r, g, b]，每个值范围0-255 * @throws 如果输入格式无效 */ export function hexToRgb(hex: string): [number, number, number] { // 移除#号，处理缩写形式 let sanitizedHex = hex.replace(/^#/, ''); if (sanitizedHex.length === 3) { sanitizedHex = sanitizedHex.split('').map(c => c + c).join(''); } if (!/^[0-9A-Fa-f]{6}$/.test(sanitizedHex)) { throw new Error(`Invalid hex color string: ${hex}`); } const r = parseInt(sanitizedHex.substring(0, 2), 16); const g = parseInt(sanitizedHex.substring(2, 4), 16); const b = parseInt(sanitizedHex.substring(4, 6), 16); return [r, g, b]; } /** * 将RGB数组转换为16进制颜色字符串。 * @param r 红色值 (0-255) * @param g 绿色值 (0-255) * @param b 蓝色值 (0-255) * @returns 如 `#ff0000` */ export function rgbToHex(r: number, g: number, b: number): string { const toHex = (n: number) => n.toString(16).padStart(2, '0'); return `#${toHex(r)}${toHex(g)}${toHex(b)}`; } /** * 计算两种颜色的混合色（简单线性混合）。 * @param color1 第一种颜色的RGB数组 * @param color2 第二种颜色的RGB数组 * @param factor 混合因子 (0-1)，0表示完全color1，1表示完全color2 * @returns 混合后的RGB数组 */ export function blendColors( color1: [number, number, number], color2: [number, number, number], factor: number ): [number, number, number] { const invFactor = 1 - factor; return [ Math.round(color1[0] * invFactor + color2[0] * factor), Math.round(color1[1] * invFactor + color2[1] * factor), Math.round(color1[2] * invFactor + color2[2] * factor), ]; }

3.3 执行构建与结果分析

代码写好了，现在运行构建命令。

npm run build

你会看到Belmont在终端输出简洁的构建日志。完成后，查看生成的dist目录：

dist/ ├── index.cjs.js # CommonJS格式包 ├── index.esm.js # ES模块格式包 └── index.d.ts # TypeScript类型声明文件

让我们检查一下index.esm.js的内容，看看打包效果：

// dist/index.esm.js function hexToRgb(hex) { let sanitizedHex = hex.replace(/^#/, ""); if (sanitizedHex.length === 3) { sanitizedHex = sanitizedHex.split("").map((c) => c + c).join(""); } if (!/^[0-9A-Fa-f]{6}$/.test(sanitizedHex)) { throw new Error(`Invalid hex color string: ${hex}`); } const r = parseInt(sanitizedHex.substring(0, 2), 16); const g = parseInt(sanitizedHex.substring(2, 4), 16); const b = parseInt(sanitizedHex.substring(4, 6), 16); return [r, g, b]; } function rgbToHex(r, g, b) { const toHex = (n) => n.toString(16).padStart(2, "0"); return `#${toHex(r)}${toHex(g)}${toHex(b)}`; } function blendColors(color1, color2, factor) { const invFactor = 1 - factor; return [ Math.round(color1[0] * invFactor + color2[0] * factor), Math.round(color1[1] * invFactor + color2[1] * factor), Math.round(color1[2] * invFactor + color2[2] * factor) ]; } export { blendColors, hexToRgb, rgbToHex };

可以看到，代码已经被转译成纯净的ES2020 JavaScript（根据tsconfig.json的target设置），三个函数被正确导出，格式干净，没有多余的包装代码。index.cjs.js内容类似，只是使用module.exports导出。index.d.ts文件则包含了完整的类型签名。

构建过程解析：

清理：Belmont首先清理dist目录（如果存在）。
类型检查：调用TypeScript编译器进行类型检查（相当于tsc --noEmit）。如果类型错误，构建会在此阶段失败。
转译与打包：这是核心步骤。Belmont会：
- 使用Esbuild将src/下的所有.ts文件快速转译为JavaScript。
- 根据package.json中的main和module字段，使用Rollup分别将转译后的代码打包成CommonJS和ES模块格式。Rollup会进行Tree-shaking，但由于我们目前只有一个入口文件，效果不明显。如果库内部有多个相互引用的模块，Rollup会移除未被入口文件引用的代码。
生成声明文件：再次调用TypeScript编译器（或类似工具），仅生成类型声明文件（.d.ts），输出到dist目录。

整个过程一气呵成，无需任何额外配置。你可以立即将dist目录发布到npm，或者在其他项目中通过npm link进行本地测试。

4. 高级用法与个性化配置

虽然Belmont推崇零配置，但它也提供了足够的扩展点来应对更复杂的需求。

4.1 使用配置文件进行微调

在项目根目录创建belmont.config.js（或.ts，如果你喜欢用TypeScript写配置）。这个文件需要导出一个配置对象。

// belmont.config.js import { defineConfig } from 'belmont'; export default defineConfig({ // 指定源码入口，默认是 `src/index.[jt]s` // entry: './src/main.ts', // 覆盖默认的构建输出目录 // outDir: './build', // 配置Rollup选项 rollup: { // 定义外部依赖，不打入包中 external: ['react', 'react-dom', 'lodash'], // 自定义Rollup插件 plugins: [ // 例如，使用 @rollup/plugin-node-resolve 和 @rollup/plugin-commonjs // 来处理某些特殊的第三方模块 ], // 输出配置 output: { // 为UMD格式设置全局变量名（如果需要的话） // globals: { // react: 'React', // 'react-dom': 'ReactDOM' // } } }, // 配置Esbuild选项 esbuild: { // 定义JSX的处理方式（如果不是React 17+的自动运行时） // jsx: 'transform', // jsxFactory: 'h', // jsxFragment: 'Fragment', // 目标环境 target: 'es2020', // 定义全局变量替换 define: { 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'production') } }, // 在构建完成后执行的钩子函数 afterBuild: () => { console.log('构建完成！'); // 可以在这里执行一些自定义脚本，如复制文件、运行测试等 } });

4.2 处理样式与静态资源

如果你的库包含CSS、SCSS或图片等静态资源，Belmont也能处理，但需要一点配置。Belmont默认只处理JavaScript/TypeScript文件。对于样式文件，一种常见的做法是让库的使用者自己处理（例如，提供单独的.css文件让用户导入）。另一种做法是在构建时将CSS提取到单独的文件中。

这通常需要通过Rollup插件来实现。例如，使用rollup-plugin-postcss：

安装插件：npm install --save-dev rollup-plugin-postcss
在belmont.config.js中配置：

import postcss from 'rollup-plugin-postcss'; // ... 其他导入 export default defineConfig({ rollup: { plugins: [ postcss({ extract: true, // 提取CSS到单独文件 minimize: true, // 生产环境压缩 // 可以配置使用Sass、Less等 // plugins: [require('autoprefixer')] }), // ... 其他插件 ] } });

这样，当你的TS/JS文件中导入./style.css时，该CSS文件会被处理并最终输出到dist目录（如index.css）。你需要在package.json中指明这个样式文件，以便用户使用。

4.3 集成测试与代码质量工具

Belmont的check和lint命令为集成测试和代码检查提供了入口。虽然Belmont本身不包含测试运行器，但它可以很好地与Jest、Vitest等工具协同工作。

推荐的方式是在package.json的scripts中定义你自己的测试命令，Belmont的命令与之互补。

{ "scripts": { "build": "belmont build", "dev": "belmont dev", "check": "belmont check", "lint": "belmont lint", "test": "vitest run", // 使用Vitest运行测试 "test:watch": "vitest", // 监听模式 "prepublishOnly": "npm run lint && npm run check && npm run test && npm run build" } }

prepublishOnly是一个npm生命周期钩子，在运行npm publish之前自动执行。这里我们让它依次执行代码检查、类型检查、测试和构建，确保发布到npm的包是高质量的。

5. 实战避坑与经验总结

在实际使用Belmont构建了几个项目后，我积累了一些宝贵的经验和遇到的一些“坑”。

5.1 常见问题与解决方案

问题现象	可能原因	解决方案
运行`belmont build`时报类型错误，但IDE里不报错。	Belmont使用的TypeScript版本或`tsconfig.json`的解析路径可能与IDE不同。	1. 确保项目根目录有正确的`tsconfig.json`。 2. 在`belmont.config.js`中显式指定`tsconfig`路径：`{ typescript: { tsconfig: './tsconfig.json' } }`。 3. 运行`npx tsc --noEmit`单独检查类型，看是否与Belmont报错一致。
构建后，`dist`目录下没有生成`.d.ts`类型声明文件。	1.`tsconfig.json`中未设置`"declaration": true`。 2. 源码不是TypeScript，或没有类型注解。 3. Belmont的TypeScript插件配置有误。	1. 检查并确保`tsconfig.json`包含`"declaration": true`。 2. 如果是纯JS项目想生成声明文件，需要使用JSDoc注释，并考虑使用`@microsoft/api-extractor`等工具，Belmont对纯JS项目的声明文件生成支持有限。 3. 尝试在配置中禁用Belmont内置的d.ts生成，改用`tsc`命令单独生成：在`afterBuild`钩子中执行`tsc --emitDeclarationOnly`。
开发服务器 (`belmont dev`) 热更新不工作。	1. 文件监听路径不对。 2. 可能是一些特殊的文件结构或符号链接导致。 3. 使用的插件与HMR有冲突。	1. 确认修改的文件在`src`目录下。 2. 检查项目路径中是否有特殊字符或过深的嵌套。 3. 如果使用了自定义Rollup插件，尝试暂时移除，排查是否是插件问题。Belmont的HMR基于Rollup插件，某些插件可能不兼容。
引入某些第三方库时，构建失败或运行时报错。	该第三方库的模块格式（CommonJS/UMD）与Belmont的打包环境不兼容。	1. 在`belmont.config.js`的`rollup.external`中将其标记为外部依赖，不打包进来。 2. 使用Rollup插件如`@rollup/plugin-commonjs`和`@rollup/plugin-node-resolve`来帮助处理这些模块。需要在配置中手动添加这些插件。
构建出的包体积比预期大很多。	Tree-shaking未生效，可能将未使用的代码打包进来了。	1. 确认你的代码是ES模块格式（使用`import/export`），这是Rollup进行Tree-shaking的前提。 2. 检查是否有副作用代码阻碍了Tree-shaking。可以在`package.json`中设置`"sideEffects": false`（如果你的库确实无副作用），或更精确地列出有副作用的文件。 3. 使用`rollup-plugin-visualizer`插件分析包内容，查看体积大的模块。

5.2 个人实操心得与建议

拥抱约定，但了解配置：Belmont的零配置在标准项目中非常爽快。但在开始一个复杂项目前，花10分钟阅读一下它的配置选项是值得的。了解belmont.config.js能做什么，可以让你在遇到需求偏差时快速找到解决方案，而不是试图推翻它的约定。
类型声明文件是门面：对于TypeScript库，.d.ts文件的质量至关重要。Belmont自动生成声明文件很方便，但有时对于复杂的类型导出（如命名空间、重载函数、条件类型）可能处理不够完美。构建后，务必检查dist/index.d.ts文件，确保导出的类型是准确和完整的。必要时，可以手动编写一个index.d.ts放在根目录，Belmont会优先使用它。
开发体验的权衡：belmont dev启动速度极快，这得益于Esbuild。但对于一个复杂的组件库，如果依赖了大量需要编译的样式语言（如SCSS）或非JS资源，开发服务器的热更新链可能会变长。这时，可以考虑将样式构建与JS构建分离，或者使用Vite作为开发服务器（Vite同样基于Esbuild），而用Belmont仅做生产构建。
生态兼容性：Belmont是一个较新的工具，其插件生态自然不如Webpack或Rollup原生那么丰富。当你需要集成一个非常小众的Rollup插件时，可能会遇到兼容性问题。我的建议是，优先寻找Esbuild或Rollup社区的主流插件，并在集成前在小型测试项目中验证。
保持依赖更新：Belmont自身以及它依赖的Esbuild、Rollup都在快速迭代。定期更新这些依赖，可以让你获得更好的性能、更多的功能和修复的bug。但升级时，务必仔细阅读变更日志，特别是主版本升级，可能包含不兼容的改动。

Belmont给我的感觉更像是一个精心打磨的“瑞士军刀”，它没有追求大而全，而是在一个特定的问题域（现代JS库开发）上做到了极致。它用极简的接口隐藏了底层工具的复杂性，为开发者提供了一条高效、省心的流水线。如果你的项目符合它的“胃口”，那么它带来的开发体验提升将是显著的。它可能不会成为下一个Webpack，但对于追求效率和简洁的库开发者来说，Belmont无疑是一个值得放入工具箱的利器。