Netlify CLI 中使用 ESM 模块的常见问题与解决方案

问题背景

在使用 Netlify CLI 开发项目时，开发者可能会遇到一个典型问题：即使已经在 package.json 中明确设置了 "type": "module"，Netlify 函数仍然被构建为 CommonJS (CJS) 格式的 module.exports 语法，导致运行时错误。

问题现象

当开发者按照以下方式配置项目时：

1. 在 package.json 中设置 "type": "module"
2. 在 netlify.toml 中配置 node_bundler = "esbuild"
3. 使用 ES 模块语法 (export/import) 编写函数

构建后的函数文件仍然包含 CommonJS 的 module.exports 语法，而不是预期的 ES 模块格式。这会导致运行时错误，因为 Node.js 会尝试以 ES 模块方式加载这些函数，但实际得到的是 CommonJS 格式的代码。

根本原因

Netlify 函数的构建系统默认会根据文件扩展名来确定模块类型。即使项目配置为 ES 模块，如果函数文件使用 .js 扩展名，构建系统仍可能将其视为 CommonJS 模块处理。

解决方案

方法一：使用正确的文件扩展名

对于 ES 模块函数，应使用以下扩展名之一：

• .mjs - 纯 JavaScript 的 ES 模块
• .mts - TypeScript 的 ES 模块

示例：

// functions/test.mjs
const handler = async (event, context) => {
  return {
    statusCode: 200,
    body: JSON.stringify({ message: "test" })
  }
}

export { handler }

方法二：明确配置构建选项

在 netlify.toml 中，可以更详细地配置构建选项：

[functions]
  directory = "functions"
  node_bundler = "esbuild"
  format = "esm"  # 明确指定输出格式为 ES 模块

方法三：检查 Node.js 版本

确保使用的 Node.js 版本完全支持 ES 模块。建议使用 Node.js 14+ 版本，并在 netlify.toml 中明确指定：

[build.environment]
  NODE_VERSION = "20.11.1"

最佳实践

1. 统一模块系统：在整个项目中保持一致，要么全部使用 ES 模块，要么全部使用 CommonJS。

2. 文件命名规范：

   • 对于 ES 模块：使用 .mjs 或 .mts 扩展名
   • 对于 CommonJS：使用 .js 或 .cjs 扩展名

3. 构建配置：在 netlify.toml 中明确指定构建目标和格式。

4. 测试验证：在本地开发时，使用 netlify dev 命令测试函数是否按预期工作。

总结

Netlify CLI 支持 ES 模块，但需要开发者注意文件扩展名和配置细节。通过使用正确的文件扩展名（如 .mjs）和适当的构建配置，可以确保函数以正确的模块格式构建和运行。这一实践不仅适用于简单的函数，也适用于复杂的、依赖现代 JavaScript 特性的项目。