esbuild 版本演进指南：从 CHANGELOG 解读 0.28.x 的关键修复、安全加固与新特性

esbuild（An extremely fast bundler for the web）采用按年份拆分的变更日志（changelog）来管理其版本历史。本文以仓库根目录的 CHANGELOG.md 为主体，逐条解读其中记录的 Unreleased 改动、0.28.1 安全修复与 0.28.0 新特性，并结合 internal/ 与 pkg/ 下的源码实现佐证每项变更的落点。读完本文，你可以掌握：如何查阅 esbuild 各版本的发布内容、--allow-overwrite、--log-style=visualstudio 等关键参数的行为与源码依据，以及 0.28.x 版本中值得关注的 minify、lowering 与安全相关修复细节。

变更日志的目录组织：主文件 + 按年归档

当前仓库的版本号为 0.28.1，见 version.txt。esbuild 的变更日志不是单一文件，而是一套"主文件 + 年度归档"的结构：

• CHANGELOG.md：包含最新的 Unreleased 条目以及最近几个完整版本（0.28.1、0.28.0、0.27.7、0.27.5、0.27.4、0.27.3）的详细记录；
• 更早的版本按年份归档，主文件在文末给出了索引：
  • 2025 年（0.25.0 ~ 0.27.2）→ CHANGELOG-2025.md
  • 2024 年（0.19.12 ~ 0.24.2）→ CHANGELOG-2024.md
  • 2023 年（0.16.13 ~ 0.19.11）→ CHANGELOG-2023.md
  • 2022 年（0.14.11 ~ 0.16.12）→ CHANGELOG-2022.md
  • 2021 年（0.8.29 ~ 0.14.10）→ CHANGELOG-2021.md
  • 2020 年（0.3.0 ~ 0.8.28）→ CHANGELOG-2020.md

每条记录采用"特性/修复名称 + 详细描述 + 前后行为对比代码示例"的格式，并明确标注触发问题的 CLI 参数或 API 选项（如 --minify-syntax --target=es6），这使得每条 changelog 本身就可以当作可复现的最小用例来阅读。

Unreleased：即将发布的改动

CHANGELOG.md 顶部的 Unreleased 小节记录了尚未进入正式发布的改动，是了解 esbuild 下一步演进方向最直接的窗口。当前包含以下七项。

防止输出文件覆盖输入文件（恢复 --allow-overwrite 的默认保护）

esbuild 默认不允许输出文件覆盖输入文件，例如 esbuild input.js --outfile=input.js 本应被拒绝。该保护曾在 0.17.0 中意外回归：错误信息虽然打印了，但输入文件仍然被覆写。本次改动恢复了原有行为——遇到构建错误时不写入任何文件，只有在显式提供 --allow-overwrite 时才会允许覆盖。

这一行为的源码落点可以查证。CLI 参数定义在 cmd/esbuild/main.go：

--allow-overwrite         Allow output files to overwrite input files

JavaScript API 对应选项为 allowOverwrite: true（见 pkg/api/api.go 中的 AllowOverwrite bool），Go API 对应 AllowOverwrite: true。核心检查逻辑位于 internal/bundler/bundler.go：当未启用 AllowOverwrite 时，bundling 阶段会把所有可达的输入文件构建为绝对路径集合，再逐一比对输出文件路径；一旦输出路径命中输入路径，就记录一条 Refusing to overwrite input file ... 错误，并根据调用来源（CLI / JS API / Go API）附上不同的开启提示。

修复逻辑赋值运算符 lowering 时的压缩 bug

逻辑赋值运算符（||=、&&=、??=）在 lowering 到较旧 target 时需要复制左操作数。此前当左操作数是一个标识符时，esbuild 没有把这个"复制"计为一次新的使用，导致压缩器误判左操作数只被使用一次，从而错误地把初始化表达式内联到首次使用处，生成语义错误的代码。修复后的行为：

// Original code
function foo() {
  let x
  bar(x ||= {})
}

// Old output (with --minify-syntax --target=es6)
function foo() {
  bar(void 0 || (x = {}));
}

// New output (with --minify-syntax --target=es6)
function foo() {
  let x;
  bar(x || (x = {}));
}

旧输出把 x 内联成了 void 0，而 bar 接收到的参数与声明生命周期都不再正确；新输出保留了 x 的 let 声明与真实引用。

修复 JavaScript API 误用时的潜在死锁

esbuild 的 JavaScript API 将原生可执行文件作为长驻子进程运行，通过 stdin/stdout/stderr 通信；每个 API 请求都是异步的，只要 stdin 未关闭或还有正在处理的请求，进程就保持存活。此前 esbuild 对"未完成请求"的引用计数在一种边缘情况（API 请求返回错误且 API 被误用时）少减了一次计数，导致原生进程可能以一条关于死锁的错误信息退出。本次发布修复了这个引用计数缺陷（修复由社区贡献者提交）。

