HGfast Cloud 灵狐加速 · 一站式全球云网络返回首页

Cloudflare Workers怎么绑定自定义域名?5步完成配置与失败排查

更新于 2026-11-20 · hgfastapp.lol

简答:Cloudflare Workers绑定自定义域名,先确认域名属于已激活的Cloudflare Zone且Worker已部署,再按 Workers & Pages → Worker → Settings → Domains & Routes → Add → Custom Domain 添加主机名。根域名、www和api通常要分别处理;已有CNAME时需先核对业务再调整。

定义:Cloudflare Workers的Custom Domain,是把Cloudflare Zone中的某个根域名或子域名连接到Worker,并由Cloudflare创建相关DNS记录和必要证书。

先看结论:5步绑定自定义域名,根域名和www要分别处理

如果Worker本身就是应用的源站,优先选择Custom Domain;如果Worker只是位于已有网站或服务器之前,用来处理请求后再转发,选择Route。Cloudflare官方把Custom Domain定义为Worker作为源站的入口,把Route用于已有外部应用源站前的匹配规则。查看Cloudflare官方 Routes and domains 说明。

下文使用hgfastapp.lol、api.hgfastapp.lol和www.hgfastapp.lol作示例,请替换成你自己的域名,不要直接照抄。

绑定对象前置条件配置方式验证结果
hgfastapp.lol根域名Zone已激活,Worker已部署Custom Domain根域名HTTPS请求进入目标Worker
www.hgfastapp.lol同一Zone,主机名未被冲突记录占用单独添加Custom Domain,或设置重定向www访问成功或按预期跳转
api.hgfastapp.lolZone已激活,目标主机名无冲突CNAMECustom DomainAPI健康检查路径返回预期状态码
已有网站前的处理层已有且已开启代理的DNS记录;某些配置可使用占位记录,是否适用需核实Route匹配路径先执行Worker,再按代码决定是否访问外部源站
  1. 把域名添加到Cloudflare并确认Zone已激活。
  2. 确认Worker已经部署,并先用现有的workers.dev地址测试。
  3. 确定要绑定的是根域名、www、api还是app。
  4. 在Worker的Domains & Routes中添加Custom Domain,或用Wrangler配置。
  5. 检查DNS、HTTPS、状态码、响应内容和根域名与www是否一致。

绑定前检查:Zone、Worker、权限和DNS记录

添加Custom Domain前,至少需要一个已激活的Cloudflare Zone和一个要调用的Worker。Cloudflare文档还说明,添加、修改或删除Route或Custom Domain,需要对Worker具备Editor权限,并对受影响的Zone具备Workers Routes Write权限。Custom Domain前置条件见官方文档;权限要求见官方文档。

  • 确认Zone归属:域名必须属于当前Cloudflare账户中的Zone;仅确认域名在注册商账户中并不够。
  • 确认Zone状态:在Cloudflare控制台查看该Zone是否已经激活。未激活时,先完成官方要求的域名服务器接入。
  • 确认Worker状态:确认代码已经部署,并用Worker已有的workers.dev地址访问一个确定路径。
  • 规划主机名:网页入口、API和管理后台可分别使用根域名、www、api或app,不要默认一个绑定会覆盖其他主机名。
  • 检查冲突记录:重点查看目标主机名是否已有CNAME。Cloudflare明确说明,已有CNAME记录的主机名不能直接创建Custom Domain。

不要为了绑定成功而删除整个Zone的A、AAAA或CNAME记录。先确认记录是否承载网站、邮件或其他服务,只调整确定属于目标主机名且已经不再使用的记录。

控制台绑定步骤:Workers & Pages里添加Custom Domain

  1. 登录Cloudflare控制台,进入Workers & Pages。
  2. 在Overview中选择已经部署的Worker。
  3. 打开Settings → Domains & Routes。
  4. 选择Add → Custom Domain。
  5. 输入完整主机名,例如api.你的域名,再选择添加Custom Domain。

