一条龙上线部署

代码写完了，怎么让全世界都能访问？这篇教你用 Vercel + Railway + Cloudflare 三件套，把前后端都部署上线。

架构说明

这套组合的好处：免费额度够用、部署简单、全球访问快。

第一步：部署后端到 Railway

先把后端搞定，前端才有接口可调。

1. 注册 Railway

访问 railway.app，用 GitHub 账号登录。

2. 创建项目

两种方式，选一个：

方式一：用模板（推荐新手）

访问 FastAPI + PostgreSQL 模板，点击 Deploy，一键部署。

方式二：连 GitHub 仓库

1. Railway 控制台 → New Project → Deploy from GitHub repo
2. 选你的后端仓库
3. Railway 自动识别 FastAPI，开始部署

3. 添加 PostgreSQL 数据库

1. 项目页面 → New → Database → PostgreSQL
2. 等它创建好，点进去看 Variables 标签
3. 复制 DATABASE_URL，等下要用

4. 配置环境变量

点击你的 FastAPI 服务 → Variables，添加这些：

DATABASE_URL=postgresql://... （从 PostgreSQL 服务复制）
SECRET_KEY=你的密钥（随便生成一个长字符串）
SUPABASE_URL=你的 Supabase 地址（如果用了的话）
SUPABASE_KEY=你的 Supabase Key

5. 获取后端地址

部署成功后，Railway 会给你一个地址，类似：

https://your-app.up.railway.app

记住这个地址，前端要用。

第二步：部署前端到 Vercel

1. 注册 Vercel

访问 vercel.com，用 GitHub 账号登录。

2. 导入项目

1. 控制台 → Add New → Project
2. 选择你的前端 GitHub 仓库
3. Vercel 自动识别 Next.js
4. 点 Deploy

3. 配置环境变量

部署前，先配好环境变量：

Settings → Environment Variables，添加：

NEXT_PUBLIC_API_URL=https://your-app.up.railway.app  （你的后端地址）
NEXT_PUBLIC_SUPABASE_URL=你的 Supabase 地址
NEXT_PUBLIC_SUPABASE_ANON_KEY=你的 Supabase Key

注意：前端环境变量要以 NEXT_PUBLIC_ 开头，不然客户端拿不到。

4. 重新部署

改完环境变量后，需要重新部署才生效：

Deployments → 点最新的那个 → Redeploy

第三步：配置 Cloudflare 域名

1. 注册 Cloudflare

访问 cloudflare.com，注册账号。

2. 添加域名

1. Add a Site → 输入你的域名
2. 选 Free 计划
3. Cloudflare 会给你两个 nameserver 地址
4. 去你的域名注册商（阿里云/腾讯云/GoDaddy），把 DNS 服务器改成 Cloudflare 给的

3. 配置前端域名（Vercel）

Vercel 控制台 → 你的项目 → Settings → Domains
添加你的域名，比如：www.yourdomain.com

Vercel 会告诉你需要添加的 DNS 记录，去 Cloudflare 添加：
类型：CNAME
名称：www
内容：cname.vercel-dns.com

4. 配置后端域名（Railway）

Railway 默认给你的地址是 xxx.up.railway.app，生产环境最好换成自己的域名。

第一步：在 Railway 添加自定义域名

1. Railway 控制台 → 点击你的 FastAPI 服务
2. Settings → Networking → Custom Domain
3. 点击 "Add Custom Domain"
4. 输入你的子域名：api.yourdomain.com
5. Railway 会显示需要配置的 CNAME 记录值，类似：xxx.railway.app

第二步：在 Cloudflare 添加 DNS 记录

1. Cloudflare 控制台 → DNS → Records → Add record
2. 类型：CNAME
3. 名称：api（这样最终域名就是 api.yourdomain.com）
4. 目标：粘贴 Railway 给你的那个地址
5. 代理状态：先关掉（灰色云朵），等验证通过再开
6. 点击保存

第三步：等待验证

回到 Railway，等几分钟，状态会从 "Pending" 变成 "Active"
验证通过后，就可以用 https://api.yourdomain.com 访问后端了

第四步：更新前端的 API 地址

域名配好后，记得把前端的环境变量改成新域名：

