本文探讨了在使用esbuild打包javascript并将其引入html时，因`defer`属性导致的`uncaught referenceerror`问题。通过分析`defer`属性的加载机制，阐明了全局变量在dom解析阶段不可用的原因。文章提供了两种解决方案：移除`defer`属性以提前执行脚本，以及推荐使用`addeventlistener`进行事件绑定，避免对全局变量的依赖，从而提升代码健壮性和可维护性。
在现代Web开发中，我们经常使用模块打包工具（如Esbuild）来优化JavaScript代码。然而，在将打包后的脚本集成到HTML页面时，如果不理解HTML脚本加载机制，可能会遇到一些意料之外的问题，例如Uncaught ReferenceError。本文将深入分析一个典型的案例：当一个Esbuild打包的脚本通过defer属性加载，并且在HTML解析过程中尝试访问其定义的全局变量时，为何会失败，并提供相应的解决方案和最佳实践。
理解 defer 属性与脚本执行时机
HTML <script> 标签的 defer 属性是一个布尔属性，它指示浏览器在文档完全解析完毕后（即DOM结构构建完成），但在触发 DOMContentLoaded 事件之前执行脚本。带有 defer 属性的脚本会异步下载，不会阻塞HTML解析，并且它们的执行顺序会严格按照它们在文档中出现的顺序。</script>
为了更好地理解 defer，我们可以将其与没有属性和 async 属性的脚本进行对比：
- 无属性脚本：脚本下载并立即执行。在脚本下载和执行期间，HTML解析会被阻塞。
- async 属性脚本：脚本异步下载并在下载完成后立即执行。它不会阻塞HTML解析，但执行顺序不保证。如果脚本在DOM完成前执行，它可能无法访问完整的DOM。
- defer 属性脚本：脚本异步下载，不阻塞HTML解析。它会在所有HTML内容解析完成后，按它们在文档中出现的顺序执行。这确保了脚本可以访问完整的DOM，但会在 DOMContentLoaded 之前。
Uncaught ReferenceError 的根源：脚本执行时序不匹配
考虑以下场景，我们有一个通过Esbuild打包并暴露全局变量的JavaScript模块，以及一个尝试访问该全局变量的HTML页面：
立即学习“前端免费学习笔记（深入）”；
src/index.js:
export function myFunction() {
alert("Hello!");
}esbuild.config.js:
const esbuild = require('esbuild');
esbuild.build({
entryPoints: ['./src/index.js'],
outfile: './dist/index.js',
bundle: true,
sourcemap: 'external',
minify: true,
globalName: 'xyz', // 将导出内容暴露为全局变量 xyz
loader: {
'.js': 'jsx' // 示例配置，与核心问题无关
}
}).catch(() => process.exit(1));上述配置会将 myFunction 暴露为全局对象 xyz 的一个方法，即 xyz.myFunction()。
index.html:
<html>
<head>
<script src="./dist/index.js" defer></script>
</head>
<body>
<button onClick="xyz.myFunction()">Hello</button> <!-- 此处正常工作 -->
<script>
xyz.myFunction(); /* 错误: Uncaught ReferenceError: xyz is not defined */
</script>
</body>
</html>在此HTML结构中，当浏览器解析页面时：
- <script src="./dist/index.js" defer></script>：浏览器开始异步下载 dist/index.js，但不会立即执行它，而是继续解析HTML。
- HTML解析器继续向下，遇到 标签。
- 遇到 ：浏览器解析按钮元素及其 onClick 属性。此时，xyz 尚未定义，但 onClick 属性的值是一个字符串，它会在事件触发时才被求值执行，所以此时不会报错。
- 遇到第二个 <script> 标签：这是一个内联脚本，它会在HTML解析过程中立即执行。</script>
- 当内联脚本尝试执行 xyz.myFunction() 时，由于带有 defer 属性的 dist/index.js 尚未执行（它在HTML解析完成后才执行），全局变量 xyz 根本不存在于全局作用域中。因此，浏览器会抛出 Uncaught ReferenceError: xyz is not defined 错误。
而 onClick="xyz.myFunction()" 能够正常工作，是因为 onClick 事件处理器是在按钮被点击时才执行的。此时，HTML文档的解析已经完成，并且 defer 脚本也已经执行，xyz 变量已经可用。
解决方案一：调整脚本加载顺序
最直接的解决方案是移除导致脚本延迟执行的 defer 属性，从而确保在内联脚本执行时，全局变量 xyz 已经定义。
修改后的 index.html:
<html>
<head>
<script src="./dist/index.js"></script> <!-- 移除 defer 属性 -->
</head>
<body>
<button onClick="xyz.myFunction()">Hello</button>
<script>
xyz.myFunction(); // 现在可以正常执行
</script>
</body>
</html>移除 defer 属性后，dist/index.js 脚本会在下载完成后立即执行，阻塞后续的HTML解析，从而确保在内联脚本执行时 xyz 变量已经定义。
注意事项：移除 defer 可能会导致脚本阻塞页面渲染。如果 dist/index.js 文件较大，或者需要执行耗时操作，这可能会影响页面的首次渲染时间（FCP），从而降低用户体验。因此，这种方法适用于脚本文件较小且必须在DOM解析期间可用的特定场景。
解决方案二（推荐）：现代事件处理与封装
更推荐的做法是遵循现代JavaScript开发实践，避免过度依赖全局变量和HTML中的 onclick 属性。将事件绑定逻辑封装在JavaScript模块内部，使用 addEventListener，可以提高代码的模块化、可维护性和健壮性。这种方法允许我们继续使用 defer 属性来优化页面加载性能，同时避免 ReferenceError。
修改 src/index.js:
// 定义核心功能
function myFunction() {
alert("Hello from myFunction!");
}
// 在DOM内容加载完成后执行初始化逻辑
document.addEventListener('DOMContentLoaded', () => {
// 获取按钮元素
const button = document.getElementById('myButton');
if (button) {
// 为按钮添加点击事件监听器
button.addEventListener('click', () => {
myFunction(); // 直接调用内部函数
});
}
// 如果需要在页面加载后立即执行某个操作，也可以在此处调用
// myFunction(); // 示例：页面加载后立即显示alert
});
// 如果需要，仍然可以通过命名导出提供函数，但不再强制暴露为全局变量
// export { myFunction };修改 index.html:
<html>
<head>
<!-- 脚本现在可以在 DOMContentLoaded 之后安全执行，因此可以保留 defer -->
<script src="./dist/index.js" defer></script>
</head>
<body>
<button id="myButton">Hello</button> <!-- 为按钮添加一个 ID -->
<!-- 移除 onClick 属性和额外的内联脚本标签 -->
</body>
</html>Esbuild 配置：在这种推荐的方案中，esbuild.config.js 可以保持不变。globalName: 'xyz' 选项不再是外部交互的关键，因为我们不再通过全局 xyz 对象来访问功能。如果不再需要将任何内容暴露为全局变量，甚至可以移除 globalName 配置项。
const esbuild = require('esbuild');
esbuild.build({
entryPoints: ['./src/index.js'],
outfile: './dist/index.js',
bundle: true,
sourcemap: 'external',
minify: true,
// globalName: 'xyz', // 在推荐方案中，如果不再需要全局暴露，可以移除此项
loader: {
'.js': 'jsx'
}
}).catch(() => process.exit(1));这种方法有以下优点：
- 避免全局污染：减少了全局变量的使用，降低了命名冲突的风险。
- 更好的模块化：JavaScript代码更加独立和可维护。
- 性能优化：defer 属性可以继续使用，确保脚本异步加载且不阻塞页面渲染，同时脚本在DOM准备就绪后才执行，确保了对DOM的正确访问。
- 更清晰的关注点分离：HTML负责结构，JavaScript负责行为，两者通过ID或类名进行松散耦合。
总结
理解HTML中脚本加载属性（如 defer 和 async）对脚本执行时机的影响至关重要。当脚本定义了全局变量，而其他脚本或HTML属性需要在DOM解析期间立即访问这些变量时，需谨慎使用 defer。
为了解决 Uncaught ReferenceError 问题，并提升代码质量，我们推荐采用现代JavaScript开发实践：
- 理解脚本加载机制：明确 defer、async 和无属性脚本在加载和执行时序上的差异。
- 封装事件逻辑：将事件绑定和DOM操作逻辑封装在JavaScript模块内部。
- 使用 addEventListener：利用 document.addEventListener('DOMContentLoaded', ...) 或直接在模块中处理事件，避免在HTML中直接使用 onclick 属性。
- 减少全局变量依赖：尽量避免将模块内容暴露为全局变量，以减少命名冲突和提高代码的模块化程度。
通过采纳这些最佳实践，开发者可以构建出更健壮、更高效且易于维护的Web应用程序。
