Fastify中CORS配置无效：浏览器报‘CORS网络失败’问题排查

问题背景 #

用Fastify构建应用，已安装@fastify/cors并配置允许所有源、指定请求方法和头，但通过curl请求能看到正确的CORS响应头，Chrome中使用Swagger-UI测试却报错：

Failed to fetch. Possible Reasons:
CORS Network Failure URL scheme must be "http" or "https" for CORS request.

且Chrome网络控制台未显示Swagger-UI发起的请求，无法直接调试。

可能的原因及排查方向 #

• Swagger-UI的访问协议不兼容
  错误提示明确指向URL scheme问题，大概率是你直接通过本地文件（file://协议）打开Swagger-UI页面。CORS机制不支持file协议，浏览器会直接限制此类跨域请求。解决方式是将Swagger-UI部署到HTTP服务中，比如用Node启动简单静态服务器，或者通过Fastify本身提供Swagger-UI的静态资源访问。

• 路由层面覆盖了全局CORS配置
  检查你的路由是否单独设置了cors选项，如果某条路由显式配置cors: false或自定义CORS规则，会覆盖全局的@fastify/cors配置，导致该路由的CORS规则失效。

• 浏览器缓存干扰
  浏览器可能缓存了旧的CORS响应头，导致新配置无法生效。可以尝试用无痕模式打开浏览器测试，或手动清空浏览器缓存后重试。

• 预检请求（OPTIONS）未被正确处理
  curl发送的是简单GET请求，不会触发预检流程，但浏览器的部分请求（比如携带自定义头的请求）会先发OPTIONS预检请求。检查Fastify路由是否拦截了OPTIONS方法，或有没有中间件错误处理了OPTIONS请求，导致预检失败。可以用curl手动发送OPTIONS请求验证：

  curl -vX OPTIONS 'http://localhost:5000/api/1/2/test' \
    -H 'Access-Control-Request-Method: GET' \
    -H 'Origin: http://localhost:3000'
  

  查看响应是否包含正确的CORS头信息。

• Fastify插件注册顺序错误
  确认server.register(cors)是在注册所有路由之前执行的，如果先注册路由再注册CORS插件，插件规则不会对已注册的路由生效。

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