处理重复的 target 引擎

此前指定重复的 target 引擎（如 --target=chrome1,chrome99）时，esbuild 会取最后一次出现的版本（即 chrome99），这与"取兼容下限"的直觉相悖。现在 esbuild 会在所有重复的 target 引擎之间取最小版本（即 chrome1），确保生成的代码满足最严格的那一端。

强制 .mp3 文件使用 audio/mpeg MIME 类型

esbuild 生成 data URL 时的 MIME 类型检测基于 Go 内置的 MIME sniffing（其标准依据是 WHATWG 的 MIME sniffing 规范）。以 ID3 魔数开头的 MP3 能被正确识别，但存在不以上述序列开头的合法 MP3，会被错误地标记为 application/octet-stream。本次改动后，所有以 .mp3 结尾的文件一律使用 audio/mpeg。

这一点在源码中有直接对应：internal/helpers/mime.go 中维护了一张内置扩展名 → MIME 类型的映射表（注释说明之所以不用 Go 的 mime.TypeByExtension，是因为该函数在 Windows 上有缺陷），其中 Audio 分组正是：

// Audio
".mp3": "audio/mpeg",

新增 TypeScript 类型断言语法警告

TypeScript 6 接受 1 + 2 as number * 3 这一语法，但会把它解析为 (1 + 2) * 3 而非更直观的 1 + (2 * 3)，这种"非直觉优先级"在 TypeScript 7 中已被改为语法错误。esbuild 现在会对这种写法发出 confusing-typescript-cast 警告：

▲ [WARNING] Operator "*" should not directly follow a TypeScript type cast after the "+" operator [confusing-typescript-cast]

    example.ts:1:28:
      1 │ console.log(1 + 2 as number * 3)
        ╵                             ^

  This is a syntax error in newer versions of TypeScript because the type cast has unintuitive
  precedence in this case. Surround the inner expression in parentheses to silence this warning:

    example.ts:1:12:
      1 │ console.log(1 + 2 as number * 3)
        │             ~~~~~~~~~~~~~~~
        ╵             (             )

该警告名在 internal/logger/msg_ids.go 中注册，并与 Visual Studio 诊断 ID 绑定（vsID_JS_ConfusingTypeScriptCast = 10），下文介绍 --log-style=visualstudio 时会再次用到它。

新增 Visual Studio 日志格式（--log-style=visualstudio）

Visual Studio 对自定义构建步骤的日志输出有固定的格式约定（MSBuild 诊断格式），不符合该格式的消息无法在 IDE 的问题面板中正确显示。esbuild 现在新增了 visualstudio 日志风格，可通过 CLI 开启：

$ esbuild example.ts --log-style=visualstudio
/Users/evan/dev/esbuild/example.ts(1,29): warning ES0010: Operator "*" should not directly follow a TypeScript type cast after the "+" operator

注意输出中的 ES0010：每条诊断消息都有编号。实现位于 internal/logger/style_visualstudio.go——当消息带有文件位置时输出 绝对路径(行,列)（列号从源码的 0-based 调整为 1-based），无位置时输出 esbuild: 作为工具名；诊断代码由内部 vsID 常量按 ES%04d 格式生成，vsID 常量表（见 style_visualstudio.go 末尾）是对外承诺的——注释明确要求"只可追加，不可删除或重排"，保证已发布版本的诊断代码稳定。该风格同样暴露给 JS / Go API，可以配合既有的 formatMessages API 使用。CLI 侧的取值校验在 pkg/cli/cli_impl.go，合法值为 default 或 visualstudio。

0.28.1：一个以安全修复为主的发布

0.28.1 记录了两条安全公告（CVE 级别的 GHSA 通告）与两条行为修复。

禁止本地开发服务器 HTTP 请求中的反斜杠（Windows 路径穿越修复）

esbuild 的本地开发服务器（serve 模式）曾被发现在 Windows 上可借助 \ 反斜杠逃出 serve 目录：根因是使用了 Go 的 path.Clean()，它只处理 Unix 风格的 /。修复后，路径中含有 \ 的 HTTP 请求直接不再被允许。这是典型的跨平台路径处理陷阱——path 包与 filepath 包的语义差异在此暴露无遗。

为 Deno API 增加完整性校验

继上一版本为 npm 安装脚本加入完整性校验后，0.28.1 把同样的校验延伸到了 Deno 安装脚本：若下载到的 esbuild 二进制内容与预期不符，Deno API 会直接报错。需要留意的前提是：esbuild 的 Deno API 默认从官方 npm 注册表安装，但允许通过 NPM_CONFIG_REGISTRY 环境变量指向自定义注册表——该环境变量提供的二进制现在也必须与预期内容一致，使用私有镜像的团队需要确认镜像内容的完整性。

