经常把项目 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.comDNS 会把这域名指向 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/filexxx浏览器就会绕过你的自定义域名直接访问源站虽然图片能加载但会造成跨域、速度等问题。这类问题有一个判断方法打开开发者工具的 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 收到的请求、转发的目标、返回的状态码全部打出来比瞎猜高效不少。你只需要在本地安装 wranglernpm 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转发到 project1spaces.example.com/app2转发到 project2。关键是代码里先判断url.pathname的前缀再选择不同的源站地址并把路径前缀去掉后转发。这会让你的作品集页面变得非常像一个正经产品聚合入口别人只需记住一个域名就能看到你所有小型 Demo对个人品牌塑造很友好。不过要做成这件事路径重写逻辑必须小心否则子路径之间的静态资源容易互相串我建议先给每个子应用单独测试通过后再合并。6.3 其他替代方案和最终选型建议如果你的项目流量已经大到逼近免费限额或者你需要复杂路由、跨越多平台那不如换个思路直接升级 Hugging Face 的付费套餐使用官方自定义域名功能让平台帮你维护域名校验、证书、重定向省心省力。如果你自己正好已有 VPS用 Nginx 或 Caddy 做反代也完全可以只是一旦源站变动、证书续期、服务重启都要自己盯成本和精力都要评估进去。对我来说Cloudflare Worker 方案拿来做免费的个人项目绑定、个人主页、作品展示是最合适的。它的维护成本很低免费额度又足够哪怕只用来学习 Cloudflare 的边缘网络机制都非常有价值。我自己在跑这套链路时最深的体会是“反向代理”绝不是转发一下请求那么简单。Host 头的改写、重定向 Location 的处理、WebSocket 的取舍每一个点都会在实际场景里跳出来为难你。但只要把链路逻辑想明白遇到问题时有耐心用日志一步步看下去这套方案就能变成你日常工具箱里非常顺手的一件工具。如果你也准备给自己的 Space 挂个自定义域名不妨先按文中的脚本跑一遍再把那些坑提前记在脑子里——你会省下不少调试时间。