上周帮一位同行看他写的前端小工具，代码拢共不到两百行，两个文件，一个入口引了一个格式化模块。他把 HTML 双击打开，控制台一片红，提示不能在普通脚本里使用导入语句。他以为是浏览器版本太旧，换了三个浏览器，结果一模一样。问题根本不在浏览器，而在于他把“写代码”和“交付代码”当成了同一件事。源码层面用模块拆分很舒服，但浏览器拿到的那一份，需要先被合并、被处理成它能直接执行的样子，这个动作就叫打包。ijc是我这两年用得比较顺手的一个轻量打包命令行工具，它不追求大而全，主打一个“单入口、少配置、出产物快”，特别适合小工具、脚本库、组件 Demo 这类规模不大但又要正经交付的场景。这篇内容就是把我自己踩过的流程完整走一遍：从环境清点、目录搭建，到跑出第一个 JavaScript 捆绑包，再到配置文件里到底哪几项值得改、跑通之后最容易在哪翻车。不管你是刚接触构建工具的新手，还是被重型方案折腾过、想找个轻量替代的老手，都能直接照着抄。
1. 先把“为什么要打包”这件事说透
1.1 浏览器原生模块能用了，为什么还要多这一步
很多人第一反应是：现在浏览器不是支持原生模块了吗，加个type="module"不就完事了？这话对一半。原生模块确实解决了“语法能不能跑”的问题，但它没解决另外三件事。第一是请求数量：你写了二十个模块文件，浏览器就得发二十次请求，小项目还好，模块一多首屏就会被拖慢。第二是依赖解析：原生模块要求你在导入时写全相对路径甚至带扩展名，而你从包管理器装下来的第三方库，路径结构完全不是这么组织的。第三是语法降级与压缩：老一点的运行环境不认识可选链、空值合并这些写法，源码直接扔上去就是白屏。
打包器干的活，本质上是把“你写起来舒服的源码结构”翻译成“运行环境吃起来舒服的产物结构”。它沿着入口文件一路往下爬，把所有被导入的模块按依赖顺序拼成一份或几份文件，顺手做语法转换、去掉没被用到的代码、压缩空白和变量名。ijc在这个环节里的定位很明确：只做这条主干链路，不掺和图片压缩、CSS 预处理器、开发服务器那一整套。你给它一个入口，它给你一份能直接<script>引入的产物，中间不需要你理解一堆插件生命周期。
这也解释了为什么它的上手成本低。重型方案的学习曲线陡，很大一部分陡在“你得先建立一个插件系统的心智模型”，而轻量工具的逻辑是线性的：入口 → 解析 → 转换 → 输出。你只要搞清楚这四个环节各自的参数，剩下的就是熟练度问题。
1.2 ijc 在整个工具链里到底站哪个位置
我习惯把前端构建分成三层来看。最底层是转译器，负责把新语法变成老语法，它只管单个文件，不管文件之间什么关系。中间层是打包器，负责沿着导入关系把所有文件串起来，输出一份或几份产物，ijc站的就是这一层。最上层是任务编排，负责把打包、压缩、拷贝静态资源、起本地服务这些动作按顺序串成一条流水线。
想清楚这个分层，你就不会对 ijc 提过分要求。比如你问它“能不能帮我把 Sass 编译成 CSS”，答案是它本身不干这事，但你可以在打包之前用别的方式先把 Sass 处理成 CSS，再让 ijc 把 CSS 当资源导入处理。同理，它也不负责热更新和本地服务器，那属于上层编排的活。知道一个工具的边界在哪，比知道它能干什么更重要，因为边界决定了你什么时候该换工具，而不是硬着头皮给轻量工具加一堆外挂。
我自己的判断标准很土：项目里入口文件不超过五个、第三方依赖不超过二十个、没有复杂的按需加载需求，就用 ijc；一旦超过这个量级，或者团队里有人需要“改一行代码页面自动刷新”的开发体验，那就老老实实上重型方案。工具没有优劣，只有匹配度。
1.3 “3 分钟”这个承诺成立的前提
标题里的三分钟不是营销话术，但它有前置条件，我得先把丑话说在前面。三分钟能跑通的前提是：你已经装好了 Node 环境、机器能正常装包、项目是单入口、没有需要特殊处理的资源文件。这四条里任何一条不满足，时间都会往上翻。
- 没装 Node：先去装，装完
node -v能看到版本号再往下走，这一步卡住的人比想象中多。 - 装包慢或失败：多半是源的问题，换个镜像源，或者检查一下公司网络有没有拦截。
- 多入口：配置文件要多写几行，时间大概五分钟。
- 有图片、字体、CSS：需要额外配资源处理规则，时间视复杂度浮动。
我把这些说清楚，不是给自己留后路，而是让你在跑不通的时候知道问题出在哪一层，而不是怀疑工具本身有毛病。真正跑起来之后你会发现，命令行那一行才是最简单的部分，难的是配置项的理解和产物的验证。
2. 动手前的环境清点与目录骨架
2.1 Node 版本与包管理器的最小要求
IJc 本身是跑在 Node 上的命令行程序，所以 Node 版本是硬门槛。我的建议是至少 16.x，最好是 18.x 及以上的 LTS 版本。原因不复杂：低版本 Node 对 ES 模块的原生支持不完整，你在配置文件里写export default会直接报语法错误，而打包器内部的很多解析逻辑也依赖较新的 API。查版本很简单，终端里敲：
node -v npm -v两条都能正常输出版本号，环境就算通了。如果node -v报“命令未找到”，说明 Node 没装或者没进环境变量，这时候别急着往下走，先把这步解决。Windows 上装完记得重开一个终端窗口，环境变量才会生效，这个坑我见过太多次。
包管理器用 npm、yarn、pnpm 都行，ijc 对三者没有偏好。我平时用 npm，因为它是 Node 自带的，少一层依赖。如果你所在的项目已经在用 pnpm，那就跟着项目走，别为了一个工具单独换包管理器，那会让 lock 文件乱掉。
2.2 一个刚好够用的目录结构
新手最容易犯的错是把源码和产物混在一个目录里，跑两次之后自己也分不清哪个文件是手写的、哪个是生成的。我推荐的骨架是这样，简单到不能再简单：
demo-bundle/ ├── src/ │ ├── index.js │ └── format.js ├── dist/ # 产物目录，不用手动建，工具会建 ├── index.html # 验证用，正式项目里就是你的页面 ├── ijc.config.js # 配置文件，先不用建，第三步再说 └── package.jsonsrc放源码，dist放产物，两者严格分开。这条规矩看着朴素，价值极大：一来你不会误删源码，二来产物目录可以整个加进版本控制的忽略列表，不会出现“某次提交把压缩后的 bundle 也提上去了”这种事故。我见过一个项目因为产物和源码混在一起，某次合并冲突把index.js覆盖成了压缩版，排查了整整一个下午。
初始化项目就一行：
npm init -y生成的package.json里，我建议手动补两个字段。一个是"private": true，防止误发布到公共仓库；另一个是"type": "commonjs"或者"module"，这个字段决定了.js文件被当成哪种模块系统解析，它和打包器的输出格式是两回事，很多人在这里混淆，后面第五步会专门讲。
2.3 依赖装在哪：本地安装优先于全局安装
装 ijc 有两种方式，我强烈建议用本地安装：
npm install --save-dev ijc为什么不推荐-g全局装？三个理由。第一，版本锁定：全局装的是“当前最新”，半年后别人拉你的代码，装到的可能是另一个大版本，行为不一致。本地安装会写进package.json的devDependencies，谁拉代码谁装到同一个版本。第二，CI 环境：自动化流水线里通常不会预装全局包，本地依赖才能被正常安装。第三，权限问题：全局安装在某些系统上需要管理员权限，容易卡住新手。
装完之后验证一下：
npx ijc --versionnpx会自动去node_modules/.bin里找可执行文件，能打出版本号就说明装好了。如果报“找不到命令”，通常是安装过程被中断了，删掉node_modules重新装一次。这一步还有个细节：如果npx ijc --version打出来的是另一个不相干的工具版本，说明你的机器上存在同名命令，这时候用./node_modules/.bin/ijc --version明确指定路径，能排除干扰。
3. 第一个捆绑包：从两行源码到可运行产物
3.1 先写两个有真实依赖关系的模块
为了让打包这件事有意义，源码里必须真的有导入关系。只有一个文件的话，打包器等于什么都没干，你也就看不出它到底做了什么。我在src/format.js里写一个纯函数：
// src/format.js export function toKebab(str) { return str .trim() .replace(/([a-z])([A-Z])/g, '$1-$2') .replace(/[\s_]+/g, '-') .toLowerCase(); } export function toTitle(str) { return str .trim() .split(/[\s_-]+/) .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()) .join(' '); }然后在src/index.js里导入并调用它：
// src/index.js import { toKebab, toTitle } from './format.js'; const input = 'helloWorld demo_case'; console.log(toKebab(input)); console.log(toTitle(input)); document.querySelector('#out').textContent = toKebab(input);注意第二行导入时我带了.js扩展名，这是刻意为之。原生模块解析要求带扩展名，打包器的解析规则则更宽松，允许省略。我建议源码里统一带上，原因有两个：一是这样源码本身在浏览器里加个type="module"就能直接跑，调试方便；二是将来换任何打包器都不会因为省略扩展名而踩坑。写代码时多打四个字符，能省掉后面一堆排查时间，这笔买卖很划算。
3.2 执行那一行命令，并且读懂它吐出来的信息
最简形式的打包命令是这样：
npx ijc src/index.js --outfile dist/bundle.js --format iife三个参数的含义：src/index.js是入口，工具从这里开始往下爬；--outfile指定产物路径；--format iife指定输出格式，iife 的意思是“立即执行函数表达式”，它会把所有代码包在一个自执行函数里，避免污染全局作用域，是最适合直接用<script>引入的格式。
跑完之后，终端会打印类似这样的信息：
ijc v1.x entry src/index.js output dist/bundle.js format iife modules 2 size 1.4 kB done in 42ms这几行信息每一行都有用。modules 2告诉你一共打包进去几个模块，如果你预期是三个却显示两个，说明有一个导入没被解析到，可能是路径写错了、也可能是那个模块被判定为未被使用。size是产物体积，第一次看没感觉，等你加了第三方库之后就能看出哪些依赖是“体积大户”。done in 42ms是耗时，小项目通常都在百毫秒以内，如果某次突然变成好几秒，多半是某个依赖解析卡住了。
如果命令报错，最常见的两类是“找不到入口”和“找不到模块”。前者检查路径拼写和当前所在目录，后者看报错里给出的那个路径，通常是相对路径的基准搞错了——相对路径是相对于执行命令时所在的目录，不是相对于入口文件所在的目录，这个区别是新手最容易栽的地方，我在第五步会展开讲。
3.3 把产物塞进页面，验证它真的能跑
产物有了，得验证。写一个极简的index.html：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>ijc 打包验证</title> </head> <body> <p id="out">等待脚本输出...</p> <script src="./dist/bundle.js"></script> </body> </html>特别注意：这里不需要写type="module"。因为 iife 格式的产物本身就是一个普通脚本，它内部已经把模块系统转换掉了。如果你习惯性加了type="module"，在某些情况下反而会引发作用域问题。这是我早期踩过的坑，加了之后页面白屏，控制台没有任何报错，排查了半天才发现是这一行属性。
打开页面，如果看到段落文字从“等待脚本输出”变成了hello-world-demo-case，恭喜，第一个捆绑包正式跑通了。控制台里还应该有两行输出，那是源码里console.log的结果。生产环境当然要清掉这些日志，但调试阶段它们是最好用的验证手段。
顺便说一句，如果你不想起本地服务器，直接双击 HTML 文件也能跑。这一点很重要——iife 格式的产物没有跨域限制，本地文件协议下照样执行。而如果你选了 esm 格式，本地双击就会因为模块跨域策略被拦下来，必须起个服务。所以“格式选择”和“验证方式”是绑在一起的，不是随便选选。
4. 配置文件里真正要改的就那么几项
4.1 入口、出口与格式的取舍不是随便选的
命令行参数适合一次性验证，正经项目要把配置固化下来。在项目根目录建一个ijc.config.js：
// ijc.config.js module.exports = { entry: 'src/index.js', output: { file: 'dist/bundle.js', format: 'iife', name: 'DemoLib', }, minify: false, sourcemap: true, target: 'es2015', };格式这一项是最容易选错的，我用一张表把常见四种讲清楚：
| 格式 | 适用场景 | 引入方式 | 全局污染 |
|---|---|---|---|
| iife | 页面内直接用的小脚本、Demo | <script src> | 无（包在自执行函数里） |
| esm | 现代构建环境、别的打包器继续处理 | <script type="module">或import | 无 |
| cjs | Node 环境、老版本工具链 | require() | 无 |
| umd | 既要给页面又要给 Node、要给第三方用 | 两种都能用 | 视情况 |
选择逻辑其实很简单，你就问自己一个问题：这份产物最终由谁消费？如果答案是“浏览器页面直接引入”，选 iife；如果是“会被别的构建流程再处理一次”，选 esm；如果是“给别人在 Node 里require的库”，选 cjs；如果“说不清，可能都有人用”，选 umd，代价是体积稍微大一点点，因为它要写兼容判断。
name这一项只在 iife 和 umd 下有意义，它决定产物挂到全局的那个变量名叫什么。上面的配置里叫DemoLib，那页面里就能通过window.DemoLib访问到入口文件导出的东西。这个名字一定要跟你的模块语义对齐，别用app、main、bundle这种，三个月后你自己都想不起来它是干什么的。
4.2 压缩与 sourcemap：什么时候开，什么时候关
minify和sourcemap这两项，我的默认策略是开发阶段全关，出包阶段全开，但中间有个折中方案值得说。
开发阶段把minify关掉，理由很实在：产物保持可读，你打断点、看报错行号、检查某个函数到底有没有被打进去，全都方便。一旦压缩，变量名变成a、b、c，堆栈里全是天书。跑通之后再打开压缩，看看体积降了多少，心里有个数。
sourcemap的情况相反，开发阶段一定要开。它会在产物旁边生成一个.map文件，浏览器开发者工具会自动读取，让你在调试时看到的是原始源码而不是打包后的拼接结果。没有它，报错行号会完全对不上，你会在一个根本不存在的位置找 bug。
module.exports = { // ... minify: process.env.NODE_ENV === 'production', sourcemap: process.env.NODE_ENV !== 'production', };用环境变量来切换是我比较推荐的做法，一行配置搞定两套行为，不用维护两个配置文件。有个细节要注意：sourcemap 文件不应该跟着产物一起上线，它包含完整源码，属于内部调试资料。上线前把它移到别处，或者在部署脚本里排除掉。
4.3 外部依赖与目标环境：两个容易被忽略但很关键的点
target这一项决定产物能用哪些语法。设成es2015意味着产物里不会出现箭头函数、模板字符串之外的新语法，老一点的环境也能跑。设成es2020就能用可选链、空值合并，产物体积会小一点，因为不用做降级转换。
怎么选？看你需要支持的最低环境。如果只是内部工具、同事都用新版浏览器，直接es2020。如果要给外部用户用、不确定对方的浏览器版本，保守一点选es2015。不确定的时候选保守的，多出来的那点体积远比“用户打开白屏”要划算。
externals是另一个关键项，它的作用是“告诉打包器某些依赖不要打进来”。典型场景是你打包一个库，而这个库依赖了某个框架，框架应该由使用方提供，你打进来反而会造成重复加载甚至版本冲突：
module.exports = { entry: 'src/index.js', output: { file: 'dist/lib.js', format: 'umd', name: 'MyLib' }, externals: { lodash: '_', }, };配置了之后，产物里不会再包含 lodash 的代码，而是保留一个对全局变量_的引用。这里有个隐含约定：使用方必须自己先引入 lodash，并且挂在全局_上。这个约定要写进文档，不然别人用你的库会直接报“找不到变量”。我见过一个开源库就栽在这，配置文件里加了外部依赖，README 里一个字没提，issue 区堆了十几条“引入就报错”。
5. 跑通之后最容易翻车的五个地方
5.1 路径解析：相对路径的基准到底在哪
这是最高频的问题，没有之一。现象是打包时报“无法解析模块”，路径看起来完全正确。根因在于相对路径的基准是执行命令时的当前工作目录，而不是入口文件所在目录。
举个例子，你在项目根目录执行npx ijc src/index.js，入口里写import './format.js'。这个./解析时，工具会以入口文件所在目录为基准去找，所以能找到src/format.js。但如果你在配置文件的entry里写了./src/index.js，而命令是在别的目录执行的，基准就变了，全程错位。
我的处理原则是三条：第一，所有命令和配置都在项目根目录执行，别在子目录里跑；第二，配置文件里的路径相对于配置文件本身，而不是相对于执行目录，这一点不同工具有细微差别，遇到问题先用最笨的办法——写成从根目录算起的完整相对路径；第三，源码里的导入统一带扩展名，前面说过，这条能省掉大量猜测。
排查手段也很直接：报错信息里通常会打印“从哪个文件解析哪个路径失败”，把这两个路径抄出来，手动去文件系统里对一遍，十有八九能立刻看出问题。
5.2 循环依赖为什么表现为“一半是 undefined”
第二个坑更隐蔽。你写了 A 导入 B、B 又导入 A，打包不报错，运行起来却发现某个导出是undefined。这不是打包器的 bug，是模块系统的固有行为。
原理是这样的：模块加载是有顺序的，A 先执行，执行到导入 B 那行时，转去执行 B；B 执行时又要用 A 的东西，但此时 A 还没执行完，它导出的值还是空的，于是 B 拿到undefined；B 执行完回到 A，A 继续往下走。结果就是“先执行的那个模块，在被对方引用时是空的”。
解决思路有三条，按推荐程度排序：
- 重构，把共享逻辑抽到第三个模块。这是根治方案，A 和 B 都去依赖 C，依赖图变成树而不是环。
- 把导入改成运行时取值。比如不要
import { fn } from './a'然后在顶层调用，改成在函数体内部调用，把执行时机推迟到两个模块都初始化完成之后。 - 延迟执行。用微任务或者事件把逻辑推到下一轮事件循环，代价是代码变得不好读。
我的经验是，只要发现循环依赖，就别想着“绕过”，它一定是模块职责划分不清的信号。绕过去只会让下一个接手的人再踩一遍。
5.3 非 JS 资源的处理策略
ijc 的主职是打包 JavaScript，但真实项目里总会遇到 JSON、CSS、甚至图片。处理策略分三档。
JSON 一般开箱可用，导入进来就是一个普通对象，很多工具默认支持，用之前先试一下，报错再配。
CSS 需要单独处理。如果只是想把它塞进产物、运行时动态插到页面里，需要配置对应的处理规则；如果想抽成独立的.css文件，让它和 JS 并行加载（这对首屏渲染更友好），那就得额外指定抽离配置。我倾向后者，因为样式越早加载越好，塞在 JS 里意味着必须等脚本执行完样式才生效，用户会看到一闪而过的无样式内容。
图片和字体这类二进制资源，小体积的可以转成 base64 内联进产物，减少请求数；大体积的一定要走文件拷贝，内联会让产物体积爆炸。分界线我一般设在 8KB，跟业界惯例保持一致：小于 8KB 内联，大于 8KB 输出独立文件。这个数字不是拍脑袋来的，它大致对应“一次额外 HTTP 请求的开销”和“体积增加带来的传输开销”的平衡点。
5.4 体积没降反升：tree-shaking 失效的几种写法
tree-shaking 的意思是“把没被用到的导出摇掉”。听起来很美，但它生效有前提，写法不对就完全失效。
第一种失效写法：CommonJS 的导出方式。如果你在源码里用module.exports = {...}而不是export，打包器无法静态分析出哪些属性被用到，只能整包保留。所以要 tree-shaking，源码就得用 ES 模块语法，这是硬条件。
第二种：模块有副作用。打包器默认认为“导入一个模块可能产生副作用”，所以不敢随便删。如果你的工具函数是纯的、导入它不会有任何副作用，可以在package.json里声明：
{ "sideEffects": false }这一行能让打包器放心大胆地删。但要注意，如果你的模块里真的有副作用代码（比如往原型上挂方法、注册全局事件），声明成false会导致这些代码被误删，运行时莫名其妙缺功能。所以这个字段要慎用，只在你确认模块纯净时加。
第三种：动态导入。import(变量)这种写法打包器无法静态确定要加载哪个模块，只能把可能的都保留下来。能用静态导入就别用动态。
验证 tree-shaking 是否生效，最直接的办法是看产物体积。写一个只用到某个导出的小入口，打包出来看看体积，如果接近整个库的大小，说明没摇掉。还可以打开压缩后的产物搜一下，看那些没被使用的函数名（压缩后是混淆过的，但可以通过字符串常量、特定数字去定位）还在不在里面。
5.5 多入口与代码分割的配置顺序
当项目从一个入口变成多个，配置要改两处：entry从字符串变成对象，output.file要改成output.dir：
module.exports = { entry: { main: 'src/index.js', admin: 'src/admin.js', }, output: { dir: 'dist', format: 'iife', }, };这里有个顺序陷阱：如果你同时开启了代码分割，公共依赖会被抽成一个独立 chunk，页面引入时就必须先引 chunk 再引入口。顺序反了就是“找不到变量”。而如果你关掉分割，每个入口会把公共依赖各打一份，体积翻倍但引入简单。
怎么选？两个入口以下，我建议关掉分割，简单直接；三个以上且公共依赖占比较大，再开分割。判断“占比大不大”的办法是看两次打包的体积差，差得多就说明公共部分值得抽出来。
6. 从“能跑”到“敢用”：产物验证与构建提速
6.1 产物自检清单：上线前我会挨个过一遍
跑通和敢用是两码事。每次出包前，我会按这张清单过一遍，大概两分钟，能拦掉绝大多数事故：
| 检查项 | 怎么查 | 不通过的典型症状 |
|---|---|---|
| 产物是否存在 | 看dist目录 | 命令成功但文件没生成，多半是输出路径写错 |
| 体积是否异常 | 对比上次构建 | 突然翻倍，通常是某个依赖被整包打进来 |
| 是否残留调试代码 | 搜console.log、debugger | 控制台刷屏、断点卡住 |
| sourcemap 是否排除 | 查部署包内容 | 源码泄露 |
| 全局变量是否冲突 | 页面里查window.xxx | 和别的脚本打架，功能互相覆盖 |
| 老环境能否执行 | 用低版本环境实测 | 白屏，控制台报语法错误 |
表格里最后一条最容易被忽略。target设成es2020之后，产物里可能带有可选链，而某些环境不支持。这件事不能靠推理，必须实测，找一台配置较低的机器或者用虚拟环境跑一遍，比查十分钟兼容性文档都管用。
6.2 构建缓存的开启条件与失效时机
小项目其实用不着缓存，几十毫秒的事。但一旦依赖多起来，每次全量解析会明显变慢，这时候开缓存就有价值了。大部分打包工具都提供缓存选项，通常是cache: true或者指定一个缓存目录。
缓存能生效的前提是输入没变。什么叫输入？源码内容、依赖版本、配置文件、环境变量，这些都算。所以你会遇到这种情况：改了配置文件，缓存没失效，产物还是旧的，你以为配置没生效，反复改了好几遍。遇到“改了没反应”，第一件事就是清缓存重跑，这一步能省掉无数自我怀疑。
什么情况下要主动清缓存？我总结了几条：升级了打包工具版本、改了配置文件、改了package.json里的依赖、以及任何“我觉得应该生效但就是没生效”的时刻。清缓存的方式一般是删掉缓存目录，或者加个--no-cache参数跑一次。
6.3 什么信号出现时该换掉 ijc
工具是要迭代的，轻量工具解决不了复杂问题，这不是它的缺点。我遇到下面这些信号时，会认真考虑换方案：
- 开发时要频繁改样式看效果，却没热更新：每次手动刷新，一天下来浪费的时间很可观。
- 需要按路由做懒加载：轻量工具的代码分割能力通常有限，做精细的按需加载会很难受。
- 团队里有人不熟悉命令行：需要图形化界面或者更成熟的一键脚本。
- 构建流程要塞进十几个步骤：拷贝资源、生成版本号、上传、通知，这些编排不是打包器的活。
反过来，如果项目就是“写个小工具发给同事用”、“做个组件 Demo”、“写个脚本挂到页面上”，ijc 这种轻量方案反而更合适，因为它没有一堆需要维护的配置和依赖。工具选型的本质是匹配复杂度，不是比拼功能数量，用重型方案做小工具，最后往往是配置比业务代码还长。
7. 我个人的几条实操心得
说几条文档里不会写、但实际做起来很有用的。
第一，先跑通最简版本，再往上加配置。我见过太多人一上手就把配置文件写得满满当当，一次没跑通，然后面对十几个配置项不知道从哪排查。正确的顺序是：先用一行命令跑通单入口无配置，确认链路是通的；再逐项加配置，每加一项跑一次。这样任何一次失败都只可能是一个原因，排查成本降到最低。
第二，把打包命令写进package.json的 scripts 里。别每次都手敲长命令，容易漏参数：
{ "scripts": { "build": "ijc src/index.js --outfile dist/bundle.js --format iife", "build:prod": "NODE_ENV=production ijc src/index.js --outfile dist/bundle.min.js --format iife --minify" } }这样npm run build就是构建，npm run build:prod就是出生产包。好处是命令变成项目的一部分，别人拉代码不用问你怎么构建。注意 Windows 上NODE_ENV=xxx这种前缀写法不生效，需要借助跨平台工具，或者干脆用两个配置文件，别在这上面死磕。
第三，产物不要提交到版本库，但产物目录要保留一个占位。dist整个加进忽略列表，同时在目录里放一个.gitkeep空文件，保证目录结构存在。这样既不会污染提交记录，clone 下来目录结构又是完整的。
第四，遇到报错先看报错的第一行，不要从最后一行往上读。打包器的报错通常是层层包裹的，最外层是“构建失败”，中间是“某个插件出错”，最里面才是“某个文件的某一行语法有问题”。真正有用的信息在最后那一小段，但定位问题要先从“是哪个环节失败”开始。我通常是先看“哪个文件”，再去看那个文件对应行。
最后分享一个我最近才用上的小技巧：给产物加一行版本注释。在配置里配一个 banner，把构建时间和版本号打进去，输出成产物的第一行。这样一来，线上出了问题，你打开产物看一眼就知道是哪个版本、什么时候构建的，不用去翻部署记录。就这一行注释，帮我省过至少两次排查时间，因为可以立刻排除“线上的包是不是旧的”这个可能性。