避免内联 using / await using 声明

压缩器此前会把 using 与 await using 声明内联到后续使用处，导致资源无法按规范正确释放。bug 的成因是：内联原本只对 let/const 生效（对 var 排除），后来声明类型增多后该判断失效。修复后：

// Original code
{
  using x = new Resource()
  x.activate()
}

// Old output (with --minify)
new Resource().activate();

// New output (with --minify)
{using e=new Resource;e.activate()}

旧输出丢失了资源管理语义，新输出保留了 using 声明块。

其他 0.28.1 修复

• 模块求值出错时的状态保持：某模块在求值时抛错后，此前只有第一次 import() / require() 会抛错，后续调用行为不一致；现在每次调用都会抛出同一个错误。
• new 运算符边缘情况：new (foo()bar)()、new (foo()?.bar)() 这类复杂 new 目标此前打印时缺少必要的括号包裹，会产生语法错误或语义变化；现在会正确加括号。
• 嵌套 var 声明的改名：被提升（hoist）到模块作用域的嵌套 var 在禁用压缩时可能引发命名冲突；现在提升后的声明参与防冲突改名通道。
• TS 专属构造在 ES5 下使用 var：import x = require('y') 在 --target=es5 下此前会生成 const，现在生成 var，与 esbuild 对 ES5 不做 const→var 泛化转换的一贯策略保持一致（嵌套作用域规则决定了 esbuild 不能盲目把 const 转成 var，所以只在这个 TS 专属构造处特殊处理）。

0.28.0：支持 with { type: 'text' } 的破坏性发布

import ... with { type: 'text' }

TC39 的 import text 提案已进入 stage 3，Deno 与 Bun 均已实现。esbuild 自 0.28.0 起支持该语法，其行为与既有的 text loader 完全一致：

import string from './example.txt' with { type: 'text' }
console.log(string)

回退下载路径加入完整性校验（破坏性变更）

通过 npm 安装 esbuild 存在多个边缘情况：安装脚本会先尝试安装平台特定包，失败后用 npm 命令自行下载，再失败则直接向 registry.npmjs.org 发起 HTTP 请求作为最后手段。这条"最后手段"此前没有任何完整性校验。0.28.0 之后，回退路径下载的其二进制哈希会与当前发布版本预置的期望哈希比对，因此所有平台特定二进制包的哈希现在都内嵌在顶层 esbuild npm 包中。正因这一内嵌哈希机制属于行为变更，该项以"破坏性变更"的形式发布。使用自定义/私有 npm 镜像的场景需要关注此约束。

Go 工具链从 1.25.7 升级到 1.26.1

本次升级本身不影响功能，但 Go 1.26 编译器内部变化较多（新的垃圾回收器、更激进的栈分配、链接器可执行文件格式变更，WebAssembly 构建无条件启用符号扩展与不陷浮点转整指令），esbuild 在某些边缘情况下可能与旧版表现略有差异。仓库根目录的 go.version 与 go.mod 记录了构建所用的 Go 版本约束。

如何结合源码阅读这份 CHANGELOG

esbuild 的 changelog 条目几乎都是"问题场景 + 参数复现方式 + 新旧输出对比"的格式，配合仓库源码可以快速验证：

1. 行为参数：--allow-overwrite 的定义在 cmd/esbuild/main.go，解析逻辑在 pkg/cli/cli_impl.go，API 选项在 pkg/api/api.go，执行逻辑在 internal/bundler/bundler.go；
2. 诊断与日志：每条警告/错误在 internal/logger/msg_ids.go 注册名称与诊断 ID，visualstudio 风格的输出格式化在 internal/logger/style_visualstudio.go，CLI 取值校验在 pkg/cli/cli_impl.go；
3. 内容类型处理：内置 MIME 映射表在 internal/helpers/mime.go；
4. 回归验证：esbuild 的 bundler 级行为有大量快照测试，位于 internal/bundler_tests/（如 bundler_lower_test.go、snapshots_lower.txt 等），lowering 与压缩类修复通常都能在其中找到对应的输入/输出对。

从源码结构看，CHANGELOG 中"修复 lowering/压缩/打印 bug"这类条目，大多对应 internal/js_parser（lowering）、internal/renamer 与 internal/linker（压缩相关）、internal/js_printer（打印加括号）等模块的改动。对需要升级 esbuild 版本的项目，建议按本文路径：先读 CHANGELOG.md 中目标版本区间的条目，确认是否触及自己使用的参数（--target、--minify、--log-style、allowOverwrite 等）与语言特性（using 声明、逻辑赋值、with 属性、TS 参数属性），再对照上述源码位置评估影响。