如何在 esbuild 中正确暴露 jQuery 供依赖脚本全局使用

esbuild 默认采用模块化作用域，直接 import 的 jQuery 不会自动挂载到全局 window，导致依赖它的传统脚本因找不到 jQuery 或 $ 而报错；需通过插件、全局注入或配置方式显式暴露。

esbuild 默认采用模块化作用域，直接 import 的 jquery 不会自动挂载到全局 window，导致依赖它的传统脚本因找不到 `jquery` 或 `$` 而报错；需通过插件、全局注入或配置方式显式暴露。

在使用 esbuild 构建现代前端项目时，若需兼容依赖全局 jQuery 的遗留脚本（如 otherFile.js），关键在于确保 jQuery 在这些脚本执行前已作为全局变量（window.jQuery 和 window.$）可用。esbuild 的模块机制默认将 import jQuery from './jquery-3.7.1.js' 视为局部绑定，即使你手动赋值 window.jQuery = jQuery，也无法保证 otherFile.js 在执行时该赋值已完成——尤其当 otherFile.js 是非 ES 模块（如 IIFE 或无导出的脚本）且被 esbuild 以 --bundle 方式内联时，其执行顺序可能早于你的赋值语句。

✅ 正确解决方案如下（推荐按优先级排序）：

1. 使用 inject 选项自动注入全局变量（最可靠）

esbuild 提供 inject 功能，可将一个包含全局挂载逻辑的“注入文件”前置到所有模块之前执行：

// inject-jquery.jsimport jQuery from './jquery-3.7.1.js';window.jQuery = window.$ = jQuery;

构建命令：

esbuild src/index.js --bundle --inject:./inject-jquery.js --outfile=dist/bundle.js

此时 inject-jquery.js 会在任何其他模块（包括 otherFile.js）之前执行，确保 window.jQuery 已就绪。

2. 配置 define + banner（适用于纯全局依赖场景）

若 otherFile.js 仅读取 jQuery 而不调用 import，可在打包前用 banner 插入全局声明，并配合 define 替换引用：

esbuild src/index.js   --bundle   --banner:js="import jQuery from './jquery-3.7.1.js'; window.jQuery = window.$ = jQuery;"   --outfile=dist/bundle.js

⚠️ 注意：banner 内容在模块顶部执行，但需确保 jquery-3.7.1.js 是 ESM 格式（官方 CDN 版通常支持）；若为 UMD/legacy 版本，建议先用 --loader:.js=jsx 或转换为 ESM。

3. 避免混合加载：用 <script> 分离加载（兼容性最强）

如答案中所提，对无法修改的第三方脚本，推荐脱离 esbuild 模块系统，改用 HTML <script> 顺序加载：

<script src="./jquery-3.7.1.js"></script><script src="./otherFile.js"></script><script type="module" src="./index.js"></script>

此时 otherFile.js 运行在全局上下文，可直接访问 jQuery；而你的主模块（index.js）仍可通过 import $ from 'jquery' 使用模块化版本，互不干扰。

⚠️ 注意事项

• ❌ 不要依赖 import 后立即 window.jQuery = ... 再 import 依赖文件——ES 模块的执行顺序由依赖图决定，非书写顺序；
• ✅ 确保 jquery-3.7.1.js 是 ESM 兼容版本（推荐从 jQuery 官方 npm 包 安装，其 main 和 exports 已适配）；
• ? 若使用 --splitting 或动态导入，需确保 jQuery 注入逻辑位于所有分块的公共入口中；
• ? 此方案同样适用于 lodash, moment, Bootstrap JS 等依赖全局对象的传统库。

总结：esbuild 的模块隔离是特性而非缺陷，解决“全局依赖可见性”问题的核心思路是——主动、前置、确定性地挂载全局变量，而非依赖模块导入的副作用顺序。选择 inject 方案能兼顾现代构建流程与遗留代码兼容性，是生产环境首选。