自定义域名与重定向规则

默认的 项目名.pages.dev 域名能直接访问站点，但要上线一个正式产品，必须用自己的域名。Pages 支持绑定自定义域名并自动签发 HTTPS 证书。除了域名，站点上线后还经常要处理旧链接跳转、设置安全响应头，这些靠 Pages 的 _redirects 和 _headers 两个文件完成。这一篇把三件事一次讲清。

自定义域名

Pages 绑定自定义域名的入口在项目设置 → 自定义域名，点击设置自定义域名后输入你的域名，Pages 会自动处理证书和解析。

绑定过程分两种情况，取决于域名是否托管在 Cloudflare DNS 上。

情况	操作
域名在 Cloudflare DNS	Pages 自动添加 CNAME 记录，无需手动配置
域名在其他 DNS 服务商	需要手动到原服务商添加 CNAME 记录指向 Pages

CNAME 记录的目标是 项目名.pages.dev。比如项目名是 my-site，就 CNAME 到 my-site.pages.dev。

绑定后 Pages 会自动申请并续期 HTTPS 证书，不用自己操心证书过期。证书签发通常几分钟内完成，DNS 生效慢的话可能要等更久。

支持的域名类型如下。

域名类型	示例	说明
子域名	blog.example.com	最常见，CNAME 即可
根域名	example.com	也支持，需 DNS 服务商配合
泛域名	*.example.com	匹配所有子域名，进阶用法

一个项目能绑定多个自定义域名，比如同时绑 example.com 和 www.example.com，访问任一地址都能到站点。

DNS 配置细节

域名不在 Cloudflare DNS 上时，手动添加 CNAME 记录要注意几点。

注意点	说明
记录类型	CNAME，不是 A 记录
记录值	项目名.pages.dev
代理状态	在 Cloudflare DNS 上建议开启代理（橙色云朵）
根域名限制	部分 DNS 服务商不支持根域名 CNAME，需用 ALIAS 或转发

根域名 CNAME 一直是个技术限制，DNS 协议原本不允许根域名做 CNAME。Cloudflare DNS 用 CNAME Flattening 解决了这个问题，所以根域名托管在 Cloudflare 上能直接绑。其他服务商要看是否支持类似功能。

绑定完成后状态会显示活跃，之前是初始化中。如果长时间停在初始化，多半是 DNS 记录没配对，回 DNS 服务商核对一下。

_redirects 重定向规则

站点改版、换链接结构时，旧地址要跳到新地址，否则收藏夹和外链全部失效。Pages 用一个 _redirects 文件处理这件事，放在构建输出目录的根下，比如 dist/_redirects 或 public/_redirects。

文件格式每行一条规则，三列用空格分隔。

源路径  目标路径  状态码

常用示例如下。

/old-page  /new-page  301
/blog/2023/*  /archive/:splat  301
/temp  /permanent  302

状态码的含义如下。

状态码	含义	适用场景
301	永久重定向	永久换地址，搜索引擎更新索引
302	临时重定向	临时跳转，保留原地址权重
200	重写（代理）	地址不变但内容来自别处

splat 和 * 配合用，* 匹配路径中的多段，:splat 在目标里引用匹配到的内容。比如 /blog/2023/* 匹配 /blog/2023/hello，重定向到 /archive/hello。

_redirects 还有几个要点要注意。

要点	说明
顺序敏感	同一源路径有多条规则时，最上面那条生效
静态规则在前	不带通配符的规则要排在带通配符的规则前面
默认状态码	不写状态码时默认 302
数量限制	静态规则 2000 条，动态规则 100 条
不作用于函数	被 Pages Functions 处理的请求不走 _redirects

_headers 响应头规则

_headers 文件用来给响应附加自定义 HTTP 头，最常见的是加安全头和缓存策略。文件同样放在输出目录根下。

格式分两部分，第一行是路径，下面缩进跟键值对。

/secure-page
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

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

常用的安全头如下。

响应头	作用
X-Frame-Options	防止页面被 iframe 嵌套
X-Content-Type-Options	禁止浏览器猜测内容类型
Referrer-Policy	控制 Referer 头泄露
Content-Security-Policy	限制资源加载来源
Strict-Transport-Security	强制 HTTPS

/assets/* 这种通配路径常用来给带哈希的静态资源设长缓存，因为文件名带哈希，内容变了文件名也变，不用担心缓存不更新。

_headers 同样有几个要点。

要点	说明
规则叠加	一个请求匹配多条规则时，所有头都生效
优先级	_redirects 先于 _headers 生效，两者冲突时重定向赢
不作用于函数	Pages Functions 的响应头要在函数代码里设置
数量限制	最多 100 条规则，每行不超过 2000 字符

路由优先级

静态文件、_redirects、_headers、Pages Functions 一起存在时，按固定优先级处理请求。搞清楚顺序才不会调不出预期效果。

优先级	来源	说明
1	Pages Functions	_routes.json 包含的路径交给函数，其他规则都不生效
2	_redirects	非函数请求总会检查重定向，即使源路径有静态文件也跳转
3	静态文件	没有重定向命中时才返回静态文件
4	_headers	给静态文件响应附加头

最常踩的坑是写了重定向规则但没生效。一查发现这条路径被 Pages Functions 接管了，或者规则顺序写反。把函数路由排除掉，或者调整规则顺序，就能解决。

把域名、重定向、响应头这三件事配好，一个正式上线的站点基础就齐了。下一篇开始讲 Pages Functions，给静态站点加上动态能力。

上一篇构建配置与预览部署
下一篇 Pages Functions 基础

构建配置与预览部署

Pages Functions 基础