Referrer-Policy 响应头配置实战指南从策略选型到源码级部署Front-End-Checklist【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本文以 Front-End-Checklist 仓库中 referrer-policy 规则文档 为骨架结合仓库内apps/web/next.config.js的真实安全头配置、packages/mcp/src/tools/review-code.ts的自动化审查逻辑以及 浏览器兼容性基线脚本系统讲解Referrer-Policy响应头的隐私保护原理、八种取值的行为差异、多环境部署方案与验证方法。读完本文你将能独立完成该头部从策略评估、服务器配置到生产验证的完整落地。为什么需要一个 Referrer-Policy 头当用户点击页面中的链接或浏览器加载某个跨站资源时浏览器会向目标服务器发送一个Referer请求头注意拼写HTTP 规范里是Referer而策略名称是Referrer-Policy。这个头携带的是用户从哪个页面跳转过来的信息。而Referrer-Policy响应头的作用就是精确控制Referer头中究竟携带多少来源 URL 信息。在最简形式下一条配置即可覆盖整个站点Referrer-Policy: strict-origin-when-cross-origin不配置的代价敏感参数泄露如果没有设置任何Referrer-Policy浏览器会采用各自默认策略此时一个典型的泄露场景是用户在https://app.example.com/reset-password?tokenxK9mP2qRuser42页面点击了一个外部链接第三方站点收到的请求头可能是Referer: https://app.example.com/reset-password?tokenxK9mP2qRuser42完整的 URL —— 包括密码重置令牌和用户 ID —— 被原样发送给了第三方。攻击者只要诱导用户点击外部链接或者页面里嵌入了任意第三方资源即可截获令牌。这一点在仓库的规则文档中被列为为什么它重要Why It Matters的第一优先级论据见 referrer-policy.mdx 的 whyItMatters 字段Without a Referrer-Policy, a password reset link such as/reset?tokenabc123is included in theRefererheader when the user clicks an external link on that page — leaking the token to third parties.八种策略取值的完整行为对照规则文档用一张对照表按同源请求 / 跨源 HTTPS / HTTPS→HTTP降级三个维度归纳了全部八种取值ValueSame-origin requestsCross-origin HTTPSHTTPS → HTTPno-referrerNothingNothingNothingno-referrer-when-downgradeFull URLFull URLNothingoriginOrigin onlyOrigin onlyOrigin onlyorigin-when-cross-originFull URLOrigin onlyOrigin onlysame-originFull URLNothingNothingstrict-originOrigin onlyOrigin onlyNothingstrict-origin-when-cross-originFull URLOrigin onlyNothingunsafe-urlFull URLFull URLFull URL逐项解读几个关键取值no-referrer任何请求都不发送Referer隐私最强但也放弃了 Referer 带来的分析价值unsafe-url无论同源、跨源、是否降级都发送完整 URL含 path 与 query string是文档明令永远不要使用的值no-referrer-when-downgradeHTTPS→HTTP 时什么都不发这是 Chrome 85 之前、Firefox 87 之前的浏览器默认值strict-origin-when-cross-origin同源发送完整 URL保留站内统计能力跨源 HTTPS 只发 origin如https://app.example.comHTTPS 降级到 HTTP 时完全不发送。三档行为兼顾了功能、隐私与安全。推荐取值strict-origin-when-cross-originstrict-origin-when-cross-origin同时是 Chrome 85 与 Firefox 87 的浏览器默认策略。文档的明确建议是即使它是现代浏览器的默认值也应当显式设置以保证所有浏览器、所有代理层行为一致——不能依赖默认就安全的假设因为不同浏览器的默认值历史不同且未来默认值也可能调整。服务器与框架层的部署配置规则文档提供了四种最常见的部署位置这里逐一给出可直接复制的配置。Nginxadd_header Referrer-Policy strict-origin-when-cross-origin always;always参数确保即使响应是错误页如 4xx/5xx该头也会被附加。ApacheIfModule mod_headers.c Header always set Referrer-Policy strict-origin-when-cross-origin /IfModuleNext.js// next.config.js const nextConfig { async headers() { return [ { source: /(.*), headers: [ { key: Referrer-Policy, value: strict-origin-when-cross-origin, }, ], }, ] }, }Express.js使用 Helmetimport helmet from helmet app.use( helmet.referrerPolicy({ policy: strict-origin-when-cross-origin, }) )仓库源码佐证Front-End-Checklist 自己的生产配置值得指出的是Front-End-Checklist 仓库自身的 apps/web/next.config.js 正是按上述模式落地的。它在securityHeaders数组中一次性集中定义了五个安全响应头const securityHeaders [ { key: Content-Security-Policy, value: buildContentSecurityPolicy() }, { key: Referrer-Policy, value: strict-origin-when-cross-origin }, { key: Permissions-Policy, value: camera(), microphone(), geolocation(), payment(), usb(), interest-cohort(), browsing-topics() }, { key: X-Content-Type-Options, value: nosniff }, { key: X-Frame-Options, value: DENY } ]并挂在headers()钩子中对所有路径生效见 apps/web/next.config.js#L106-L113async headers() { return [ { source: /:path*, headers: securityHeaders } ] }这验证了两个实战要点Referrer-Policy应该与其他安全头一起集中管理而不是零散散布。文档的 Exceptions 章节也强调当多个安全头缺失时应优先补齐能最大程度降低可利用性或浏览器能力的那个头——集中定义便于评估优先级规则文档中的 Next.js 示例source: /(.*)与仓库实际写法source: /:path*在 Next.js 中均合法前者为正则形式后者为路径模式两者都可覆盖全站所有路由。页面级与元素级控制除了 HTTP 响应头Referrer-Policy还有两种更细粒度的设置方式三者优先级从低到高为HTTP 头 meta标签 元素referrerpolicy属性。HTML Meta 标签页面级meta namereferrer contentstrict-origin-when-cross-origin适用于无法修改服务器配置的静态页面或文档站点。注意meta namereferrer必须在head中出现得足够早才能影响后续请求。元素级覆盖链接与资源对单个元素单独收紧或放宽策略适合个别外链需要无来源或个别合作方需要完整来源的场景!-- No referrer for this external link -- a hrefhttps://external.com referrerpolicyno-referrerExternal/a !-- Send full URL only to same origin -- a hrefhttps://partner.com/track referrerpolicyoriginPartner/a !-- No referrer for this image request -- img srchttps://analytics.example.com/pixel.gif referrerpolicyno-referrer第三个示例尤其值得注意第三方埋点像素、广告脚本、字体、统计图片的请求同样会携带 Referer这正是页面加载资源时浏览器发送 Referer的典型场景。仓库中 subresource-integrity 规则 也示范了referrerpolicyno-referrer用于隐藏资源加载来源的用法。即使策略正确也不要把令牌放进查询串规则文档以一个醒目的警告强调了纵深防御原则Even with a good Referrer-Policy, placing sensitive tokens in query strings is a security smell — they may appear in server logs, browser history, and shared links. Prefer tokens in the URL path or HTTP POST bodies, and rotate tokens immediately after use.即即使Referrer-Policy配置得再严格敏感令牌放在 query string 中依然是安全隐患——URL 会出现在服务器访问日志、浏览器历史、代理日志与被分享的链接里。更稳妥的做法是将令牌放在 URL path 中如/reset/token/xK9mP2qR而非?token...或放入 HTTP POST 请求体中使用后立即轮换/作废令牌。异常场景与优先级判断规则文档给出了三条实操判断准则以生产实际响应为准缺失或过弱的头应针对线上生产响应路径评估而不是孤立地只看框架或服务器配置——CDN、反向代理、WAF 可能改写或删除头部遗留集成可以窄范围放行旧系统或内嵌第三方内容可能需要收紧/放宽的例外但例外必须显式记录在案而不是默认保持宽松多安全头缺失时排优先级优先修复可利用性最高或限制浏览器能力最关键的那个头而不是随机修补。浏览器支持与基线规则文档的 Support Notes 给出了该项目浏览器矩阵下的基线兼容最低版本Baseline-compatible minimums: chrome 115, edge 115, firefox 116, safari 16.4, safari_ios 16.4.若项目的目标浏览器超出该范围应补充降级方案或更窄的策略说明。仓库在源码层面对浏览器支持有可验证的实现scripts/lib/rule-support-data.ts 中定义了RULE_SUPPORT_FEATURE_MAP将referrer-policy映射到 MDN 浏览器兼容性数据的特性 IDconst RULE_SUPPORT_FEATURE_MAP: Recordstring, string { ... content-security-policy: http.headers.Content-Security-Policy, referrer-policy: http.headers.Referrer-Policy, hsts: http.headers.Strict-Transport-Security }该脚本会通过browserslist加载项目声明的目标浏览器再逐个比对 BCD 数据isSupportedByStatement逻辑见 scripts/lib/rule-support-data.ts#L56-L68最终输出unsupportedTargets不支持的浏览器列表与baselineMinimums基线最低版本。这意味着Referrer-Policy 是否被项目浏览器矩阵支持在仓库里是一个可自动计算、可被 CI 校验的工程事实而非口头约定。你可以用同样的思路在自己的项目 CI 中把浏览器兼容性检查脚本化。验证与自动化检查自动化检查规则文档建议用 curl、安全头扫描器或等价工具针对具有代表性的线上响应检查实际生效的响应头。例如curl -sI https://your-site.com | grep -i referrer-policy应输出类似referrer-policy: strict-origin-when-cross-origin注意务必对生产路径而非本地开发环境验证因为 CDN 或网关层可能覆盖头部。仓库还把这类检查做成了代码审查工具的一部分在 packages/mcp/src/tools/review-code.ts#L1696-L1709 中内置了 referrer-policy 的启发式检测逻辑// referrer-policy — without a policy, full URLs leak to third parties via Referer header if (slug.includes(referrer-policy)) { if ( hasHeadTag(code) !lowerCode.includes(referrer) !lowerCode.includes(referrerpolicy) ) { return { hasIssue: true, issue: Missing Referrer-Policy — add meta namereferrer contentstrict-origin-when-cross-origin to control referrer leakage } } }这条检查的语义是如果一个 HTML 页面存在head却既没有referrermeta 标签也没有referrerpolicy元素属性字样就判定为缺失 Referrer-Policy并直接给出修复建议。可见显式设置策略、不依赖浏览器默认值这一原则已渗透到仓库的 Agent 自动化审查能力中——这也是该规则文档作为 Agent 可执行技能 存在的意义。手动检查在接近生产环境的流程中手动验证浏览器/用户可见行为确认页面跳转、外链点击、第三方资源加载时的 Referer 实际发送内容符合预期确认不存在更强的冲突安全信号例如混合内容、iframe 嵌入场景中其他头部与 Referrer-Policy 的相互作用。落地路线图小结选值默认采用strict-origin-when-cross-origin对极敏感页面可考虑same-origin或no-referrer绝不使用unsafe-url部署在 Nginx/Apache/Next.js/ExpressHelmet中选择与你的架构匹配的入口将其与 CSP、HSTS、X-Frame-Options 等安全头集中定义细化静态页用meta namereferrer个别外链/埋点用referrerpolicy属性做窄范围覆盖治理杜绝敏感令牌出现在 query string遗留系统例外显式记录验证对生产响应路径执行 curl/扫描器检查并将浏览器兼容性基线纳入 CI 自动校验。该规则在仓库中的完整内容脉络可继续查阅规则文档 → Agent 技能定义 → 规则内容源 → 生产配置实例 → 自动化审查实现。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考