用 Workers 搭第一个免费网站：从空目录到能访问的域名

2026-11-10 #Cloudflare

这篇是整套教程的"跑通"环节。跟着做完，你会得到一个真实可访问的站点：不需要服务器、不需要容器、不需要备案（海外节点）。

1. 准备

Node.js 20 以上，装依赖不需要，直接用 npx：

node -v
npx wrangler --version

如果还没登录，npx wrangler login 会在浏览器里走一次 OAuth。登录状态可以用 wrangler whoami 确认，它会显示账号名与 Account ID。

2. 建项目

mkdir my-site && cd my-site

wrangler.toml 描述项目：

name = "cf53-demo"
main = "src/index.js"
compatibility_date = "2026-11-01"

src/index.js 是全部代码：

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === "/api/time") {
      return Response.json({ now: new Date().toISOString() });
    }
    if (url.pathname === "/api/ip") {
      return Response.json({
        ip: request.headers.get("cf-connecting-ip"),
        country: request.cf?.country ?? "unknown",
        colo: request.cf?.colo ?? "unknown"
      });
    }
    return new Response(
      `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8">
       <title>KernelRanch 免费站点</title></head>
       <body><h1>这个页面跑在 Cloudflare Workers 上</h1>
       <p><a href="/api/time">/api/time</a></p>
       <p><a href="/api/ip">/api/ip</a></p></body></html>`,
      { headers: { "content-type": "text/html; charset=utf-8" } }
    );
  }
};

三个分支对应三个路径，其余全部返回首页。这个"其余全部"就是第 5 节要讲的 404 问题。

3. 部署

wrangler deploy

真实输出（2026-11-10，wrangler 4.146.0）：

Total Upload: 1.37 KiB / gzip: 0.80 KiB
Worker Startup Time: 2 ms
Uploaded cf53-demo (3.13 sec)
Deployed cf53-demo triggers (1.60 sec)
  https://cf53-demo.hyysn.workers.dev
Current Version ID: adefe73b-f699-43fd-91ae-d44297a74033

几个可以对照的数字：代码 1.37 KiB，压完 0.80 KiB；启动 2ms；上传 3.13 秒，路由生效 1.60 秒。这就是"部署一个站点"的全部成本。

4. 验证

Invoke-WebRequest -Uri 'https://cf53-demo.hyysn.workers.dev' -UseBasicParsing |
  Select-Object StatusCode, RawContentLength, Headers

实测结果：

请求	状态	内容
`GET /`	200	597 字节，`server: cloudflare`，`cf-ray: ...-HKG`
`GET /api/time`	200	`{"now":"2026-11-10T06:35:27.339Z","path":"/api/time"}`
`GET /api/ip`	200	`{"ip":"218.188.154.160","country":"HK","colo":"HKG"}`

cf-ray 后缀 HKG 说明请求落在香港机房；colo 字段是同一信息在应用层的暴露。country 来自 Cloudflare 的 IP 地理位置库，不需要你自己接第三方接口。

5. 为什么访问不存在的路径也返回 200

访问 /nope，实测返回的也是 200——因为代码里"其余全部返回首页"。Workers 没有内置的 404 逻辑，路由完全由你决定。

正确写法是显式返回 404：

return new Response("Not Found", { status: 404 });

这既是教学点，也是排查"为什么我的错误页不生效"的常见原因：不是 Cloudflare 的问题，是代码没写。

6. 下一步

代码怎么写得更像应用，见 54-workers-fetch-handler-tutorial.md；想把 workers.dev 换成自己的域名，前提是域名已经接入并 Active，见 55-workers-routes-custom-domain.md。

小结

从空目录到可访问站点，实际投入是三个文件（wrangler.toml、src/index.js、以及 Node 环境）和一条命令。部署耗时 3 秒，代码 1.4KB，这就是 Workers 的卖点。

两个容易忽略的点：workers.dev 域名是共享子域，证书是 *.workers.dev 通配证书；以及路由没有默认 404，你得自己写。

数据来源与检索时间

检索时间 2026-11-10。部署与访问数据均为本机真实执行。

来源	URL	对应数据
Workers 入门指南	https://developers.cloudflare.com/workers/get-started/guide/	`wrangler init` / 项目结构 / `wrangler deploy` 的官方流程
Workers 限额	https://developers.cloudflare.com/workers/platform/limits/	免费档 100,000 请求/天、启动时间与包体积的限制
Workers 路由	https://developers.cloudflare.com/workers/configuration/routing/routes/	`workers.dev` 默认域名与自定义域的前置条件

核验说明

第 3、4 节的输出为本机真实执行结果：部署输出、三个端点的状态码与响应体、cf-ray 与 colo 均原样记录。
站点当前仍然在线（cf53-demo.hyysn.workers.dev），用于验证文档可复现；不再需要时可 wrangler delete cf53-demo 删除。
未做：没有给这个站点绑定自定义域（账号无 Zone 权限），第 6 节的绑定步骤依据文档。

#Cloudflare