经常把项目 Demo 丢到 Hugging Face Spaces 上的人，应该都有过这种感受：功能做得挺完整，但xxxx.hf.space这个默认链接发出去，总有种“临时演示”的感觉。尤其到了写简历、给客户验收、或者挂到个人主页的时候，一个自己的域名比什么都重要。我前段时间就把一个图像工具部署到了 Space 上，功能跑通了，但绑定自定义域名这一步卡住了——官方确实提供了设置入口，可免费用户根本保存不了，一操作就引导你去订阅付费套餐。
后来我换了个思路，用 Cloudflare Workers 做反向代理，把自定义域名挂在 Worker 上，再把请求透明转发到原来的hf.space地址。整套链路搭下来零成本，Cloudflare 免费额度对个人项目完全够用。这篇文章会把原理、脚本、配置步骤、以及我实际操作中踩过的所有坑都写清楚，如果你想给自己的 Space 也绑一个像样的域名，可以直接照着做。
1. 为什么放着官方功能不用，反而要自己搭免费方案
1.1 默认域名在真实场景里的三个问题
先说最直接的感受。默认的hf.space域名不是不能用，但在公开场合确实有几个麻烦：一是链接又长又难记，别人看到第一眼根本不知道你这是干嘛的；二是域名带着第三方平台的品牌，用在作品集或者客户演示里显得不够正式；三是你没法控制页面的最终地址，后续如果想换平台或者迁移，链接全部失效，又要重新分发。
这些问题在小规模自嗨时无所谓，但只要你的应用有一点对外属性——比如投简历、发社交媒体、给合作方体验——自定义域名就会变成一个刚需。我最初只是想省事，真正推动我去解决的，是某次把链接发给合作方后对方问了一句“为什么不是你们自己的域名”，场面确实尴尬。
1.2 官方绑定功能的收费门槛
Hugging Face 官方其实很早就支持了自定义域名。在 Space 的 Settings 里能找到 "Custom domain" 相关选项，填写域名、校验、配置解析，一套流程都有。但问题在于，这是付费订阅用户的功能，免费用户最多只能看到入口，真正保存时会被告知需要升级套餐。
到我写这篇文章为止，想要用官方方式绑定自定义域名，基本等于每个月固定花一笔订阅费。这对于很多个人开发者来说，其实是不划算的——毕竟很多 Space 仅仅是展示用、流量不大、也没有收入，为了一两个域名每个月付费，显然不是最优解。
1.3 三条免费路线，以及我为什么选了 Cloudflare Worker
既然官方收费，那社区里自然就有人绕路。常见的有三种：
- 用 Cloudflare Workers 写一个反向代理脚本，把自定义域名的流量转到
hf.space源站。这是最稳妥的方案，下面会详细展开。 - 用 Vercel / Netlify 的 Rewrites 或 Functions 做相同的事。这条路也能走通，但配置复杂度略高，而且这两个平台的函数路由不如 Workers 灵活。
- 自己买一台 VPS 部署 Nginx 反代。最推荐有服务器基础的人，但你不是为了绑个域名还得维护一台机器，纯属增加负担。
我最后选了 Cloudflare Workers，理由很直接：免费额度够用、脚本逻辑极简单、绑定自定义域名之后证书自动签发、出问题还能用日志排查。整个方案里没有任何一个环节需要付费账号。
2. 动手前必须搞懂的三个技术环节
2.1 浏览器访问你域名时，流量到底去了哪
先画一下整个链路：用户访问spaces.example.com，DNS 会把这域名指向 Cloudflare 的节点；Cloudflare 接收到请求后，根据你配置的 Worker 路由，把请求交给对应的 Worker 脚本；脚本收到后，自己作为客户端去请求username-project.hf.space，拿到响应，再原样返回给浏览器。
这里最关键的一步是把自定义域名“接入”Cloudflare。一般人以为只要加一条 CNAME 记录就够了，实际上若要让自定义域名跑在 Worker 上，比较省事的做法就是把域名托管到 Cloudflare，也就是把域名的 NS 记录指过去。Cloudflare 会自动为你的域名生成一条 DNS 记录并接通边缘网络，之后 Worker 才能捕获到访问流量。
这里我要提醒一句：如果你的域名当前在用邮箱服务、访问量较大或者有复杂的解析记录，改 NS 之前最好把全部 DNS 记录导出备份，同时在 Cloudflare 里先完整照搬一遍，等确认服务正常再切换，不然容易把邮箱、子域名弄断。
2.2 Worker 反向代理到底做了什么
反向代理的本质，本质就是“替源站接收请求，再转发给源站”。你在自己的网站服务器前面加一层代理，对外隐藏源站地址，这就是 Reverse Proxy 最常见的用法。
在 Cloudflare Worker 里，这件事做起来比传统服务器更简单，因为脚本运行在边缘网络节点上，离用户更近，而且请求进到 Worker 时，你可以任意修改 URL、Header、Body，把请求“捏成”源站想要的样子。反过来，从源站回来的响应也能改：改响应头、改返回内容、加缓存策略都可以。
这个特性非常关键，因为hf.space源站对请求是有要求的，你直接用自定义域名去访问，它很可能不知道你是谁。Worker 的价值就是把“自定义域名的请求”改写成“源站认识的请求”。
2.3 为什么要把 Host 头改掉
这是新手最容易忽略、却又决定了能否访问成功的一点。HTTP 请求里有一个Host头，表示浏览器原本想访问的域名。你自定义域名是spaces.example.com，但这个域名对 Hugging Face 服务器来说是没有注册过的，直接转发过去，它大概率会返回 404 或者要求登录。
所以 Worker 脚本中要把转发请求的Host头替换成源站域名，比如username-project.hf.space。这样一来，HF 服务器觉得自己是在服务一个合法请求，路径、Cookie、登录态也能正确匹配。
还有另一个方向：如果源站响应里带了Location重定向头，指向的是hf.space，那浏览器又会直接跳到源站域名，等于白白绑定了。所以我一般会用代码把响应头里的Location也替换成自定义域名，这样重定向逻辑也保持在你的域名内。
3. 实操过程：把 Cloudflare Worker 变成 Spaces 的搬运工
3.1 前期准备清单
不要急着写脚本，先确认下面几样东西：
- 一个你自己有管理权的域名，建议先用一个二级域名，比如
spaces.example.com，不要一上来就动根域名，风险更小。 - 一个 Cloudflare 账号，免费版即可。
- 一个已经在公网正常运行的 Hugging Face Space，副本地址形如
https://username-project.hf.space。 - 本地装了
curl和浏览器开发者工具，用来验证效果。
如果你的域名还没有托管到 Cloudflare，先在 Cloudflare 官网添加站点，按提示修改 NS 记录，等待状态变成 Active。这一步通常几分钟到几小时不等，尽量在动手前完成，不然后面 Worker 自定义域是加不上的。
3.2 Worker 核心脚本：可以直接复制改改
登录 Cloudflare 控制台，进入 Workers & Pages，新建一个 Worker，把下面这段脚本贴进去：
const UPSTREAM = "https://username-project.hf.space"; export default { async fetch(request, env, ctx) { // 解析用户访问的 URL，保留路径和查询参数 const url = new URL(request.url); const targetUrl = UPSTREAM + url.pathname + url.search; // 复制请求头，并替换 Host 为源站域名 const headers = new Headers(request.headers); headers.set("Host", new URL(UPSTREAM).host); // 构造转发请求，GET/HEAD 不携带 Body，其余方法透传 Body const init = { method: request.method, headers: headers, body: ["GET", "HEAD"].includes(request.method) ? undefined : request.body, redirect: "manual", }; const response = await fetch(targetUrl, init); const newResponse = new Response(response.body, response); // 如果源站返回 Location 重定向，把指向源站的部分替换成当前域名 const location = newResponse.headers.get("Location"); if (location && location.startsWith(UPSTREAM)) { newResponse.headers.set( "Location", location.replace(UPSTREAM, url.origin) ); } return newResponse; }, };这段代码有个地方要特别说明：redirect: "manual"是为了不让 fetch 自动跟随重定向，因为一旦自动跟随，Location 的处理就会失效。如果你遇到重定向问题，优先检查是不是这里。
把代码里的UPSTREAM换成你自己的 Space 地址，然后 Deploy。
3.3 给 Worker 绑定自定义域名
Deploy 完成后，进入 Worker 的 Settings → Domains & Routes，选择 Add Custom Domain，输入spaces.example.com（你自己的域名），确认添加。
这里有个很大的好处：Cloudflare 会自动在 DNS 区域添加对应记录，并且自动签发一张用于边缘 HTTPS 的证书，整个过程一般在 1 到 5 分钟内完成。你不需要自己管证书，也不需要手动改 DNS 的 A 记录或 CNAME 记录，至少我在免费套餐里是可以这样操作的。
添加域名之后，可以顺便把访问限制也配置一下，比如在 Cloudflare 的 WAF 规则里加入“仅允许指定国家”或者“加访问密码”，不过这些属于可选项，初学阶段可以等基本链路通了再加。
3.4 验证链路是否真的通了
不要急着打开浏览器，先用 curl 确认关键信息：
curl -I https://spaces.example.com正常情况你能看到响应头里有server: cloudflare相关的标记，并且 HTTP 状态码是 200。如果状态码不对，我建议按顺序排查：先直接访问源站https://username-project.hf.space看是不是好的，再看 Worker 是否部署了最新代码，最后看自定义域名是否已经变成 Active 状态。
确认 HTTP 通了之后，再用浏览器无痕窗口访问一下，重点看页面里的 CSS、JS、图片是否正常加载。这一步能暴露出很多隐蔽问题，具体我放到第 5 节讲。
4. 绑定只是开始：路径、实时连接、静态资源这些体验细节
4.1 保留查询参数和路由前缀
HF Space 上跑的 Gradio / Streamlit 应用往往不只一个页面，你会发现请求路径里有/queue/join、/api/predict、/file=之类的内容。Worker 脚本中我用的是url.pathname + url.search，这就保证了所有路径和查询参数都能原样转发，不会因为这个节点设置不同而导致 404。
如果你想把自定义域名的某个子路径映射到 Space 的特定路径，比如希望spaces.example.com/demo对应到 Space 的/gradio/，那就需要在代码里改一下路径拼接逻辑。这种情况不多，但碰到时要知道原理：先把进入的路径按需要裁剪，再拼到UPSTREAM后面。
4.2 WebSocket 和 EventSource 这类实时连接怎么办
Gradio 应用在做推理时经常用到 Server-Sent Events 或 WebSocket 来流式输出结果。我用第一种简单脚本测试时发现，页面静态内容能加载，但推理过程一旦开始，前端就一直卡在等待状态，控制台也报 WebSocket 连接失败。
原因很简单：WebSocket 握手需要保留Connection: Upgrade和Upgrade: websocket这两个关键头，而上面的脚本只能透传普通 HTTP Header，对 101 状态码和双向流支持不够完整。你需要为此单独处理Upgrade请求。
我的建议是：如果应用只是展示性质、没有流式输出需求，普通 HTTP 反向代理足够了；如果确实需要 WebSocket，要么自己查一下 Cloudflare Workers 的 WebSocket 代理实现（确实可以写，代码会复杂不少），要么继续用官方域名跑那些实时性强的页面，再加一个二级域名做入口，把实时请求分流过去。不要试图让所有东西都塞进同一个简单脚本里。
4.3 静态资源加载和 CORS 头
页面打开后如果样式错乱，八成是静态资源没加载出来。最典型的情况是应用内部通过绝对路径或绝对地址引用了源站的静态资源，比如图片地址直接写https://username-project.hf.space/file=xxx，浏览器就会绕过你的自定义域名直接访问源站，虽然图片能加载，但会造成跨域、速度等问题。
这类问题有一个判断方法：打开开发者工具的 Network 面板，看失败请求的完整 URL 是落在你的域名还是hf.space域名。如果是hf.space，说明应用写死了资源地址，最稳妥的方法是改应用代码统一使用相对路径，否则只能在 Worker 里对 HTML 做字符串替换，把Upstream域名替换成自定义域名，但这样容易误伤 payload 里的 URL，我一般不建议。
另外，如果需要从其他前端页面里调用 Space 的 API，那还得在 Worker 响应里补充 CORS 头：
newResponse.headers.set("Access-Control-Allow-Origin", "*");这样才能让浏览器允许你的自定义域名资源被跨域读取。
5. 我实际踩过的坑，以及一套可复现的排查链路
5.1 状态码背后真正的原因
先看两个容易误判的场景。只遇到 502 Bad Gateway 时，第一反应是“Worker 坏了”，但真正原因往往是源站无法访问。HF 免费 Space 会定期休眠，如果你有一段时间没访问，实例还没被唤醒，Worker 去请求源站就会超时或失败。解决办法是先去浏览器直连源站，看是否能正常打开临时确认实例状态。
404 更常见。如果你已经确认源站能访问，那 404 大概率是 Host 头没改到位，或者路径有偏差。我说过，HF 源站是认 Host 的，你发过去的 Host 还是自定义域名，它当然找不到路由。所以脚本里headers.set("Host", ...)这一行的位置特别重要，确保它在 fetch 之前执行。
403 则大概率来自安全限制。比如 HF 源站的一些保护规则、或者 Cloudflare 边缘触发拦截，可以和直接访问源站对比来判断问题到底出在链路中的哪一环。
5.2 从 curl 到 wrangler tail 的完整排查流程
我每次配置 Worker 遇到问题，都会按照下面这个顺序排查，基本不会跑偏：
- 先 curl 源站，排除 Space 本身问题。
- 再 curl 自定义域名，观察路径和状态码。
- 进入 Cloudflare Worker 控制台的日志面板，或者本地装
wrangler后执行wrangler tail worker名称，实时查看每次请求的详细日志。 - 如果页面请求里有响应但资源失败，浏览器 Network 面板看一眼具体是哪个资源、哪个请求头出了问题。
wrangler tail是我最推荐的一步，它能实时把 Worker 收到的请求、转发的目标、返回的状态码全部打出来，比瞎猜高效不少。你只需要在本地安装 wrangler：
npm install -g wrangler wrangler tail my-worker然后去访问一次自定义域名，终端会立刻显示这次请求对应的日志信息。
5.3 冷启动超时和 SSL 模式的隐藏坑
免费 Space 的冷启动确实会导致超时。我实测下来，如果源站处于休眠状态，Worker 转发请求可能等待较长时间直接超时。后续我加了一个定期保活请求：用一个免费定时任务每隔 10 分钟访问一次源站，把它维持在唤醒状态，这样自定义域名打开时就快了很多。记住，这种做法会消耗 HF 免费版的计算额度，注意控制频率，不要做得太激进。
另一个容易忽视的是 Cloudflare 的 SSL/TLS 加密模式。如果你在 Cloudflare 里给另一个域名启用过某些特殊策略，可能会影响 Worker 的子域。一般情况下保持默认的“完全（严格）”模式是可以的，前提是你的源站证书有效。如果你遇到证书循环或证书错误，可以尝试把 SSL/TLS 模式调整为“完全”或“灵活”，但“灵活”会降低源站通信安全性，仅作为排错手段，不建议长期使用。
6. 免费方案的边界，以及还能怎么玩出更多花样
6.1 免费额度到底够扛多大流量
Cloudflare Workers 免费版给的额度大概是每天十万次请求，对个人项目来说非常宽裕，我在跑的几个小工具都没有触发过限制。不过要注意两个细节：一是免费版的单次请求 CPU 时间有限制，但反向代理主要是网络等待，CPU 消耗很低，基本不受影响；二是如果你在 Worker 里做了很多繁琐的字符串处理、正则匹配、加密运算，CPU 时间就会成为瓶颈，所以能少处理就少处理。
如果未来访问量大起来，你可以随时升级 Worker 的付费档，也可以改用 Cloudflare 的缓存功能，把不经常变的静态资源直接缓存在边缘节点，减少请求打到源站的次数。
6.2 用一个域名聚合多个 Spaces 应用
绑定一个自定义域名跑通之后，你可以把一个 Worker 扩展成“路由器”，根据不同的子路径转发到不同的 Space。例如spaces.example.com/app1转发到 project1，spaces.example.com/app2转发到 project2。关键是代码里先判断url.pathname的前缀，再选择不同的源站地址，并把路径前缀去掉后转发。
这会让你的作品集页面变得非常像一个正经产品聚合入口，别人只需记住一个域名，就能看到你所有小型 Demo，对个人品牌塑造很友好。不过要做成这件事，路径重写逻辑必须小心，否则子路径之间的静态资源容易互相串，我建议先给每个子应用单独测试通过后再合并。
6.3 其他替代方案和最终选型建议
如果你的项目流量已经大到逼近免费限额，或者你需要复杂路由、跨越多平台，那不如换个思路：直接升级 Hugging Face 的付费套餐使用官方自定义域名功能，让平台帮你维护域名校验、证书、重定向，省心省力。如果你自己正好已有 VPS，用 Nginx 或 Caddy 做反代也完全可以，只是一旦源站变动、证书续期、服务重启都要自己盯，成本和精力都要评估进去。
对我来说，Cloudflare Worker 方案拿来做免费的个人项目绑定、个人主页、作品展示是最合适的。它的维护成本很低，免费额度又足够，哪怕只用来学习 Cloudflare 的边缘网络机制，都非常有价值。
我自己在跑这套链路时，最深的体会是“反向代理”绝不是转发一下请求那么简单。Host 头的改写、重定向 Location 的处理、WebSocket 的取舍，每一个点都会在实际场景里跳出来为难你。但只要把链路逻辑想明白，遇到问题时有耐心用日志一步步看下去，这套方案就能变成你日常工具箱里非常顺手的一件工具。如果你也准备给自己的 Space 挂个自定义域名，不妨先按文中的脚本跑一遍，再把那些坑提前记在脑子里——你会省下不少调试时间。
