第6章 注意事项与陷阱

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// 开启代码分割（必须在 format=esm 且 platform=浏览器场景下）
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  format: 'esm',
  splitting: true,
  // 只能用 import.meta.url，不能用 __dirname
  platform: 'browser',
});

1
2

// src/index.js
import('./moduleA.js'); // 动态导入，esbuild 会把它分割成单独的文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// app.ts
interface User {
  name: string;
  age: number;
}

function greet(user: User) {
  return `Hello, ${user.name}`;
}

const user: User = { name: '小明', age: '25' }; // 类型错误：age 应该是 number，这里给了 string
console.log(greet(user));

1
2
3
4
5

# 常见场景：你 import 了一个还没装的包
import _ from 'lodash'; // esbuild 找不到，报错

# 解决方案：先安装
npm install lodash

1
2
3
4
5

# 你满怀信心地运行 esbuild
$ npx esbuild src/app.ts --bundle --outfile=dist/app.js

# 构建成功，零报错，零警告
# 但你的 TypeScript 代码里有严重的类型错误……

1
2
3
4
5
6
7
8

# 在项目里安装 typescript
npm install --save-dev typescript

# 运行类型检查（不生成任何文件，只检查错误）
npx tsc --noEmit

# 如果有类型错误，会显示：
# error TS2322: Type 'string' is not assignable to type 'number'.

1
2
3

// index.js
import './styles.css';
console.log('Hello');

1
2

# 打包后，你期望得到 index.js 和 styles.css
# 但你只得到了 index.js，里面包含了 CSS 代码

1
2
3
4
5
6
7
8
9

// esbuild.config.js
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  loader: {
    '.css': 'css',  // 关键：告诉 esbuild 如何处理 .css 文件
  },
});

1
2
3
4
5
6
7
8
9

// 需要安装 esbuild-plugin-css-modules 或类似插件
import cssModulesPlugin from 'esbuild-plugin-css-modules';

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  plugins: [cssModulesPlugin()],
});

1
2
3
4
5

// 压缩前
/* @__PURE__ */ getBuildVersion(); // 无副作用的函数调用，esbuild 会保留

// 或者标记一个工厂函数（它自己无副作用，但返回值可能有副作用）
/* @__PURE__ */ (() => createWidget())();

1
2
3
4
5
6

$ esbuild src/index.js --bundle --watch --outfile=dist/index.js

[watch] build finished, watching for changes...

# 修改了 src/index.js
# 没有输出……没有重新构建……

1
2

// index.js
import utils from '@/utils'; // 你期望这个 "@/" 指向 "src/utils"

1
2
3
4
5
6
7
8

// esbuild.config.js
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  alias: {
    '@': 'src',  // 别名配置
  },
});

1
2
3
4
5
6
7

// 你写了这样的配置
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  platform: 'node',    // 平台是 Node.js
  format: 'iife',      // 但格式是 IIFE（浏览器格式）
});

1
2
3
4
5
6
7
8

// 你配置了代码分割
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  splitting: true,  // 开启代码分割
  format: 'cjs',    // 但用的是 CommonJS 格式 —— 这是不支持的
});

1

X [ERROR] Splitting currently only works with the "esm" format

1

format: 'esm',

1
2
3
4
5
6

const config = {
  minify: false,        // 不压缩，构建更快
  sourcemap: true,       // 要 sourcemap，方便调试
  target: 'es2015',     // 目标宽泛一些，减少转译工作
  treeShaking: false,   // 开发时关掉 Tree Shaking，减少分析时间
};

1
2
3
4
5
6
7