Vercel → Settings → Environment Variables
把 NEXT_PUBLIC_API_URL 改成 https://api.yourdomain.com
然后重新部署

5. 开启 SSL

Cloudflare 默认开启 SSL，确保设置是：

SSL/TLS → Overview → Full (strict)

第四步：解决 CORS 跨域问题

这是最容易踩的坑！前端 www.yourdomain.com 调用后端 api.yourdomain.com，浏览器会拦截。

后端配置（FastAPI）

在 main.py 里加上：

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://www.yourdomain.com",
        "https://yourdomain.com",
        "http://localhost:3000",  # 本地开发
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

前端配置（Next.js）

如果后端配了还不行，可以在 next.config.js 加个代理：

module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'https://api.yourdomain.com/:path*',
      },
    ]
  },
}

Vercel 配置

在项目根目录创建 vercel.json：

{
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Credentials", "value": "true" },
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Access-Control-Allow-Methods", "value": "GET,POST,PUT,DELETE,OPTIONS" },
        { "key": "Access-Control-Allow-Headers", "value": "Content-Type, Authorization" }
      ]
    }
  ]
}

第五步：用 Playwright 调试线上环境

部署完了，让 Claude 帮你测一遍：

测试前端页面

用 playwright 访问 https://www.yourdomain.com，截图看看首页效果

测试后端接口

用 playwright 访问 https://api.yourdomain.com/docs，看看 FastAPI 文档页面能不能打开

测试完整流程

用 playwright 访问我的网站 https://www.yourdomain.com，执行以下操作：
1. 点击注册按钮
2. 填写邮箱和密码
3. 点击提交
4. 看看有没有报错

检查控制台错误

用 playwright 访问首页，帮我看看控制台有没有 CORS 错误或者其他报错

常见问题排查

Supabase IPv6 连接问题（重要！）

从 2024 年开始，Supabase 新项目默认只支持 IPv6，但很多部署平台（包括 Railway）不支持 IPv6 直连，会报错：

connection to server failed: Connection refused

解决方案：使用 Pooler 连接串

第一步：找到 Pooler 连接串

1. 登录 Supabase 控制台
2. 进入你的项目 → Settings → Database
3. 找到 "Connection string" 部分
4. 选择 "Mode: Session" 或 "Mode: Transaction"
5. 复制 Pooler 连接串（不是直连的那个！）

两种连接串对比：

❌ 直连（IPv6，可能连不上）：
postgres://postgres:[密码]@db.xxxx.supabase.co:5432/postgres

✅ Pooler 连接（IPv4 兼容，推荐）：
postgres://postgres.xxxx:[密码]@aws-0-us-east-1.pooler.supabase.com:6543/postgres

注意看区别：

• 用户名从 postgres 变成 postgres.xxxx（带项目 ID）
• 域名从 db.xxxx.supabase.co 变成 pooler.supabase.com
• 端口从 5432 变成 6543（或用 5432 走 Session 模式）

第二步：更新 Railway 环境变量

Railway → 你的服务 → Variables
把 DATABASE_URL 改成 Pooler 连接串
重新部署

其他方案

如果 Pooler 还是不行，还有两个选择：

1. 买 IPv4 附加组件：Supabase Pro 计划可以花 $4/月 买专用 IPv4 地址
2. 用 Railway 自带的 PostgreSQL：Railway 自己的数据库没有 IPv6 问题

验证连接

部署后让 Claude 帮你测：

用 playwright 访问 https://api.yourdomain.com/docs，看看 FastAPI 能不能正常启动，有没有数据库连接错误

环境变量清单

Railway（后端）

DATABASE_URL=postgresql://...
SECRET_KEY=随机字符串
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_KEY=eyJxxx...

Vercel（前端）

NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJxxx...

部署完成检查清单

[ ] Railway 后端部署成功，能访问 /docs 页面
[ ] Vercel 前端部署成功，能打开首页
[ ] Cloudflare 域名解析生效
[ ] HTTPS 正常工作
[ ] CORS 跨域问题解决
[ ] 前端能正常调用后端接口
[ ] 用 Playwright 走一遍完整用户流程

参考链接

• Railway FastAPI 部署文档
• Railway FastAPI + PostgreSQL 模板
• Vercel 启用 CORS 指南
• Vercel 部署文档