AWS Amplify设置自定义Headers失败如何排查解决

1. 先修正配置语法与位置错误 #

这部分问题占90%以上的不生效场景，对照你用的配置方式逐一核对：

控制台可视化配置（App settings >> Custom headers） #

• 不要把整段YAML配置直接粘贴到输入框，控制台配置是表单形式，只需要逐行填路径匹配规则、头键、头值即可，重复填写customHeaders根节点会直接导致解析失败
• 路径规则遵循最长前缀匹配原则，如果你配置了多条规则，更具体的路径规则优先级高于/*的全局规则，检查是否有其他规则覆盖了你要设置的头

项目内customHttp.yml配置 #

• 文件必须放在项目根目录，和amplify.yml、package.json同层级，不要放到amplify/子目录、构建输出目录（dist//build/）里
• 路径匹配值必须加单引号，否则YAML解析器会识别异常，正确配置示例：

customHeaders:
  - pattern: '/*'
    headers:
      - key: Cross-Origin-Opener-Policy
        value: same-origin
      - key: Cross-Origin-Embedder-Policy
        value: require-corp
      - key: Access-Control-Allow-Origin
        value: '*'
      - key: Access-Control-Allow-Methods
        value: GET

amplify.yml内联配置 #

• customHeaders节点必须放在配置文件根层级，和version、frontend节点平级，绝对不能嵌套在frontend、phases等节点内部
• 正确的配置结构参考：

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
# 注意customHeaders和frontend是同级，不要缩进嵌套
customHeaders:
  - pattern: '/*'
    headers:
      - key: Cross-Origin-Opener-Policy
        value: same-origin
      - key: Cross-Origin-Embedder-Policy
        value: require-corp
      - key: Access-Control-Allow-Origin
        value: '*'
      - key: Access-Control-Allow-Methods
        value: GET

2. 部署流程卡点排查 #

• 所有自定义头配置修改后，必须触发全新的完整部署，增量缓存更新、自动分支预览更新不会重新注入响应头配置
• 查看部署日志：打开对应部署的详情页，在Deploy阶段的日志里搜索custom headers关键词，配置解析错误、文件找不到、语法异常都会在这里打印明确报错
• 绕过缓存验证：不要直接用浏览器验证，先执行curl命令直接请求源站资源，排除浏览器缓存、Service Worker缓存、CDN边缘缓存影响：

curl -I https://你的Amplify应用域名/index.html

在返回结果里查找你配置的几个头字段是否存在，刚部署完建议等待1-2分钟等CDN节点同步完成再测试。

3. 特殊场景冲突解决 #

如果前面的配置都没问题还是不生效，检查是否存在以下覆盖场景：

• 框架自带响应头覆盖：如果用的是Next.js、Nuxt等SSR/SSG框架，框架本身在服务端渲染时返回的响应头会覆盖Amplify静态配置的头，这种情况需要直接在框架配置（比如next.config.js的headers字段）里设置对应头，不要依赖Amplify的静态配置
• 重写规则覆盖：如果配置了路径重写/跳转规则，指向外部域名的重写规则会自动覆盖自定义头，需要调整规则优先级，把需要加自定义头的路径规则优先级调高
• 默认安全头覆盖：如果开启了Amplify自动安全头功能，同名的安全头（包括COOP/COEP）会被平台默认值覆盖，可以在自定义头里显式重新声明对应头的值，或者关闭自动安全头功能
• 边缘函数覆盖：如果配置了Lambda@Edge边缘函数，边缘函数中对响应头的修改优先级最高，检查函数逻辑里有没有覆盖、删除对应头字段的代码
• CORS头过滤：Access-Control-Allow-Origin: * 不能和带身份凭证的请求（携带Cookie、Authorization头）共存，如果你的接口请求带凭证，Amplify会自动过滤掉这个通配符CORS头，需要把值改为具体的请求源地址，不能用通配符

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