const config = {
  minify: true,                        // 压缩代码，减小体积
  sourcemap: process.env.SENTRY_DSN ? true : false,  // 如果接入了错误追踪就开启，否则关闭
  target: ['chrome80', 'firefox80'],    // 目标更精确，可以生成更小的代码
  treeShaking: true,                   // 必须开 Tree Shaking，删无用代码
  legalComments: 'none',               // 删除法律注释，进一步减小体积
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// esbuild.config.js
const esbuild = require('esbuild');

const isProduction = process.env.NODE_ENV === 'production';

async function build() {
  await esbuild.build({
    entryPoints: ['src/index.js'],
    outdir: 'dist',
    bundle: true,
    // 根据环境动态配置
    minify: isProduction,
    sourcemap: !isProduction,
    target: isProduction ? ['chrome80'] : ['es2015'],
  });
}

build();

1
2
3
4
5

# 开发构建
NODE_ENV=development node esbuild.config.js

# 生产构建
NODE_ENV=production node esbuild.config.js

1
2
3

// 用 ESM —— Tree Shaking 效果拉满，编译器一眼就知道谁没用
export function used() { return 1; }
export function unused() { return 2; }

1
2
3
4

// 用 CommonJS —— Tree Shaking 基本瞎了
module.exports.used = function() { return 1; };
module.exports.unused = function() { return 2; };
// ↑ 编译器：我怎么知道你以后会不会 require 这两个？

1
2
3
4
5
6
7

{
  "name": "my-lib",
  "sideEffects": [
    "./src/polyfills.js",
    "./src/global.css"
  ]
}

1
2
3
4
5

// 这段代码里的 someModule 会被排除在 Tree Shaking 之外
// 因为 esbuild 不知道 if 条件为 true 时到底会不会执行
if (someCondition) {
  import('./someModule.js');
}

1
2
3

// 这个模块有副作用：执行时会修改 window.title
window.title = 'Hello, World!';
export const name = '小明';

1
2

// 即使你 import 这个模块但不使用任何导出
import './hasSideEffect.js'; // esbuild 还是会把它打包进来，因为它是"有副作用"的

1
2
3
4
5

// 标记一个函数调用是无副作用的，告诉打包工具如果没用到可以安全删除
/* @__PURE__ */ getBuildVersion();

// 或者标记一个工厂函数调用本身无副作用（返回值可能有副作用）
/* @__PURE__ */ (() => createWidget())();

1
2
3
4
5

// 保守策略：支持绝大多数浏览器
target: ['chrome74', 'firefox68', 'safari12', 'edge79'];

// 激进策略：只支持现代浏览器，代码更小
target: ['chrome100', 'firefox100', 'safari15'];

1
2
3
4
5
6
7

{
  "browserslist": [
    "> 1%",
    "last 2 versions",
    "not dead"
  ]
}

1
2
3
4
5
6

// esbuild 会自动读取 package.json 的 browserslist 配置
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  target: 'es2020', // 或者直接不写 target，让 esbuild 自己读 browserslist
});

1
2
3
4
5
6
7
8

{
  "browserslist": [
    "> 0.5%",       // 市场占有率超过 0.5% 的浏览器
    "last 2 versions", // 每个浏览器的最近两个版本
    "not dead",      // 不是已经停止更新的浏览器（如 IE）
    "not IE 11"      // 明确排除 IE 11
  ]
}

1
2
3
4
5

// 用新语法
const value = input ?? 'default';

// 降级后变成
const value = input !== null && input !== void 0 ? input : 'default';

1
2

// ❌ 危险：把密钥直接写进代码
const API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx';

1
2

// ✅ 安全：通过环境变量注入
const API_KEY = process.env.API_KEY;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// ❌ 危险：把环境变量直接 define 替换进代码 —— 构建产物里会暴露真实密钥！
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  define: {
    // 注意：define 的 key 必须与源码中的表达式完全匹配
    // 源码里写的是 process.env.API_KEY，所以 key 必须是 'process.env.API_KEY'
    // 如果 env var 里有真实密钥，替换后真实密钥会被直接写进 bundle，任何人都能提取！
    'process.env.API_KEY': JSON.stringify(process.env.API_KEY ?? ''),
  },
});

1
2

// ✅ 安全：敏感信息走运行时注入，永远不进入 bundle
const API_KEY = process.env.API_KEY; // 运行时从环境读取，bundle 里只有变量名引用

1
2
3
4
5

{
  "devDependencies": {
    "esbuild": "0.20.0"  // 锁定到精确版本，不用 ^0.20.0
  }
}

1
2
3

# 提交 lock 文件
git add package-lock.json
git commit -m "chore: lock esbuild version to 0.20.0"