如何创建一个Cloudfalare worker项目？

在你本地创建一个 Worker 项目目录

mkdir xxx-worker && cd xxx-worker

初始化 Worker

npx wrangler init

What would you like to start with? ● Hello World example   ○ Framework Starter  ○ Application Starter     ○ Template from ○ a GitHub repo ◁ Go back

很好，这四个选项其实就是帮你“起步的脚手架程度”不同而已——从最轻到最重大致是这样：

四种模板到底是什么？

1. Hello World example（最轻）

• 内容：就一个最小可运行的 Worker（src/index.ts + wrangler.toml），返回 “Hello World”。
• 适合：想快速理解 Worker 的运行机制、手写路由/中间件、自己决定用不用 D1/R2/KV。
• 优点：干净、无魔法、容易学原理。
• 缺点：一切都要自己搭（路由、错误处理、结构化目录）。

2. Framework Starter（中等）

• 内容：基于常见框架的 Starter，例如 Hono（轻量路由）、Remix/SvelteKit/React（一般跑在 Pages）等，并配好 Cloudflare 适配器。
• 适合：想马上拥有路由/中间件等开发体验，又不想拉一大堆“完整应用”样板。
• 优点：上来就有优雅的路由/请求处理；对 “Worker 当后端 API” 场景非常友好（推荐 Hono）。
• 缺点：比 Hello World 多一点“框架约束”。

3. Application Starter（偏重）

• 内容：更“带电池”的示例应用（可能已经整合了 D1/KV/R2、鉴权、示例路由、页面等）。
• 适合：想快速看一个可用示例，然后改着用；或者做 PoC。
• 优点：开箱即跑、很快看到全链路。
• 缺点：模板结构更“意见强”，删改成本稍高；对新手理解原理不如 Hello World 直观。

4. Template from a GitHub repo（自定义）

• 内容：从任意 GitHub 仓库拉一个模板。
• 适合：你已经看中某个社区模板/我给你的专门仓库。
• 优点：随心所欲。
• 缺点：质量与维护取决于模板来源。

---

我该选哪一个？（结合你的 CloudMusic 管理后台）

• 想先学清楚 Worker 原理/生命周期 → 选 Hello World，然后你可以按需把 D1/R2/KV 逐步接进来。
• 想直接开始写 API，少铺垫 → 选 Framework Starter → Hono（Workers）。这是我更推荐你现在用的路线：有路由、有中间件、TypeScript 体验好，目录也干净。

你前期强调“用 Cloudflare 免费额度，不想复杂”，Hello World 和 Hono Starter 都完美契合。

---

如果选了 Hello World，下一步怎么把它变成 API？

生成文件后你会看到：

wrangler.toml
src/index.ts

wrangler.toml（最小配置）

name = "cloudmusic-admin"
main = "src/index.ts"
compatibility_date = "2025-08-21"

以后需要 D1/R2，再加：

[[d1_databases]]
binding = "DB"
database_name = "cloudmusic-db"
database_id = "你的D1ID"[[r2_buckets]]
binding = "MUSIC_BUCKET"
bucket_name = "cloudmusic"

src/index.ts（手写一个最小路由）

