第7章 配置参考

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

// 单个入口
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
});

// 多个入口 —— 每个入口会生成对应的输出文件
await esbuild.build({
  entryPoints: ['src/home.js', 'src/about.js', 'src/contact.js'],
  outdir: 'dist',
});
// 生成：dist/home.js、dist/about.js、dist/contact.js

1
2
3
4
5
6
7

await esbuild.build({
  stdin: {
    contents: `import { greeting } from './utils.js'; console.log(greeting);`,
    resolveDir: './src',  // 指定解析模块时的基准目录
  },
  outfile: 'dist/bundle.js',
});

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

// outfile：指定输出文件路径（单入口时使用）
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/bundle.js',
});

// outdir：指定输出目录（多入口时使用）
await esbuild.build({
  entryPoints: ['src/home.js', 'src/about.js'],
  outdir: 'dist',
});
// 生成：dist/home.js、dist/about.js

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

// 不指定 outbase —— 输出文件结构与源文件目录一致
await esbuild.build({
  entryPoints: ['src/pages/home.js'],
  outdir: 'dist',
});
// 输出：dist/pages/home.js

// 指定 outbase —— 去掉 src 部分
await esbuild.build({
  entryPoints: ['src/pages/home.js'],
  outbase: 'src',  // 关键：告诉 esbuild 基准目录是 src
  outdir: 'dist',
});
// 输出：dist/pages/home.js （而不是 dist/src/pages/home.js）

1
2
3
4
5
6
7
8

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  outExtension: {
    '.js': '.mjs',  // 输出的 .js 变成 .mjs
  },
});
// 输出：dist/index.mjs

1
2
3
4
5
6
7
8

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  format: 'esm',     // 必须用 ESM 格式
  splitting: true,   // 开启代码分割
  platform: 'browser', // 只能在浏览器环境使用
});

1
2

// src/index.js
import('./moduleA.js'); // 这行会触发代码分割

1
2
3
4
5

await esbuild.build({
  absWorkingDir: '/home/user/project',  // 绝对路径
  entryPoints: ['src/index.js'],
  outdir: 'dist',
});

1
2
3
4
5
6

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  // allowOverwrite: false  // 默认值，不允许覆盖
});
// 如果 dist/index.js 已存在，会报错

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  allowOverwrite: true,  // 允许覆盖已存在的文件
});

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

// 默认 true —— 写入文件系统
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  write: true,
});

// write: false —— 不写入文件系统，返回结果对象
const result = await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  write: false,
  metafile: true,  // 需要开启 metafile 才能获取详细信息
});

console.log(result.outputFiles); // 产物文件的 Buffer 数组
// 可以自己决定如何处理这些文件，比如上传到 CDN

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

// ESM 格式
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.mjs',
  format: 'esm',
});

// CJS 格式
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  format: 'cjs',
});

// IIFE 格式
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.global.js',
  format: 'iife',
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// 浏览器应用：ESM + browser
await esbuild.build({
  entryPoints: ['src/app.js'],
  outdir: 'dist',
  platform: 'browser',
  format: 'esm',
});

// Node.js 类库：CJS + node
await esbuild.build({
  entryPoints: ['src/index.ts'],
  outdir: 'dist',
  platform: 'node',
  format: 'cjs',
});

// 通用场景：neutral + esm
await esbuild.build({
  entryPoints: ['src/lib.js'],
  outdir: 'dist',
  platform: 'neutral',
  format: 'esm',
});

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

// 比如 lodash 的 package.json 可能是这样的：
// {
//   "main": "lodash.js",
//   "module": "lodash.esm.js",
//   "exports": { ".": { "import": "lodash.esm.js", "require": "lodash.js" } }
// }

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/bundle.js',
  mainFields: ['module', 'main'],  // 优先用 module 字段，没有再用 main
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/bundle.js',
  conditions: ['import', 'module', 'node'],  // 解析时的条件列表
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 自动模式（React 17+ 推荐）
await esbuild.build({
  entryPoints: ['src/app.jsx'],
  jsx: 'automatic',  // 自动导入 jsx-runtime，不需要手动 import React
});

// transform 模式（需要手动 import React）
await esbuild.build({
  entryPoints: ['src/app.jsx'],
  jsx: 'transform',
});

1
2
3
4
5
6

