本文探讨了在使用esbuild打包javascript并将其引入html时，因`defer`属性导致的`uncaught referenceerror`问题。通过分析`defer`属性的加载机制，阐明了全局变量在dom解析阶段不可用的原因。文章提供了两种解决方案：移除`defer`属性以提前执行脚本，以及推荐使用`addeventlistener`进行事件绑定，避免对全局变量的依赖，从而提升代码健壮性和可维护性。

在现代Web开发中，我们经常使用模块打包工具（如Esbuild）来优化JavaScript代码。然而，在将打包后的脚本集成到HTML页面时，如果不理解HTML脚本加载机制，可能会遇到一些意料之外的问题，例如Uncaught ReferenceError。本文将深入分析一个典型的案例：当一个Esbuild打包的脚本通过defer属性加载，并且在HTML解析过程中尝试访问其定义的全局变量时，为何会失败，并提供相应的解决方案和最佳实践。

理解 defer 属性与脚本执行时机

HTML

为了更好地理解 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:

  
    
  

  
    Hello 

    
  

在此HTML结构中，当浏览器解析页面时：

1. ：浏览器开始异步下载 dist/index.js，但不会立即执行它，而是继续解析HTML。
2. HTML解析器继续向下，遇到 标签。
3. 遇到 Hello：浏览器解析按钮元素及其 onClick 属性。此时，xyz 尚未定义，但 onClick 属性的值是一个字符串，它会在事件触发时才被求值执行，所以此时不会报错。
4. 遇到第二个
5. 当内联脚本尝试执行 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:

  
     
  

  
    Hello
    
  

移除 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:

  
    
    
  

  
    Hello 
    
  

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开发实践：

1. 理解脚本加载机制：明确 defer、async 和无属性脚本在加载和执行时序上的差异。
2. 封装事件逻辑：将事件绑定和DOM操作逻辑封装在JavaScript模块内部。
3. 使用 addEventListener：利用 document.addEventListener('DOMContentLoaded', ...) 或直接在模块中处理事件，避免在HTML中直接使用 onclick 属性。
4. 减少全局变量依赖：尽量避免将模块内容暴露为全局变量，以减少命名冲突和提高代码的模块化程度。

通过采纳这些最佳实践，开发者可以构建出更健壮、更高效且易于维护的Web应用程序。