控制台菜单名称可能随界面调整,以官方文档当前页面和实际界面为准。核心是进入目标Worker的域名或路由设置,选择Custom Domain,而不是把主机名填入普通Route规则。

创建后,Cloudflare会为目标主机名创建DNS记录并签发必要证书。Custom Domain按域名或子域名连接Worker,绑定后该主机名下的路径都会进入同一个Worker,具体返回内容由Worker代码决定。查看官方Custom Domains文档。

如果需要根域名和www都能访问,应分别添加你的域名和www.你的域名,或者明确设置其中一个到另一个的重定向。绑定根域名不会自动覆盖www,反过来也一样。

Wrangler配置:JSON和TOML怎么写

Cloudflare当前文档给出的Custom Domain配置方式,是在配置文件的routes中为每个主机名设置custom_domain为true。新项目可优先使用wrangler.jsonc;Wrangler也支持JSON和TOML配置。示例中的Worker名称、入口文件、兼容日期和域名都要替换为你的实际值。查看官方Wrangler配置说明。

JSONC配置示例

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-11-20",
  "routes": [
    {
      "pattern": "api.example.com",
      "custom_domain": true
    }
  ]
}

TOML配置示例

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-11-20"

[[routes]]
pattern = "api.example.com"
custom_domain = true

在项目目录的Bash、Zsh或PowerShell中执行:

npx wrangler deploy

如果绑定多个主机名,每个主机名分别增加一条routes配置。修改或部署已有Worker通常需要Worker的Editor权限;部署时新增或修改Custom Domain,还需要受影响Zone的Workers Routes Write权限。权限范围见官方说明。

Custom Domain和Route怎么选:看Worker是不是源站

对比项Custom DomainRoute
Worker角色Worker就是该域名或子域名的应用源站Worker位于已有应用源站之前
匹配方式按域名或子域名连接,路径都会进入该Worker按URL模式匹配,可包含路径和通配符
DNS要求Cloudflare会创建相关DNS记录需要已有且已开启代理的DNS记录;某些场景可使用占位记录,是否适用需核实
适合场景API、边缘应用、Worker直接返回网页或数据给现有网站增加鉴权、重写、日志、代理或请求处理
选择口诀没有要长期通信的外部应用源站,优先考虑Custom Domain必须继续访问外部应用源站时,考虑Route

Cloudflare官方建议:当Worker是应用的源站时使用Custom Domain;当应用源站位于Cloudflare之外时使用Route。Route需要Zone处于激活状态、目标主机名有DNS记录且该记录已开启Cloudflare代理。查看官方Routes文档。

