如何在AWS CloudFront S3源响应中注入API端点供React SPA使用

不推荐URL重写追加查询参数的原始思路，该方案会破坏React Router路由匹配、污染浏览器地址栏、用户手动删除参数后会直接失效，以下三个方案均经过生产验证，按易维护性从高到低排序：

方案1：CloudFront Functions 响应阶段注入全局变量（最推荐，改动最小） #

不需要跳转、不需要修改URL，直接在SPA入口文档返回时注入配置，稳定性最高。

• 配置步骤：
  1. 将CloudFront Function绑定到**查看器响应（Viewer Response）**事件，不要绑定到源站响应事件，避免S3返回压缩内容导致字符串替换失败。核心逻辑仅拦截入口HTML请求，匹配客户标识后注入全局配置脚本，不修改任何JS/CSS/图片等静态资源。
     可用的参考代码如下：

function handler(event) {
  const response = event.response;
  const request = event.request;
  // 仅处理SPA入口文档请求
  if (request.uri === '/' || request.uri === '/index.html') {
    // 替换为你自己的客户映射规则，可根据请求Host、路径前缀等标识匹配
    const customerApiMap = {
      'customer1.myapp.mydomain.com': 'api-customer1.mydomain.com',
      'customer2.myapp.mydomain.com': 'api-customer2.mydomain.com',
      'myapp.mydomain.com': 'default-api.mydomain.com'
    };
    const targetApi = customerApiMap[request.headers.host.value] || 'default-api.mydomain.com';
    // 注入全局变量到head标签最前端
    let htmlContent = response.body;
    const injectScript = `<script>window.__CUSTOMER_API__ = "${targetApi}";</script>`;
    htmlContent = htmlContent.replace('<head>', '<head>' + injectScript);
    // 必须更新content-length，否则会出现内容截断白屏
    response.body = htmlContent;
    response.headers['content-length'] = {
      value: new TextEncoder().encode(htmlContent).length.toString()
    };
  }
  return response;
}

2. React侧读取逻辑非常简单，在封装请求工具的公共文件中直接读取全局变量即可：

// src/utils/request.js
const API_BASE = window.__CUSTOMER_API__ 
  ? `https://${window.__CUSTOMER_API__}` 
  : import.meta.env.VITE_DEFAULT_API; // 本地开发环境兜底地址

// 后续所有接口请求统一使用API_BASE拼接路径即可

• 注意事项：index.html的缓存策略需要设置TTL为0，禁止CloudFront缓存入口文档，避免不同客户访问命中缓存拿到错误配置；带hash后缀的JS/CSS/图片等静态资源可以正常设置1年长缓存，不影响配置正确性。

方案2：查看器请求阶段内部重写查询参数（适配你最初的思路） #

如果一定要用查询参数传递配置，需要修正之前调试时的常见错误，不要做302跳转，使用CloudFront内部重写，用户地址栏不会显示追加的参数：

• 配置步骤：
  1. 将Function绑定到**查看器请求（Viewer Request）**事件，先过滤后缀为.js/.css/.png/.svg等静态资源请求直接放行；对页面请求判断查询参数中是否存在api字段，不存在则根据客户标识追加对应api参数后转发给S3源站。
  2. 修改CloudFront缓存策略，将api查询参数加入缓存键，避免不同客户的请求串缓存。
  3. React侧通过new URLSearchParams(window.location.search).get('api')读取配置，注意要在React Router的路由匹配规则中排除该参数，避免出现路由不匹配的404问题。
• 缺点：用户可以手动修改地址栏的api参数连错后端，稳定性和安全性弱于方案1。

方案3：独立配置文件动态返回（扩展性最强） #

如果后续除了API端点还需要给不同客户配置主题、功能开关、品牌信息等差异化内容，推荐用该方案，配置和前端代码完全解耦，更新配置不需要重新部署前端：

• 配置步骤：
  1. 在S3桶的根目录放一个占位的config.js文件，内容为window.__APP_CONFIG__ = {}，在index.html中固定引入该脚本：<script src="/config.js"></script>。
  2. 给/config.js路径配置单独的缓存策略，将请求Host头加入缓存键，通过CloudFront Functions拦截该路径的请求，根据访问的Host头直接返回对应客户的配置内容，不需要回源S3。
  3. React侧读取逻辑和方案1一致，直接读window.__APP_CONFIG__中的配置字段即可。
• 优势：配置更新完全独立，不需要修改前端构建产物，适合客户数量多、配置变更频繁的场景。

CloudFront Functions调试失败的常见原因 #

• 绑定事件错误：修改响应内容必须绑定查看器响应事件，绑定源站响应事件时S3返回的压缩内容会导致字符串替换失效
• 未更新content-length头：修改响应体后未同步更新长度，会导致浏览器加载内容截断、页面白屏
• 未过滤静态资源：对JS/CSS等静态资源也执行了替换逻辑，导致资源解析失败
• 缓存配置错误：未将客户标识（Host头、api参数）加入缓存键，导致不同客户的请求命中同一个缓存，返回错误配置

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