自定义 Headers #

什么是 HTTP Headers？ #

HTTP Headers 是 HTTP 请求和响应中的元数据，用于传递额外信息。

text

HTTP 响应：
┌─────────────────────────────────────┐
│ HTTP/1.1 200 OK                     │
│ Content-Type: text/html             │
│ X-Frame-Options: DENY               │
│ Cache-Control: max-age=3600         │
├─────────────────────────────────────┤
│ <html>...</html>                    │
└─────────────────────────────────────┘

配置方式 #

方式一：netlify.toml #

toml

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"

方式二：_headers 文件 #

text

# static/_headers
/*
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block

优先级 #

text

netlify.toml > _headers 文件

安全 Headers #

基本安全配置 #

toml

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

X-Frame-Options #

防止点击劫持攻击：

值	说明
DENY	完全禁止嵌入
SAMEORIGIN	只允许同源嵌入
ALLOW-FROM uri	允许指定源嵌入（已弃用）

toml

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "SAMEORIGIN"

X-XSS-Protection #

启用浏览器 XSS 过滤：

toml

[[headers]]
  for = "/*"
  [headers.values]
    X-XSS-Protection = "1; mode=block"

X-Content-Type-Options #

防止 MIME 类型嗅探：

toml

[[headers]]
  for = "/*"
  [headers.values]
    X-Content-Type-Options = "nosniff"

Referrer-Policy #

控制 Referer 头信息：

值	说明
no-referrer	不发送 Referer
no-referrer-when-downgrade	HTTPS→HTTP 时不发送
origin	只发送源
strict-origin	只发送源，降级时不发送
strict-origin-when-cross-origin	同源发送完整 URL

toml

[[headers]]
  for = "/*"
  [headers.values]
    Referrer-Policy = "strict-origin-when-cross-origin"

Permissions-Policy #

控制浏览器功能权限：

toml

[[headers]]
  for = "/*"
  [headers.values]
    Permissions-Policy = "camera=(), microphone=(), geolocation=()"

常用功能：

camera：摄像头
microphone：麦克风
geolocation：地理位置
payment：支付
usb：USB 设备

Content Security Policy #

基本配置 #

toml

[[headers]]
  for = "/*"
  [headers.values]
    Content-Security-Policy = "default-src 'self'"

完整配置示例 #

toml

[[headers]]
  for = "/*"
  [headers.values]
    Content-Security-Policy = """
      default-src 'self';
      script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net;
      style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
      font-src 'self' https://fonts.gstatic.com;
      img-src 'self' data: https:;
      connect-src 'self' https://api.example.com;
      frame-ancestors 'none';
      base-uri 'self';
      form-action 'self';
    """

CSP 指令说明 #

指令	说明
default-src	默认资源策略
script-src	JavaScript 资源
style-src	CSS 资源
font-src	字体资源
img-src	图片资源
connect-src	AJAX/WebSocket 连接
frame-ancestors	嵌入策略（替代 X-Frame-Options）
base-uri	base 标签策略
form-action	表单提交目标

CSP 值说明 #

值	说明
‘self’	同源
‘none’	禁止
‘unsafe-inline’	允许内联代码
‘unsafe-eval’	允许 eval
data:	data URI
https:	HTTPS 资源
域名	指定域名

缓存策略 #

静态资源长期缓存 #

toml

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

HTML 不缓存 #

toml

[[headers]]
  for = "/*.html"
  [headers.values]
    Cache-Control = "public, max-age=0, must-revalidate"

CSS/JS 中期缓存 #

toml

[[headers]]
  for = "/*.css"
  [headers.values]
    Cache-Control = "public, max-age=86400"

[[headers]]
  for = "/*.js"
  [headers.values]
    Cache-Control = "public, max-age=86400"

图片缓存 #

toml

[[headers]]
  for = "/images/*"
  [headers.values]
    Cache-Control = "public, max-age=2592000"

字体缓存 #

toml

[[headers]]
  for = "/fonts/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000"
    Access-Control-Allow-Origin = "*"

Cache-Control 指令 #

指令	说明
public	可被任何缓存存储
private	只能被浏览器缓存
no-cache	使用前需验证
no-store	不缓存
max-age=秒数	缓存时间
immutable	资源永不变化
must-revalidate	过期后必须验证

CORS 配置 #

允许所有来源 #

toml

[[headers]]
  for = "/api/*"
  [headers.values]
    Access-Control-Allow-Origin = "*"

允许特定来源 #

toml

[[headers]]
  for = "/api/*"
  [headers.values]
    Access-Control-Allow-Origin = "https://example.com"

完整 CORS 配置 #

toml

[[headers]]
  for = "/api/*"
  [headers.values]
    Access-Control-Allow-Origin = "https://example.com"
    Access-Control-Allow-Methods = "GET, POST, PUT, DELETE, OPTIONS"
    Access-Control-Allow-Headers = "Content-Type, Authorization"
    Access-Control-Allow-Credentials = "true"
    Access-Control-Max-Age = "86400"

CORS 指令说明 #

指令	说明
Access-Control-Allow-Origin	允许的来源
Access-Control-Allow-Methods	允许的方法
Access-Control-Allow-Headers	允许的头
Access-Control-Allow-Credentials	允许携带凭证
Access-Control-Max-Age	预检请求缓存时间

HSTS #

启用 HSTS #

toml

[[headers]]
  for = "/*"
  [headers.values]
    Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"

HSTS 指令 #

指令	说明
max-age=秒数	HSTS 有效期
includeSubDomains	包含子域名
preload	允许预加载

_headers 文件语法 #

基本语法 #

text

# 注释
/path
  Header-Name: Header-Value

# 通配符
/assets/*
  Cache-Control: public, max-age=31536000

多个路径 #

text

/*
  X-Frame-Options: DENY

/assets/*
  Cache-Control: public, max-age=31536000

/api/*
  Access-Control-Allow-Origin: *

常见配置场景 #

场景1：静态网站 #

toml

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    X-Content-Type-Options = "nosniff"

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

场景2：API 服务 #

toml

[[headers]]
  for = "/api/*"
  [headers.values]
    Access-Control-Allow-Origin = "https://example.com"
    Access-Control-Allow-Methods = "GET, POST, OPTIONS"
    Access-Control-Allow-Headers = "Content-Type, Authorization"
    Cache-Control = "no-store"

场景3：SPA 应用 #

toml

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

[[headers]]
  for = "/static/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/index.html"
  [headers.values]
    Cache-Control = "public, max-age=0, must-revalidate"

场景4：字体文件 #

toml

[[headers]]
  for = "/*.woff"
  [headers.values]
    Access-Control-Allow-Origin = "*"
    Cache-Control = "public, max-age=31536000"

[[headers]]
  for = "/*.woff2"
  [headers.values]
    Access-Control-Allow-Origin = "*"
    Cache-Control = "public, max-age=31536000"

调试 Headers #

查看响应头 #

bash

curl -I https://your-site.netlify.app

使用浏览器开发者工具 #

text

开发者工具 → Network → 选择请求 → Headers 标签

在线工具 #

最佳实践 #

1. 最小权限原则 #

只开放必要的权限：

toml

# 好的做法
Content-Security-Policy = "default-src 'self'"

# 不好的做法
Content-Security-Policy = "default-src *"

2. 合理设置缓存 #

静态资源：长期缓存
HTML：不缓存或短期缓存
API：根据需求设置

3. 使用 HSTS #

增强 HTTPS 安全性。

4. 定期检查 #

使用安全检测工具定期检查配置。

下一步 #

掌握了自定义 Headers 后，继续学习 CI/CD 集成了解自动化部署流程！