如何在Cloudflare Worker中添加googleapis、nodemailer等依赖

基础依赖引入流程 #

所有基于Wrangler CLI创建/部署的Cloudflare Worker项目，依赖安装逻辑和普通Node.js项目一致：

• 进入项目根目录，执行安装命令：

npm install googleapis nodemailer

Wrangler打包时会自动将本地node_modules里的依赖合并进Worker产物，不需要手动做路径映射。

必做兼容配置 #

Cloudflare Worker运行在V8 Isolate环境，不是完整Node.js runtime，直接装完依赖运行会报核心模块缺失错误，必须先开启Node兼容层：
打开项目根目录的wrangler.toml配置文件，添加以下两行配置：

compatibility_date = "2024-06-05"
node_compat = true

配置完成后Wrangler会自动注入Node核心模块的polyfill，覆盖两个依赖90%以上的API调用需求。

两个依赖的特殊适配踩坑 #

直接开启兼容层后大概率还是会遇到运行报错，核心原因和解决方法如下：

• nodemailer适配：nodemailer默认依赖Node原生net/tls模块建立TCP连接，而免费版Worker默认不支持原始TCP出站，且仅允许请求80/443端口的服务，直接用默认SMTP传输连接常规25/465端口的邮件服务会被拦截。两种可行方案：
  1. 弃用默认SMTP传输，改用支持Fetch API的自定义传输，直接对接邮件服务的HTTP API（比如Gmail API、Resend、SendGrid的HTTP接口），不需要额外依赖TCP能力
  2. 开启Worker Beta版的TCP Socket API，在wrangler.toml中添加配置tcp_sockets = true，同时选择支持443端口SMTP over TLS的邮件服务商
• googleapis适配：全量安装的googleapis包包含所有Google服务的适配代码，打包后体积很容易超过免费版Worker 1MB的压缩包大小限制，还会携带很多Worker环境用不到的Node专属逻辑（比如本地文件读取、子进程调用）。最优方案是不要全量引入googleapis，直接用Worker原生的fetch方法调用需要的Google REST API，既能把包体积压到100KB以内，也不会出现兼容问题。

可直接运行的最简示例（Gmail发信场景，无需全量googleapis/nodemailer） #

如果需求是通过Google账号发邮件，完全可以不用装两个大体积依赖，直接写逻辑即可：

export default {
  async fetch(request, env) {
    // 凭证存在Worker环境变量里，不要硬编码
    const accessToken = env.GOOGLE_ACCESS_TOKEN;
    const rawMail = Buffer.from(
      `To: 收件人邮箱\r\n` +
      `From: 你的Gmail邮箱\r\n` +
      `Subject: 测试邮件\r\n\r\n` +
      `这是从Cloudflare Worker发出的测试邮件`
    ).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

    const res = await fetch('https://gmail.googleapis.com/gmail/v1/users/me/messages/send', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ raw: rawMail })
    });

    return new Response(JSON.stringify(await res.json()), { headers: { 'Content-Type': 'application/json' } });
  }
}

额外注意事项 #

• 如果打包时提示找不到fs、child_process这类模块，是依赖里的环境判断逻辑残留，不会影响Worker环境下的实际运行，在wrangler打包配置里将这些模块标记为外部即可
• 所有敏感凭证（Google OAuth密钥、邮箱授权码）都要存在Worker的环境变量/Secrets中，不要硬编码在代码里提交
• 如果必须使用全量nodemailer+googleapis，建议升级到Workers付费版，付费版支持最大10MB的压缩包体积，兼容层稳定性也更好

内容的提问来源于stack exchange，提问作者MrBanjade