// 使用 Preact 的 h 和 Fragment
await esbuild.build({
  entryPoints: ['src/app.jsx'],
  jsxFactory: 'h',           // JSX 元素用 h() 创建
  jsxFragment: 'Fragment',    // JSX 片段用 Fragment 创建
});

1
2
3
4
5
6

// 自动从 preact 导入 jsx-runtime
await esbuild.build({
  entryPoints: ['src/app.jsx'],
  jsxImportSource: 'preact',
});
// esbuild 会自动加上：import { jsx as _jsx, jsxs as _jsxs } from 'preact/jsx-runtime'

1
2
3
4
5
6

// 开发模式：保留可读的 JSX 结构
await esbuild.build({
  entryPoints: ['src/app.jsx'],
  jsx: 'automatic',
  jsxDev: true,  // 生成的代码里保留 _jsx/_jsxs 调用，利于调试
});

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

await esbuild.build({
  entryPoints: ['src/app.tsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  // loader 字段可以省略，esbuild 会自动识别以下内置类型：
  // loader: {
  //   '.js': 'js',      // ESM JavaScript
  //   '.ts': 'ts',      // TypeScript
  //   '.jsx': 'jsx',    // JSX
  //   '.tsx': 'tsx',    // TSX（TypeScript + JSX）
  //   '.css': 'css',    // CSS
  //   '.json': 'json',  // JSON
  //   '.txt': 'text',   // 文本文件
  // },
});

1
2
3
4
5
6
7
8

await esbuild.build({
  entryPoints: ['src/app.vue'],
  bundle: true,
  loader: {
    '.vue': 'js',  // 把 .vue 当作 JS 文件处理（实际需要 vue 插件）
  },
  // 但这只是个例子，实际处理 .vue 需要专门的插件
});

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

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'dist',
  loader: {
    '.png': 'file',    // 输出为独立文件，引用路径保持正确
    '.jpg': 'file',
    '.svg': 'text',    // SVG 可以当作文本内联
    '.woff': 'file',   // 字体文件输出为独立文件
    '.woff2': 'file',
    '.wasm': 'binary', // WebAssembly 二进制文件
  },
});

1
2
3
4
5
6

loader: {
  '.png': 'dataurl',  // 转成 base64 data URL 内联
  '.svg': 'base64',   // 转成 base64 字符串（不同于 dataurl，不带 mime type 前缀）
  '.css': 'local-css', // CSS Modules 模式，类名本地化
  '.ext': 'default',  // 使用默认加载逻辑
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  loader: {
    // 变成 dataurl 内联进 JS（base64 编码的 data URL）
    '.png': 'dataurl',  // → <img src="data:image/png;base64,xxxx">

    // 变成文本内联
    '.svg': 'text',

    // 变成二进制
    '.wasm': 'binary',
  },
});

// 注意：esbuild 的 loader 选项只接受扩展名到加载器名称的简单映射，
// 如需处理自定义文件类型（如 .myext），应使用插件的 onLoad 钩子，
// 具体方法参见 7.13 节插件配置。

---

## 7.5 路径解析配置

### 7.5.1 alias（路径别名 / 路径重写）

