Astro部署Cloudflare Pages间歇性出现ReferenceError: reset未定义问题排查

问题概述 #

使用Astro构建的混合站点部署至Cloudflare Pages后，两个对接SendGrid API的API端点（新闻通讯订阅、联系表单提交）出现间歇性失败，Cloudflare Functions实时日志抛出以下错误：

"exceptions": [
  {
    "stack": "    at chunks/server_ChVHT3Lq.mjs:27:2\n    at setGetEnv (chunks/astro/env-setup_E0oxRp6C.mjs:163:3)\n    at Object.fetch (chunks/_@astrojs-ssr-adapter_ho7DYPta.mjs:1077:5)",
    "name": "ReferenceError",
    "message": "reset is not defined",
    "timestamp": 1728762389258
  }
],

当前通过astro:env API读取SendGrid API密钥环境变量，无法定位是Astro配置还是Cloudflare环境问题。

可能原因 #

1. Astro的astro:env API在Cloudflare Pages SSR运行时存在兼容性缺陷，内部用于环境变量重置的reset函数未被正确注入
2. 环境变量异步加载的竞态条件：端点请求触发时，环境变量初始化流程未完成，导致未定义错误

解决方案 #

1. 替换astro:env为Cloudflare原生环境变量读取方式 #

直接使用process.env读取环境变量，跳过Astro的封装层，避免内部逻辑冲突：

// src/pages/api/subscribe.js 示例
export async function POST({ request }) {
  const sendGridKey = process.env.SENDGRID_API_KEY;
  if (!sendGridKey) {
    return new Response(JSON.stringify({ error: "SendGrid密钥未配置" }), { status: 500 });
  }
  // 后续SendGrid API调用逻辑
}

注意：需在Cloudflare Pages控制台的「环境变量」中正确配置SENDGRID_API_KEY，并勾选「Available in Runtime」选项。

2. 升级Astro Cloudflare适配器 #

旧版本@astrojs/cloudflare适配器可能存在与Cloudflare Functions运行时的兼容性bug，执行以下命令升级：

npm update @astrojs/cloudflare

3. 禁用Astro环境变量缓存 #

在astro.config.mjs中添加配置，强制环境变量每次请求重新读取，避免缓存导致的初始化异常：

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'hybrid',
  adapter: cloudflare({
    mode: 'directory',
  }),
  env: {
    cache: false,
  },
});

4. 验证Cloudflare Pages部署配置 #

• 确认构建命令为npm run build，构建输出目录为dist
• 在项目「Settings」>「Functions」>「Runtime」中，将运行时版本设置为Node.js 18或更高版本

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