面向使用 AI 但不懂代码的新手。跟着点就能上线，遇到问题有 AI 帮忙排查。基于真实部署经验整理。
当我们已经有网站项目代码，并且代码已经上传到 GitHub 仓库时，可以使用本 SOP 完成网站部署上线。
| 条件 | 说明 | 是否必须 |
|---|---|---|
| GitHub 账号 | 代码已上传到 GitHub 仓库 | 必须 |
| Cloudflare 账号 | 用于部署前端和 API 代理 | 必须 |
| Railway 账号 | 用于部署后端（仅全栈网站需要） | 有后端时必须 |
| 代理工具（VPN） | 注册和配置海外平台时需要 | 必须（见第二章） |
| AI 工具 | 遇到问题随时让 AI 帮忙 | 强烈建议 |
| 平台 | 国内状态 | 用途 |
|---|---|---|
| Cloudflare Pages | 直连可用 | 前端托管 + API 代理 |
| DeepSeek API | 直连可用 | AI 大模型 |
| GitHub | 不稳定 | 代码仓库 |
| Cloudflare 控制台 | 建议开代理 | 配置部署 |
| Railway | 被墙 | 后端托管 |
| Vercel | 被墙 | 不要用 |
| 操作 | 需要代理？ | 说明 |
|---|---|---|
| 注册 GitHub / Cloudflare / Railway | 需要开 | 注册页面需要验证，国内直连可能卡住 |
| 使用 Cloudflare 控制台 | 建议开 | 页面加载更稳定 |
| 推送代码到 GitHub | 看情况 | 大部分时间可用，断连时开代理 |
| 用户访问你的网站 | 不需要 | 网站在 Cloudflare 上，国内直连 |
如果你有代理软件（如 Clash），端口通常是 7890 或 10808：
# 设置代理
git config --global http.proxy http://127.0.0.1:10808
git config --global https.proxy http://127.0.0.1:10808
# 取消代理
git config --global --unset http.proxy
git config --global --unset https.proxy不确定端口的话，问 AI："我的代理软件是 XXX，帮我看看本地代理端口是多少"。
在开始部署前，确认以下内容：
package.json 内容、目录截图或仓库地址发给 AI，让 AI 帮忙判断构建命令和输出目录。
这是核心步骤。Cloudflare Pages 是国内可直连的前端托管平台，免费且无限流量。
进入 Cloudflare 后台
打开 https://dash.cloudflare.com/（建议开代理），登录后进入控制台首页。
找到 Workers & Pages
在左侧菜单栏找到 Workers & Pages，点击进入。
如果左侧菜单很多，在 Build / Compute 分类下找。
创建新应用
点击右上角蓝色按钮 Create application。
选择部署 Pages
默认显示 Create a Worker。我们是部署网站页面，需要选 Pages。
在页面下方找到 "Looking to deploy Pages? Get started"，点击 Get started。
选择导入 Git 仓库
选择 Import an existing Git repository，点击 Get started。
选择这个选项后，后续 GitHub 代码更新，Cloudflare 可以自动重新部署。
选择 GitHub 仓库
确认 GitHub 账号 → 在 Select a repository 区域选择目标仓库。
仓库太多可以在搜索框输入名称搜索。
如果找不到仓库怎么办？
页面底部会提示 "configure repository access for the Cloudflare Pages app on GitHub"，点击 Cloudflare Pages 链接：
配置构建和部署信息
选择仓库后进入配置页面，需要填写构建命令和输出目录。
| 项目类型 | 构建命令 | 输出目录 |
|---|---|---|
| 纯 HTML/CSS/JS 静态网站 | 留空 | / |
| Vite 项目 | npm run build | dist |
| React 项目 | npm run build | build 或 dist |
| Next.js 静态导出 | npm run build | out |
| Astro 项目 | npm run build | dist |
package.json 内容发给 AI，让 AI 判断。
点击部署
点击 Save and Deploy，Cloudflare 开始构建和部署。
等待部署完成
部署过程中会显示构建日志。成功后显示：
Success! Your project is deployed to Region: Earth
并展示预览地址，例如 website-deploy-sop.pages.dev。
找到正式网站地址
在项目详情页 Deployments → Production 区域，可以看到：
https://你的项目名.pages.dev
这个地址就是正式访问地址，可以分享给任何人。
xxx.pages.dev 对外使用；单次预览地址 4601e4a2.xxx.pages.dev 是某次部署的预览链接。对外分享用正式地址。
Railway 是一个免费的后端托管平台（每月 $5 免费额度），支持 Python、Node.js 等。类似 Cloudflare Pages 之于前端，Railway 是后端的托管平台。
注册 Railway 账号（需要开代理）
打开 https://railway.app
点击右上角 Login 按钮
选择 Login with GitHub
中文理解：用 GitHub 账号直接登录，不需要单独注册
首次登录会弹出 GitHub 授权页面，点击 Authorize Railway 同意授权
授权后自动进入 Railway 控制台首页
创建新项目
在 Railway 控制台首页，点击 New Project 按钮（通常在右上角或页面中间）
弹出选项菜单，选择 Deploy from GitHub repo
中文理解：从 GitHub 仓库部署
选择后端仓库
选择 Deploy from GitHub repo 后，会显示你的 GitHub 仓库列表
在列表中找到并点击你的后端代码仓库
选择仓库后，Railway 会自动开始构建和部署
构建过程可能需要 1-3 分钟，耐心等待
配置环境变量
进入刚创建的项目页面，点击顶部的 Variables 标签
点击 New Variable 按钮，逐个添加环境变量
常见环境变量参考：
| 变量名 | 值 | 说明 |
|---|---|---|
DEEPSEEK_API_KEY | sk-xxxxxxxx | DeepSeek AI 的 API 密钥 |
PORT | 8000 | 后端运行端口（一般自动检测） |
https://platform.deepseek.com（国内可直连，不需要代理）→ 注册登录 → 左侧菜单 API Keys → 点击 创建 API Key → 复制密钥。
.env.example、config.py 或 requirements.txt 发给 AI，让 AI 告诉你需要配置哪些环境变量。
生成公网访问地址
进入项目页面，点击 Settings 标签
找到 Networking 区域
点击 Generate Domain 按钮
Railway 会自动生成一个公网地址，格式类似：
https://web-production-xxx.up.railway.app验证后端是否正常运行
在浏览器中打开后端地址 + /health：
https://你的后端地址.up.railway.app/health看到 {"status":"ok"} 或类似的 JSON 返回，说明后端正常运行。
查看运行日志（验证失败时）
如果验证失败，进入项目 Logs 标签查看运行日志
把日志中的报错信息复制发给 AI，让 AI 帮你排查原因
原理：用户访问 你的网站.pages.dev/api/xxx → Cloudflare 收到请求 → 转发到 Railway 后端 → 后端返回数据 → Cloudflare 返回给用户。整个过程用户无感知。
让 AI 帮你创建代理文件
不要自己写代码！把以下信息发给 AI，让 AI 帮你生成代理文件：
请帮我创建 Cloudflare Pages Functions 代理文件：
- 我的前端仓库地址是：XXX
- 后端地址是：https://你的后端地址.up.railway.app
- 需要代理的接口：/api/research（POST 请求）
- 还需要一个 /api/health 健康检查代理
请告诉我：
1. 需要创建哪些文件？
2. 每个文件的完整内容是什么？
3. 文件应该放在仓库的什么位置？AI 会告诉你具体需要创建哪些文件、文件内容、以及放在哪里。
把文件放到正确位置
AI 告诉你创建的文件，通常放在前端仓库的 functions/api/ 目录下：
你的前端仓库/
├── functions/
│ └── api/
│ ├── research.js ← 代理搜索接口
│ └── health.js ← 代理健康检查
├── src/
├── package.json
└── ...推送到 GitHub
如果用 AI 编程工具，可以让 AI 帮你执行推送。也可以用命令行：
git add .
git commit -m "添加API代理"
git push origin main验证代理是否正常
等 Cloudflare 构建完成后，在浏览器中打开：
https://你的网站.pages.dev/api/health看到 {"status":"ok"} 说明代理正常工作！
网站上线后，不要只看 Cloudflare 显示成功，还需要自己检查一遍。
原因：Cloudflare 没有该仓库的访问权限。
解决：点击页面底部的 Cloudflare Pages 授权链接，到 GitHub 重新授权目标仓库。
错误信息：npm ci can only install packages when lock file in sync
原因：升级了依赖版本但锁文件没更新。
解决：让 AI 帮你删除 package-lock.json 并重新推送。
错误信息：Page with dynamic = "force-dynamic" couldn't be exported
原因：Next.js 静态导出模式不允许使用 force-dynamic。
解决：把报错信息发给 AI，让 AI 帮你找到并删除相关代码。
原因：通常是输出目录填写错误。
解决：检查构建输出目录。Vite 项目是 dist，Next.js 静态导出是 out。不确定就问 AI。
原因：后端未运行、地址错误或代理文件配置有误。
解决：
BACKEND_URL 是否正确原因：构建可能还在进行中，或者构建失败了。
解决：在 Cloudflare 控制台 Deployments 页面查看构建状态。如果 Failed，查看构建日志找原因。修复后重新推送代码。
现象：Cloudflare 或其他平台提示 "Vulnerable version of Next.js detected"。
解决：把提示信息发给 AI，让 AI 帮你升级到安全版本。升级后记得删除 package-lock.json 重新推送。
原因：Vercel 在国内被墙。
解决：改用 Cloudflare Pages 部署前端。这也是本 SOP 推荐用 Cloudflare 的原因。
如果部署时不确定怎么填，或者遇到报错，直接用以下模板问 AI：
我现在要把这个 GitHub 仓库部署到 Cloudflare Pages。
仓库地址是：XXX
请你帮我判断：
1. 这个项目是什么技术栈？
2. Cloudflare Pages 的构建命令应该填什么？
3. 构建输出目录应该填什么？
4. 是否需要环境变量？
5. 如果部署失败，我应该优先检查哪些地方？我在 Cloudflare Pages 部署网站时报错了。
这是报错信息：
【粘贴报错日志】
请你帮我判断：
1. 报错原因是什么？
2. 应该怎么修改？
3. Cloudflare Pages 配置里需要改哪些地方？
4. 修改后如何重新部署？我的网站已经部署到 Cloudflare Pages 了，
地址是：https://xxx.pages.dev
但是遇到以下问题：
【描述问题，比如：搜索功能用不了 / 页面显示不全 / 接口报错】
后端地址是：https://xxx.up.railway.app
请你帮我排查原因，告诉我应该怎么解决。修改代码后，只需要一条命令重新部署：
git add .
git commit -m "修改说明"
git push origin main推送后 Cloudflare 会自动重新构建，通常 2-3 分钟后新版本上线。不需要手动操作。
Cloudflare 自带免费的数据分析功能：
推荐用 UptimeRobot（https://uptimerobot.com）免费监控网站是否在线：
如果新版本有问题，可以回退：
前端部署（必须）：
xxx.pages.dev 正式地址后端部署（有后端时需要）：
xxx.up.railway.app/health 返回正常API 代理配置（后端在 Railway 时必须）：
functions/api/ 目录xxx.pages.dev/api/health 返回正常| 名称 | 地址格式 | 用途 |
|---|---|---|
| 前端地址 | https://xxx.pages.dev | 分享给用户 |
| 后端地址 | https://xxx.up.railway.app | 配置在代理文件里 |
| 健康检查 | https://xxx.pages.dev/api/health | 验证是否正常 |