Helmet、CORS 速查表与上线检查表

1. Helmet Header 速查

不同 Helmet 版本的默认值可能变化，应以项目锁定版本和官方文档为准。

Header	主要作用	常见影响
`Content-Security-Policy`	限制页面可加载或执行的资源	配置过严会阻止脚本、样式、图片、API 连接
`Cross-Origin-Opener-Policy`	隔离顶层窗口的浏览上下文	OAuth、支付弹窗、`window.opener` 可能受影响
`Cross-Origin-Resource-Policy`	声明资源是否可被其他源加载	跨域图片、字体、文件可能被拒绝
`Origin-Agent-Cluster`	请求按 Origin 隔离代理集群	通常无需业务代码特别处理
`Referrer-Policy`	控制 Referer 泄露范围	日志、统计和第三方跳转获得的信息减少
`Strict-Transport-Security`	后续强制浏览器使用 HTTPS	配错会使 HTTP 无法访问；子域策略影响面大
`X-Content-Type-Options: nosniff`	禁止 MIME 嗅探	Content-Type 配错的 JS/CSS 会直接被拒绝
`X-Frame-Options`	限制页面被 iframe 嵌入	合法嵌入和旧系统集成可能失效
`X-DNS-Prefetch-Control`	控制 DNS 预取	可能影响少量性能优化
`X-Download-Options`	降低旧版 IE 直接打开下载的风险	现代浏览器影响较小
`X-Permitted-Cross-Domain-Policies`	限制旧插件跨域策略文件	主要影响遗留技术
移除 `X-Powered-By`	减少直接暴露 Express 信息	不是实质性的漏洞修复

2. CORS Header 速查

Header	谁发送	作用
`Origin`	浏览器请求	表示发起请求的 Origin
`Access-Control-Request-Method`	浏览器预检	声明正式请求准备使用的方法
`Access-Control-Request-Headers`	浏览器预检	声明正式请求准备携带的非简单 Header
`Access-Control-Allow-Origin`	服务器响应	允许哪个 Origin 读取响应
`Access-Control-Allow-Methods`	服务器预检响应	允许哪些方法
`Access-Control-Allow-Headers`	服务器预检响应	允许哪些请求 Header
`Access-Control-Allow-Credentials`	服务器响应	允许带凭据的跨源响应被暴露给前端
`Access-Control-Expose-Headers`	服务器响应	额外允许前端脚本读取哪些响应头
`Access-Control-Max-Age`	服务器预检响应	预检结果可缓存多久
`Vary: Origin`	服务器响应	提醒缓存按 Origin 区分响应

3. 选择速查

场景	CORS	Helmet/安全 Header 重点
同域 `/api` 反代	通常不需要	HTML CSP 在 Nginx；API 可用 Helmet
跨子域 Bearer	精确白名单，不必 credentials	页面 CSP `connect-src` 要允许 API
跨源 Cookie	精确 Origin + credentials	Cookie、CSRF、HTTPS 同时处理
文件下载	视 Origin 决定	暴露 Content-Disposition，正确 MIME
HTML 在线预览	视 Origin 决定	内容清洗、严格 CSP、独立域名/iframe sandbox
公共跨源图片	可能需要	关注 CORP 和页面 `img-src`

4. curl 命令速查

# 响应头 + 响应体
curl -i https://api.example.com/api/health

# HEAD 请求，只看响应头
curl -I https://www.example.com/

# 模拟带 Origin 的正式请求
curl -i https://api.example.com/api/health \
  -H "Origin: https://www.example.com"

# 模拟预检
curl -i -X OPTIONS https://api.example.com/api/orders \
  -H "Origin: https://www.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type, Authorization"

5. 上线前检查表

部署拓扑

[ ] 已确认页面和 API 的真实 Origin。
[ ] 已确认 TLS 在 Nginx、负载均衡还是应用层终止。
[ ] 已明确每类 Header 由 Nginx 还是 Express 管理。
[ ] Nginx 与 Express 不会重复添加 CORS Header。

Helmet

[ ] 首页 HTML 上的 CSP 已经过浏览器真实验证。
[ ] CSP 的 connect-src 包含生产 API、SSE 或 WebSocket 地址。
[ ] 第三方脚本、字体、图片、统计服务均已验证。
[ ] nosniff 下所有资源 Content-Type 正确。
[ ] OAuth、支付弹窗已验证 COOP 影响。
[ ] iframe 场景已验证 frame-ancestors/X-Frame-Options。
[ ] HSTS 仅在 HTTPS 稳定后启用，理解子域影响。

CORS

[ ] 生产 Origin 使用精确白名单。
[ ] OPTIONS 不会被认证提前拒绝。
[ ] Bearer Token 所需 Authorization 已允许。
[ ] 下载所需 Content-Disposition 已暴露。
[ ] Cookie 场景没有使用 *，且前后端都启用 credentials。
[ ] 动态 Origin 响应正确设置 Vary: Origin。
[ ] 预检缓存时间不会妨碍紧急配置变更。

响应覆盖

[ ] 正常响应通过。
[ ] OPTIONS 通过。
[ ] 401/403 带预期 Header。
[ ] 404 带预期 Header。
[ ] 500 带预期 Header。
[ ] 下载、图片和 HTML 预览单独验证。

发布验证

[ ] nginx -t 通过并已 reload。
[ ] PM2 运行的是最新构建文件。
[ ] curl 已分别验证 Nginx 公网地址和 Express 本机地址。
[ ] 真实浏览器 Network、Console、Application 面板已验证。
[ ] 有可执行的回滚方案。

6. 故障回滚原则

先确认是 CSP、CORS、Cookie、Nginx还是应用业务问题。
优先回滚最近的单项策略，而不是永久关闭所有 Helmet。
CSP 可临时切回 Report-Only 收集违规，不建议长期完全关闭。
CORS 不能为了救急永久改成 *，尤其不能在 Cookie 场景这样做。
保存失败请求的 Origin、URL、状态码、响应头和浏览器报错，便于复盘。