export default {async fetch(request, env, ctx): Promise<Response> {const { pathname } = new URL(request.url);if (pathname === "/songs" && request.method === "GET") {// 这里先返回静态数据，后面再接 D1/R2/KVreturn Response.json([{ id: 1, title: "Song A", artist: "Singer A", duration: 210 },{ id: 2, title: "Song B", artist: "Singer B", duration: 188 }]);}return new Response("Not Found", { status: 404 });}
};

本地调试/部署：

npx wrangler dev    # 本地 http://127.0.0.1:8787/songs
npx wrangler deploy # 线上 https://cloudmusic-admin.<你>.workers.dev/songs

---

如果选 Framework Starter → Hono，开发体验会更舒服

初始化时选择 Framework Starter，再选 Hono (Workers)，会得到自动化的路由脚手架。
示例（Hono 版 src/index.ts）：

import { Hono } from 'hono';type Bindings = {DB: D1Database;MUSIC_BUCKET: R2Bucket;
};const app = new Hono<{ Bindings: Bindings }>();app.get('/songs', async (c) => {// 先返回静态，后续可换成 D1 查询或从 R2 列表生成return c.json([{ id: 1, title: "Song A", artist: "Singer A", duration: 210 },{ id: 2, title: "Song B", artist: "Singer B", duration: 188 }]);
});app.notFound((c) => c.text('Not Found', 404));export default app;

优点：app.get('/xxx', ...) 的写法更接近你习惯的后端路由；后续加中间件、鉴权、错误处理都更顺手。

---

选 Hello World 的好处（为什么很多人建议从它开始）

• 学习价值高：你会亲手搭路由、处理请求/响应、管理 Env 绑定（D1/KV/R2）；
• 无“隐藏魔法”：出了问题更好排查；
• 迁移自由：以后想切换到 Hono 也不难（把 switch-case 路由迁过去即可）。

---

常见问题（速记）

• 没有自定义域名怎么办？
  不影响。部署后会有免费的 workers.dev 二级域名可用。

• 会不会收费？
  你当前的规模在 Cloudflare 免费额度内完全够用：Worker 请求、D1 读写、R2 存储都很宽裕。

• 选错模板了怎么办？
  直接删掉目录重新 npx wrangler init，或者把模板里的代码按你的偏好调整即可。

---

👌 案例：设计一份 CloudMusic Worker + D1 + R2 的免费版初始化流程，确保前期开发测试全都用 Cloudflare 免费额度（不会产生额外费用）。

---

✅ Cloudflare 免费额度概览

• Workers：每天 100,000 次免费请求。开发够用了。
• KV（Key-Value）存储：每天 1,000,000 次读写操作免费。
• D1（SQLite 数据库云托管）：1GB 免费存储 + 5M 行读写/月。
• R2（对象存储）：每月 10GB 存储 + 1,000,000 次操作免费。

---

⚡ 初始化流程（0 成本版）

1️⃣ 创建 Worker 项目

# 在你本地创建一个 Worker 项目目录
mkdir cloudmusic-worker && cd cloudmusic-worker# 初始化 Worker
npx wrangler init

• 选 TypeScript 模板
• 会自动生成 wrangler.toml、src/index.ts

---

2️⃣ 创建 D1 数据库

npx wrangler d1 create cloudmusic-db

输出结果类似：

⛅️ Successfully created DB 'cloudmusic-db' with ID 1234-abcd-5678-efgh

⚠️ 免费版 D1 限额 1GB 存储，你的歌曲信息（songs.json）+ 歌单数据足够了。

在 wrangler.toml 里添加：

[[d1_databases]]
binding = "DB"
database_name = "cloudmusic-db"
database_id = "1234-abcd-5678-efgh"

---

3️⃣ 初始化数据库表

先写好 schema.sql：

CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT,username TEXT UNIQUE,password TEXT
);CREATE TABLE IF NOT EXISTS playlists (id INTEGER PRIMARY KEY AUTOINCREMENT,user_id INTEGER,name TEXT,FOREIGN KEY(user_id) REFERENCES users(id)
);CREATE TABLE IF NOT EXISTS songs (id INTEGER PRIMARY KEY AUTOINCREMENT,title TEXT,artist TEXT,duration INTEGER,file_url TEXT,cover_url TEXT
);CREATE TABLE IF NOT EXISTS playlist_songs (playlist_id INTEGER,song_id INTEGER,FOREIGN KEY(playlist_id) REFERENCES playlists(id),FOREIGN KEY(song_id) REFERENCES songs(id)
);

导入到 D1：

npx wrangler d1 execute cloudmusic-db --file=src/db/schema.sql

---

4️⃣ 创建 R2 存储桶

npx wrangler r2 bucket create cloudmusic

在 wrangler.toml 里添加：

[[r2_buckets]]
binding = "MUSIC_BUCKET"
bucket_name = "cloudmusic"

---

5️⃣ 本地开发调试

npx wrangler dev

你会得到一个本地调试地址：

http://127.0.0.1:8787

---

6️⃣ 部署到 Cloudflare

npx wrangler deploy

部署后会得到一个免费二级域名，例如：

https://cloudmusic-worker.username.workers.dev

---

✅ 你得到的效果

1. Worker = 你的后端 API （替代 Java、Node 服务）。

   • /auth/login 登录
   • /playlist/add 新建歌单
   • /song/list 获取歌曲

2. D1 = 数据库 （存储用户、歌单、歌曲信息）。

3. R2 = 文件存储 （存储 mp3、图片封面）。

👉 所有这些服务在免费额度下都够你开发和日常测试使用。

---