01. 开始之前
这一章不要跳。
如果这一章没做好，你后面基本一定会卡住。
1. 你到底要部署哪些东西
Section titled “1. 你到底要部署哪些东西”ZShip 不是一个单页面项目。
它是一整套会交付给用户的系统，至少包含：
- 10 个后端 Worker
- 2 个会交付给用户的前端项目
- 9 个 D1 数据库
- 1 个 KV namespace 给支付服务使用
- 1 个 R2 bucket 给 CDN 服务使用
所以你不是在部署一个网站。
你是在部署一套”前台 + 后台 + 微服务 + 数据库 + 存储”的 Cloudflare 系统。
2. 你需要准备什么账号
Section titled “2. 你需要准备什么账号”至少准备下面这些：
- 一个 Cloudflare 账号
- 一个 Git 仓库副本
- 一台能运行 Node.js 的电脑
可选账号：
- Stripe 账号，如果你要开真实支付
- Creem 账号，如果你要开 Creem 支付
- Google OAuth 应用，如果你要开 Google 登录
3. 先决定你要怎么拿这份源码
Section titled “3. 先决定你要怎么拿这份源码”这是第一步里最容易被忽略、但会影响后续维护成本的选择。
你有两种方式。
方式 A：GitHub Fork
Section titled “方式 A：GitHub Fork”做法：
- 打开官方模板仓库
- 点击 GitHub 右上角的
Fork - 把仓库 fork 到你自己的账号或组织
- 再把 fork 之后的仓库 clone 到本地
优点：
- 还保留和官方模板仓库的关联
- 以后官方模板继续更新时，你更容易手动同步
- 更适合基于模板长期维护
缺点：
- 不会自动更新
- 以后同步官方更新时，仍然需要你手动处理
方式 B：直接复制代码，然后自己新建仓库
Section titled “方式 B：直接复制代码，然后自己新建仓库”做法：
- 下载官方模板代码
- 删除原来的 git 历史，或者不要保留原仓库关系
- 在你自己的 GitHub 账号下新建一个全新仓库
- 把代码推上去
优点：
- 仓库历史更像你自己的项目
- 对有些团队来说更容易接受
缺点：
- 以后官方模板更新时，你不会有现成的上游同步入口
- 想跟进官方更新，基本只能手工比对、手工合并
推荐你选哪个
Section titled “推荐你选哪个”推荐：
- 选
GitHub Fork
原因：
- 这套模板后续官方还会继续更新
fork至少保留了后面吃官方更新的通道- 对大多数用户来说，这是维护成本最低的方案
但你必须记住：
Fork不会自动让你获得官方更新
如果官方模板未来更新了：
- 你需要手动同步 upstream
- GitHub 上可以用
Sync fork - 或者你在本地自己执行
fetch+merge/rebase
4. 你电脑上需要安装什么
Section titled “4. 你电脑上需要安装什么”请确认本机已经安装：
- Node.js 22 或更高版本
- pnpm
- Git
安装完成后，在终端里执行：
node -vpnpm -vgit --version三个命令都能正常返回版本号，再继续。
5. 先把 Dev Console 跑起来
Section titled “5. 先把 Dev Console 跑起来”如果你是第一次接触这个项目，建议在继续前先执行：
pnpm dev:console启动后访问：
http://localhost:3900你先不用把所有功能都点一遍。
先确认下面 3 个标签你能看到：
新手入门本地启动部署 Cloudflare
这会大幅降低你后面排错的成本。
6. 把仓库拉到本地
Section titled “6. 把仓库拉到本地”如果你已经有仓库，可以跳过。
如果你还没有，把你的仓库拉下来：
git clone <你的仓库地址>cd zship如果你选择的是 Fork
Section titled “如果你选择的是 Fork”这里的仓库地址，应该是你 fork 之后自己的仓库地址。
不是官方仓库地址。
如果你选择的是”自己新建仓库”
Section titled “如果你选择的是”自己新建仓库””那这里就是你自己新仓库的地址。
然后安装依赖：
pnpm install安装时间可能会有点长，正常。
如果安装过程报错，不要继续后面的步骤，先把依赖装好。
7. 登录 Wrangler
Section titled “7. 登录 Wrangler”Wrangler 是 Cloudflare 官方命令行工具。
本项目的 Worker、Pages、D1、KV、R2 资源都会通过它来创建或部署。
在仓库根目录执行：
npx wrangler login浏览器会自动打开 Cloudflare 授权页面。
授权完成后，再执行：
npx wrangler whoami如果能看到你的 Cloudflare 账号信息，说明 Wrangler 登录成功。
8. 第一次部署时，你不要做的事
Section titled “8. 第一次部署时，你不要做的事”不要改这些 Worker 名称
Section titled “不要改这些 Worker 名称”zship-node1-authzship-node2-supportzship-node3-payzship-node4-notifyzship-node5-blogzship-node6-cdnzship-node7-sitezship-node8-promptzship-node9-checkinzship-node10-ai
不要改这些 Pages 项目名
Section titled “不要改这些 Pages 项目名”webadmin
9. 这一章结束前，你应该已经满足的条件
Section titled “9. 这一章结束前，你应该已经满足的条件”请自己对照一遍：
- 你已经决定是
Fork还是”自己复制代码建仓库” - 你已经知道
pnpm dev:console怎么启动 - 你已经把仓库拉到本地
- 你已经执行过
pnpm install - 你已经执行过
npx wrangler login - 你已经执行过
npx wrangler whoami - 你知道第一遍不要改默认名称
如果上面有任意一项没完成，不要进下一章。