```javascript
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  alias: {
    '@': 'src',        // @ 指向 src
    '@components': 'src/components',
    '@utils': 'src/utils',
  },
});

1
2
3

// 现在可以这样写 import
import Button from '@/components/Button.js';  // 自动解析到 src/components/Button.js
import { utilA } from '@utils/a.js';       // 自动解析到 src/utils/a.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  external: [
    'fs',           // Node.js 内置模块
    'path',         // Node.js 内置模块
    'lodash',       // npm 包，不打包
    './local/*',    // 匹配本地相对路径
  ],
});

1
2
3

// 标记为 external 后，打包结果会保留 require 调用
const _ = require('lodash');
const fs = require('fs');

1

npm install --save-dev tsconfig-paths

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

import tsconfigPaths from 'tsconfig-paths';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  outdir: 'dist',
  plugins: [
    tsconfigPaths({
      // tsconfig.json 的路径
      baseUrl: './src',
      // paths 配置来自 tsconfig.json
      paths: {
        '@/*': ['./*'],
      },
    }),
  ],
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  resolveExtensions: ['.tsx', '.ts', '.jsx', '.js', '.css', '.json'],
});

1
2
3

// import './utils' 时，esbuild 按顺序查找：
// ./utils.tsx → ./utils.ts → ./utils.jsx → ./utils.js → ./utils.css → ./utils.json
// 找到第一个存在的就停下

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  nodePaths: ['../../shared_modules'],  // 在 node_modules 找不到时，额外搜索这些目录
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  minify: true,
});

1
2
3
4
5
6

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  minify: true,
  mangleProps: '^_',  // 只有以下划线开头的属性名才会被混淆
});

1
2
3
4
5
6

// 原始代码
const obj = { _secret: 123, publicProp: 456 };

// 压缩后
const obj = { _s: 123, publicProp: 456 };
// _secret 被混淆成 _s，但 publicProp 没变

1
2
3
4
5
6

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  minify: true,
  keepNames: true,  // 保留所有函数和类的原始名称
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  drop: ['console', 'debugger'],  // 删除所有 console.* 和 debugger 语句
});

1
2
3
4
5
6
7
8
9

// 原始代码
console.log('debug info');
debugger;  // 断点语句
const secret = 'value';
console.error('error!');

// 压缩后
const secret = 'value';
// 所有 console 和 debugger 都被删掉了

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  pure: ['console.log'],  // 告诉 esbuild：这个 console.log 没有副作用，可以放心删
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  legalComments: 'none',  // 不保留任何法律注释
});

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

// 生成外部 .map 文件，并在主文件末尾加上 sourceMappingURL
sourcemap: true

// 不生成 sourcemap
sourcemap: false

// 把 sourcemap 内容内联到主文件底部
sourcemap: 'inline'

// 只生成外部 .map 文件，不在主文件里引用
sourcemap: 'external'

// 在主文件末尾引用 .map 文件
sourcemap: 'linked'

// 同时生成外部 .map 文件并内联
sourcemap: 'both'

1
2
3
4
5
6

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  sourcemap: true,
  sourceRoot: 'https://my-cdn.com/project/src',  // Source Map 里的源码根路径
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 默认 false：Source Map 里不包含原始源码（减小 .map 文件体积）
// 开发者工具会根据 sources 字段的 URL 去服务器上找源码

// 如果设为 true：Source Map 里内联了原始源码内容
// 即使源码文件不在服务器上，开发者工具也能显示源码
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  sourcemap: true,
  sourcesContent: true,
});

1
2
3
4
5
6
7

// 生产构建：根据场景决定是否开启 sourcemap
await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  minify: true,
  sourcemap: process.env.SENTRY_DSN ? 'linked' : false,  // 接入 Sentry 就开启
});

1
2
3
4
5
6
7

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  define: {
    'process.env.NODE_ENV': '"production"',  // 把代码里的 process.env.NODE_ENV 替换成 "production"
  },
});

1
2
3
4
5
6
7
8

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  define: {
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'),
    'process.env.API_URL': JSON.stringify(process.env.API_URL || 'https://api.example.com'),
  },
});

1
2
3
4
5
6
7
8
9

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  define: {
    'VERSION': '"1.0.0"',         // 替换为字符串
    '__DEBUG__': 'true',           // 替换为布尔值
    'PI_VALUE': String(Math.PI),   // 替换为计算后的常量
  },
});

1
2
3
4
5
6

// 如果代码里写的是 process.env.NODE_ENV
define: {
  'process.env.NODE_ENV': '"production"',  // ✅ 能匹配
  'process.env.NODE_ENV': '"development"', // ❌ 不匹配
  'NODE_ENV': '"production"',               // ❌ 不匹配
}

1
2
3

// globals.js —— 包含要注入的全局变量
export const process = { env: { NODE_ENV: 'production' } };
export const VERSION = '1.0.0';

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  inject: ['./globals.js'],  // 自动把这个文件的内容注入到所有模块的顶部
});

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

// 不转译 ES2020 语法（现代浏览器直呼其名，代码原汁原味）
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  target: 'es2020',
});

// 转译到 ES2015（IE11 用户也要用？那只能委屈你了）
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  target: 'es2015',  // ES6 及以上的语法都会被降级，包括 ?.、??、BigInt……
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  target: ['chrome100', 'firefox100', 'safari15'],
});

1
2
3
4
5
6

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  platform: 'node',
  target: 'node18',  // 生成兼容 Node.js 18 的代码
});

1
2
3
4
5
6

// 直接用字符串作为 target，esbuild 会识别为 browserslist
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  target: '> 0.5%, last 2 versions, not dead',
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.ts'],
  outfile: 'dist/index.js',
  tsconfig: './tsconfig.json',  // 读取 tsconfig.json，继承其配置
});

1
2
3
4
5
6
7
8

await esbuild.build({
  entryPoints: ['src/index.ts'],
  outfile: 'dist/index.js',
  tsconfig: './tsconfig.json',
  // 独立覆盖 tsconfig 中的某些选项
  strict: false,       // 覆盖 tsconfig 里的 strict: true
  target: 'es2015',   // 覆盖 tsconfig 里的 target
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  logLevel: 'debug',  // 显示所有日志，包括 debug 信息
});

1
2
3
4
5

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  logLimit: 5,  // 每个错误最多显示 5 行代码上下文
});

1
2
3
4
5
6
7
8

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  logOverride: {
    'this-is-undefined': 'silent',  // 把这个警告静默掉
    'call-result-unused': 'warning', // 把这个警告降级为警告（而不是错误）
  },
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  banner: {
    js: '/* 我的库 v1.0.0 | MIT License */',  // 在 JS 文件开头插入
  },
  footer: {
    js: '/* Built with esbuild */',  // 在 JS 文件末尾插入
  },
});

1
2
3
4

// 输出结果
/* 我的库 v1.0.0 | MIT License */
...bundle code...
/* Built with esbuild */

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

const result = await esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  metafile: true,  // 开启元数据输出
});

console.log(result.metafile);
// 输出示例：
// {
//   inputs: { 'src/index.js': { ... }, 'src/utils.js': { ... } },
//   outputs: { 'dist/index.js': { ... } }
// }

1
2
3
4

# 构建时生成 metafile
esbuild src/index.js --bundle --outdir=dist --metafile=dist/metafile.json

# 用 bundle-visualizer（或其他可视化工具）分析 dist/metafile.json

1
2
3
4
5
6
7

// 一个最简单的插件
const myPlugin = {
  name: 'my-plugin',
  setup(build) {
    // 在这里配置插件的各种拦截器
  },
};

1
2
3
4
5
6
7
8
9

const timingPlugin = {
  name: 'timing',
  setup(build) {
    build.onStart(() => {
      // 注意：onStart 回调触发时再获取时间，而不是在 setup 时
      console.log(`构建开始！时间：${new Date().toISOString()}`);
    });
  },
};

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

const aliasPlugin = {
  name: 'alias',
  setup(build) {
    build.onResolve({ filter: /^@\// }, (args) => {
      // 拦截所有 @/ 开头的导入
      return {
        path: args.path.replace(/^@\//, 'src/'),
        // 重新指向 src/ 目录
      };
    });
  },
};

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

const textPlugin = {
  name: 'text-plugin',
  setup(build) {
    build.onLoad({ filter: /\.txt$/ }, async (args) => {
      // 读取 .txt 文件内容
      const fs = require('fs');
      const contents = fs.readFileSync(args.path, 'utf8');
      
      // 返回文件内容和加载器类型
      return {
        contents: `export default ${JSON.stringify(contents)}`,
        loader: 'js',
      };
    });
  },
};

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

const metafilePlugin = {
  name: 'metafile',
  setup(build) {
    let metafile;
    
    build.onEnd((result) => {
      if (result.metafile) {
        console.log('构建完成！');
        console.log('输入文件：', Object.keys(result.metafile.inputs));
        console.log('输出文件：', Object.keys(result.metafile.outputs));
      }
    });
  },
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

const logoPlugin = {
  name: 'logo',
  setup(build) {
    // 拦截 .logo 文件的解析
    build.onResolve({ filter: /\.logo$/ }, (args) => {
      return { path: args.path };
    });

    // 处理 .logo 文件内容
    build.onLoad({ filter: /\.logo$/ }, async (args) => {
      // 假设 .logo 文件里就是 SVG 文本
      const fs = require('fs');
      const svg = fs.readFileSync(args.path, 'utf8');
      
      // 把 SVG 变成一个导出的字符串
      return {
        contents: `export default ${JSON.stringify(svg)}`,
        loader: 'js',
      };
    });
  },
};

// 使用这个插件
await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/index.js',
  plugins: [logoPlugin],  // 把插件加到 plugins 数组里
});

1
2
3

build.onLoad({ filter: /\.png$/ }, ...);  // 只处理 .png 文件
build.onLoad({ filter: /src\/components\// }, ...);  // 只处理 src/components/ 下的文件
build.onLoad({ filter: /.*/ }, ...);  // 处理所有文件