不要把api.example.com和api.example.com/*当成相同配置:前者是Custom Domain主机名示例,后者是Route路径模式示例,作用范围不同。

绑定完成后怎么验证:DNS、HTTPS和Worker响应三层检查

  1. 看控制台状态:回到Worker的Domains & Routes区域,确认目标主机名显示为Custom Domain,而不是只存在workers.dev入口。
  2. 查DNS是否有回答:Windows PowerShell执行nslookup api.example.com;macOS或Linux终端执行dig api.example.com。这一步只验证DNS回答,不要把返回地址直接当作Worker源站地址。
  3. 查HTTPS:执行curl -I https://api.example.com/health,将域名和/health替换成你的实际值。该路径应是Worker确实处理且不会修改数据的测试路径。
  4. 对比Worker响应:分别访问自定义域名和workers.dev地址的同一路径,比较HTTP状态码、响应头和响应内容。若代码按Host、路径或环境变量分支,响应不同不一定表示绑定失败。
  5. 分别测试根域名与www:访问https://example.com/和https://www.example.com/,确认两者都已绑定,或其中一个按预期跳转到规范地址。

DNS查询结果主要用于确认名称是否有回答;最终判断应结合控制台绑定状态、HTTPS证书和Worker实际响应。首次测试不要使用带密钥、Cookie或个人数据的真实请求。

绑定失败怎么排查:优先查Zone、CNAME和主机名

先查这三项:Zone是否属于当前账户并已激活、目标主机名是否已有CNAME、根域名和www是否分别配置。它们比反复刷新浏览器更适合作为第一轮排查。

现象优先检查处理方向
提示域名不属于当前账户或ZoneZone归属、Zone状态和权限确认域名已加入当前账户且Zone已激活,再核对Worker Editor和Workers Routes Write权限。
提示已有CNAME或无法创建目标主机名的DNS记录确认旧CNAME是否仍承载业务;完成迁移后再删除或调整,再重新添加Custom Domain。
根域名能访问,www不能访问主机名是否分别绑定分别添加两个Custom Domain,或给未绑定的一方设置重定向。
DNS没有回答Zone状态和记录创建结果回到DNS Records和Worker域名设置检查,先确认记录确实存在,再判断缓存或传播问题。
HTTPS证书或握手异常访问的主机名、证书状态和协议确认访问的是刚绑定的主机名并使用HTTPS;仍异常时结合控制台证书状态和具体错误继续核实。
自定义域名返回内容不对Worker代码、路径和Host判断用同一路径对比workers.dev与自定义域名响应,再检查代码分流逻辑。

如果从Route迁移到Custom Domain,应先确认旧Route和DNS记录的用途,处理目标主机名的冲突记录,再创建Custom Domain,最后清理不再需要的旧Route。不要让两个配置同时争用同一主机名。迁移说明见官方Custom Domains文档。

如果域名绑定已经按上述步骤验证通过,但跨境访问仍有明显延迟或丢包,可再考虑从网络线路角度核对访问路径。

相关阅读:按问题类型继续排查

本文解决的是“Worker如何绑定自定义域名,以及绑定后如何确认请求真正到达Worker”。如果还没有部署Worker,可阅读Cloudflare Workers怎么部署;如果已绑定但想确认DNS记录是否生效,可阅读Cloudflare DNS propagation怎么查;如果域名配置完成后仍然连接失败,再看Cloudflare连接失败排查。

常见问题

Cloudflare Workers绑定自定义域名需要先部署Worker吗?

需要。先准备一个可调用的Worker,并确认目标域名属于已激活的Cloudflare Zone。可以先用workers.dev地址访问确定路径,再添加Custom Domain。

根域名绑定后,www会自动生效吗?

不会。Custom Domain按域名或子域名精确连接,绑定根域名不会自动覆盖www,反过来也一样。需要分别添加绑定,或设置一个主机名到另一个主机名的重定向。

已有CNAME为什么不能添加Custom Domain?

Cloudflare官方说明,目标主机名已有CNAME记录时不能直接创建Custom Domain。先确认旧CNAME是否仍承载业务,完成迁移或调整后,再重新添加绑定。

Custom Domain和Route应该选哪个?

如果Worker就是应用源站,优先选Custom Domain;如果Worker位于已有网站或服务器之前,并且请求还要按代码访问外部应用源站,选Route。Route需要目标主机名存在已开启代理的DNS记录。

绑定后DNS查询显示的地址是不是Worker源站地址?

不能仅凭DNS查询这样判断。DNS查询只能说明名称是否有回答,不能单独证明请求已由目标Worker处理。应结合控制台状态、HTTPS请求、HTTP状态码和响应内容验证。

Wrangler中怎么配置Custom Domain?

在配置文件的routes中填写目标主机名,并设置custom_domain为true。JSON或TOML均可,保存后在项目目录执行npx wrangler deploy;名称、入口文件、兼容日期和域名应替换成实际值。

相关阅读

参考资料

  1. Cloudflare Workers官方文档:Custom Domains
  2. Cloudflare Workers官方文档:Routes and domains
  3. Cloudflare Workers官方文档:Routes
  4. Cloudflare Workers官方文档:Wrangler configuration
  5. Cloudflare Workers官方文档:Workers roles and permissions