这几年我前后经手的 Web 工程不算少。从早几年流行的 Spring Boot Vue到团队项目里的 Django React再到最近一年我和朋友做内部工具时用的 FastAPI React来回折腾过好几轮。如果要我用一句话概括这套组合的体验我会说它把开发效率、类型安全、运维成本这三件事平衡得很舒服。FastAPI 负责把 Python 生态的能力直接暴露成接口React 负责在浏览器里把接口数据渲染成真正能用的界面中间靠接口契约和部署配置把两端粘起来。这篇文章就沿着这条主线展开先聊为什么选它俩再一步步把工程初始化、接口对接、跨域配置、生产部署这些环节走一遍最后把我踩过的坑统一列出来。适合正在做全栈项目、准备从前端或者后端往对侧延伸的同学参考也适合团队内部从零搭建一套前后端分离工程时当作落地清单。1. 为什么是 FastAPI React技术选型背后的关键考量1.1 FastAPI 靠什么征服后端接口开发讲技术选型不能只看宣传语。FastAPI 最核心的卖点不是快而是用类型把接口约束起来。它基于 Starlette 和 Uvicorn底层走 ASGI天然支持异步但这只是性能下限的保障真正让开发体验提升一个档次的是它的类型注解配合 Pydantic 完成的请求解析和响应校验。举个最简单的例子。你定义一个接口接收 JSON 请求体用 FastAPI 只需要这样写from pydantic import BaseModel class TaskCreate(BaseModel): title: str done: bool False app.post(/api/tasks, response_modelTask) async def create_task(payload: TaskCreate): return await task_service.create(payload)这段代码写下来请求体有没有缺字段、类型对不对、返回结构是否一致全部由框架在运行前后自动处理。写错字段名、传错类型客户端拿到的不是脏数据而是明确的 422 错误。这一点在前后端分离的开发模式下特别有价值因为前端不依赖后端同事的口头描述只依赖一份自动生成的 OpenAPI 文档就能知道该传什么、会收到什么。FastAPI 的 /docs 和 /redoc 接口就是从这个契约里长出来的。对比一下Django 有一套自己的体系成熟但重Flask 灵活但一切靠自己拼。FastAPI 正好落在中间——文档自动生成、校验开箱即用、异步支持成熟而且整个生态和 Python 的数据处理、机器学习库无缝衔接。这两年 AI 相关的服务端接口大量用 FastAPI 写不是没有原因的。如果你团队里本来就有 Python 背景的成员FastAPI 的上手成本几乎是所有主流后端框架里最低的。1.2 React 在前端的位置为什么不止是能用React 已经从一个视图层库长成了一整套生态。现在用 Vite 初始化一个 React TypeScript 工程几乎不需要手动配 Webpack、Babel 这些烦人的东西创建完直接 npm run dev 就能开发。选择 React 而不是其他框架我的理由很朴素它组件化的心智模型足够稳定Hooks 把状态和副作用的管理方式统一了生态里从路由、状态管理到表格、图表、拖拽都有非常成熟的方案。而且求职市场上 React 的需求量一直很大学一套技能不只服务于当前项目。当然 Vue 也很好但在这个项目里我最终选了 React核心原因是团队里前端同学最熟的是 React而且我们后面要接一套 React 生态的大屏图表方案生态匹配度更重要。技术选型没有绝对的对错只有合适不合适。前后端分离的架构下前端框架本身是高度可替换的你只要把接口层抽象好今天用 React明天换 Vue后端几乎不用动。这句话反过来也成立React 前端对接 FastAPI、对接 Node 后端、对接 Java 后端也都能平滑切换。所以框架之争其实不是关键关键在于你怎样设计前后端的边界。1.3 前后端分离的架构边界怎么画前后端分离拆的不只是代码仓库更是职责边界。前端负责用户交互、路由、页面状态后端负责业务逻辑、数据持久化、权限校验。双方通过 JSON over HTTP 通信任何一端内部怎么实现另一端都不用关心。我用一个最简单的流程来描述这套项目的请求链路浏览器 → Nginx 静态资源(React SPA) → /api 请求 → FastAPI 应用 → 数据库/Redis/第三方服务在开发环境链路就变成Vite 开发服务器 → 后端接口 http://localhost:8000中间再叠一层 Vite proxy 或者 CORS 配置。到了生产环境Nginx 同时承担托管静态文件和反向代理 API两个角色这层配置我会在第 4 部分详细展开。这种架构最直接的好处是前端团队和后端团队可以并行开发后端先把接口文档定好前端用模拟数据就能开工后端也可以专注做接口性能和稳定性不用关心浏览器兼容性。缺点也不是没有——跨域问题、双重部署、环境变量管理、接口版本演进全都比单体应用麻烦。这篇文章后半部分主要就是在解决这些麻烦。2. 工程初始化从零搭出一套可运行的前后端项目2.1 后端初始化用 uv 快速创建 FastAPI 工程Python 环境的坑我自己踩了太多年。以前是 pip install 完才发现版本冲突后来用 venv 手动激活再后来用 Poetry直到最近换成 uv才算把创建虚拟环境、管理依赖、锁定版本这几件事做得顺畅了。uv 最大的优势是快创建环境、装依赖都比传统方式快一个量级而且它用一个 pyproject.toml uv.lock 就把依赖锁得明明白白。实际操作很简单uv init fastapi-demo cd fastapi-demo uv add fastapi uvicorn[standard]执行完这几条命令项目里会多出一个 pyproject.toml 和一个 uv.lock虚拟环境在第一次 uv add 时自动创建。之后启动开发服务uv run uvicorn app.main:app --reload --port 8000如果你暂时不想引入 uv用 python -m venv pip install fastapi uvicorn[standard] 也是一样的效果只是速度慢一些。工具是次要的关键是虚拟环境和依赖锁要建立起来否则过两周你再想复现这个项目依赖装不装得上都是个问题。项目结构我建议这样铺。别把什么都塞进一个 main.py接口多了之后会非常痛苦backend/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 实例、CORS、路由注册 │ ├── config.py # Pydantic Settings 配置 │ ├── models.py # 数据库模型(如果用 SQLAlchemy) │ ├── schemas.py # 请求/响应 Pydantic 模型 │ └── routers/ │ ├── __init__.py │ └── tasks.py # 按业务域拆分的路由 ├── pyproject.toml ├── uv.lock └── .envmain.py 里的基础结构保持简洁from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from app.routers import tasks app FastAPI(titleFullstack Demo API) # 先配 CORS后注册路由 app.add_middleware( CORSMiddleware, allow_origins[http://localhost:5173], allow_credentialsTrue, allow_methods[*], allow_headers[*], ) app.include_router(tasks.router, prefix/api)CORS 配置之所以放在路由注册前面是为了让所有路由都统一过同一套中间件避免出现有的接口能跨域、有的接口不能的诡异现象。2.2 前端初始化Vite React TypeScript 一把梭前端我直接用 Vite 的官方模板初始化命令就一行模板会把 React 和 TypeScript 的基础配置全部铺好省去手工拼 Webpack 配置的麻烦npm create vitelatest frontend -- --template react-ts cd frontend npm install npm run devVite 能在这个时代成为 React 社区默认的启动器核心原因是它开发时按需编译不用像 Webpack 那样一启动就要把整个应用打包一遍。改一行代码浏览器里几乎瞬间就能看到结果这种开发体验一旦用过就回不去了。模板生成完以后建议先做两件事。第一清理默认的 App.css 和 logo 引用别让示例代码留在项目里第二把访问后端的接口请求封装成单独模块不要在每个组件里裸写 fetch。我习惯在 src/api/request.ts 里封装一个基础请求函数统一处理 baseURL、超时和错误提示。下面是开发环境配合 Vite proxy 的写法// vite.config.ts import { defineConfig } from vite import react from vitejs/plugin-react export default defineConfig({ plugins: [react()], server: { port: 5173, proxy: { /api: { target: http://localhost:8000, changeOrigin: true, }, }, }, })配置好 proxy 以后前端代码里所有 /api 开头的请求都会在开发服务器这一层被转发到后端。这意味着开发阶段你根本不需要处理 CORS因为浏览器看到的请求是同源的。这个方案比在 FastAPI 里配 CORSMiddleware 还要干净我强烈建议开发环境优先用 proxy。2.3 第一杯水让前后端真的通起来两端都跑起来之后先别急着写业务验证一下链路。后端访问 http://localhost:8000/docs你应该能看到 Swagger 文档前端访问 http://localhost:5173然后打开浏览器控制台执行 fetch(/api/health)能拿到 JSON 就说明整个链路通了。这个 health 接口写起来很简单app.get(/api/health) def health_check(): return {status: ok, service: fullstack-demo}别看这个接口只返回一个对象它的价值在联调阶段会体现得特别充分。每次前后端联调我先让前端同学调一下 health如果不通那就是环境层面的问题比如端口、代理、网络如果 health 通了但业务接口报错那问题范围就缩小到了业务代码。这套排查思路能帮你省下大量瞎猜的时间。3. 接口对接与状态管理前后端协作的核心环节3.1 接口契约先行用 OpenAPI 统一前后端认知前面提到 FastAPI 会自动生成 OpenAPI 文档但文档生成是结果契约先行才是关键。在实际项目里我习惯先写后端 schemas再写路由然后再交给前端对接。因为 Pydantic 模型本身就是契约前端可以拿着 /docs 上展示的字段列表直接定义 TypeScript 类型。两端各有一套自己的类型系统但描述的是同一份数据靠的就是这份契约。举个例子如果后端定义了这样的模型class TaskResponse(BaseModel): id: int title: str done: bool created_at: datetime前端对应的 TypeScript 类型会长这样interface Task { id: number title: string done: boolean created_at: string }字段名、类型一一对应前端才会少出后端返回的是驼峰前端用的是下划线之类的低级问题。这里要特别提醒接口字段命名在项目一开始就要定好中途改字段名是前后端同时改成本翻倍。我个人的习惯是后端坚持 snake_case因为 Python 风格如此前端则在下划线命名下老老实实照用不强行转换。3.2 前端请求层fetch 还是 axios很多新手会纠结前端到底用 fetch 还是 axios。我的建议很实际项目里没有统一封装历史的话直接用带封装的 fetch 就够了如果团队已经有 axios 的拦截器习惯那就继续用 axios。关键在于统一封装而不是工具本身。一个最简封装大概是这样的// src/api/request.ts const BASE_URL import.meta.env.VITE_API_BASE_URL ?? export async function requestT(path: string, options?: RequestInit): PromiseT { const res await fetch(${BASE_URL}${path}, { headers: { Content-Type: application/json }, ...options, }) if (!res.ok) { const msg await res.text() throw new Error(HTTP ${res.status}: ${msg}) } return res.json() as PromiseT }BASE_URL 用 import.meta.env 而不是 process.env这是 Vite 项目的环境变量写法后面部署到不同环境只需要在 .env 文件里改 VITE_API_BASE_URL 就行。把请求统一封装的另一个好处是出错时前端可以统一弹提示不用在十几个组件里各写各的错误处理。3.3 React 数据请求useEffect 的正确姿势React 拿到接口数据最基础的写法是 useEffect useState但很多人一上手就写出死循环const [tasks, setTasks] useStateTask[]([]) useEffect(() { fetchTasks().then(setTasks) }, []) // 依赖数组填空数组只请求一次只要记住 useEffect 的依赖数组决定副作用何时重新执行空数组表示只在组件挂载时执行一次如果忘了写依赖数组那么每次渲染都会触发请求再触发 setState再渲染直接死循环。这是一个前后端联调时出现频率非常高的诡异问题。如果项目里的跨组件共享状态开始变多我建议引入 zustand而不是一上来就上 Redux。zustand 的 API 极其精简不需要 Provider也不需要写 action/reducer 那套样板代码import { create } from zustand interface TaskStore { tasks: Task[] loading: boolean fetchTasks: () Promisevoid toggleTask: (id: number) Promisevoid } export const useTaskStore createTaskStore((set) ({ tasks: [], loading: false, fetchTasks: async () { set({ loading: true }) const tasks await requestTask[](/api/tasks) set({ tasks, loading: false }) }, toggleTask: async (id) { await request(/api/tasks/${id}, { method: PATCH }) set((state) ({ tasks: state.tasks.map((t) t.id id ? { ...t, done: !t.done } : t, ), })) }, }))组件里直接调用 useTaskStore() 取值、取方法就行了全局状态不用层层传 props。zustand 和 React 的并发渲染兼容性做得也很好规模不大的项目用它基本不会踩坑。4. 生产部署Nginx 反向代理与多环境配置4.1 前端构建与刷新就 404的源头前端开发完要部署第一步当然是构建npm run build构建产物在 dist 目录。但如果你直接把 dist 扔给 Nginx然后把 location / 指向它很快会发现一个问题打开首页没问题一旦访问 /tasks/123 这种前端路由的 URL刷新就变成 404。原因是前端路由是浏览器端用 History API 模拟出来的服务器上并不存在 /tasks/123 这个物理路径。Nginx 拿到这个请求去磁盘上找文件找不到就返回 404。解决方法是把未知路径全部重写到 index.html让前端路由自己接管location / { root /var/www/fullstack-demo/frontend/dist; try_files $uri $uri/ /index.html; }try_files 的意思是先找真实文件$uri 找不到就找目录目录也没有就直接给 index.html。这样浏览器刷新 /tasks/123 时会拿到 index.htmlReact Router 再从 URL 里解析出应该渲染哪个页面。这个配置几乎是所有 React/Vue SPA 部署的必备项忘了它上线第一天就会被测试提 bug。4.2 Nginx 反向代理把 /api 交给 FastAPI静态资源是前端的事接口还得到后端。生产环境下我一般不直接让浏览器访问后端的 8000 端口而是让所有请求都走 NginxNginx 把 /api 前缀的请求转发给本机 8000 端口上的 FastAPI 服务location /api/ { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }这里有个细节坑过很多人proxy_pass 指令如果 URL 末尾不带斜杠转发时会保留原始路径也就是 /api/tasks 会变成后端的 /api/tasks如果写成 proxy_pass http://127.0.0.1:8000/;Nginx 会把 /api 前缀去掉后端收到的就是 /tasks。两种写法各有用途但必须心里清楚你用的是哪一种否则会出现接口 404 但明明后端有这路由的灵异事件。我个人习惯保持后端路由统一带 /api 前缀所以 proxy_pass 不带斜杠。提示线上出现接口 404 时先检查 Nginx proxy_pass 末尾有没有斜杠。这个细节比业务代码更值得怀疑。整套 Nginx 配置合并起来一个生产服务器同时托管 React 静态文件和 FastAPI 接口浏览器永远只跟 Nginx 这个域名打交道也就彻底绕开了 CORS。CORS 依然是开发环境的问题生产环境用同源反向代理解决这是我强烈推荐的标准做法。4.3 后端进程管理与配置文件初始化FastAPI 生产环境不应该直接用 --reload 那个开发命令跑。--reload 会监听文件变化自动重启方便开发但不安全也不高效。生产我常用 gunicorn 来管理多个 worker 进程gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 127.0.0.1:8000-w 4 表示 4 个 worker 进程-k 指定 worker 类型必须用 UvicornWorker这样每个 worker 里跑的是 Uvicorn 的异步事件循环FastAPI 的 async 接口才有意义。再配合 systemd 托管保证服务器重启后服务自动拉起[Unit] DescriptionFastAPI fullstack-demo Afternetwork.target [Service] Userwww-data WorkingDirectory/var/www/fullstack-demo/backend EnvironmentFile/var/www/fullstack-demo/backend/.env ExecStart/usr/local/bin/gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 127.0.0.1:8000 Restartalways [Install] WantedBymulti-user.targetEnvironmentFile 这行很关键。FastAPI 项目里的数据库地址、密钥、环境标识这些配置我从来不会硬编码在代码里而是通过 pydantic-settings 从 .env 读取# app/config.py from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): app_name: str Fullstack Demo database_url: str secret_key: str model_config SettingsConfigDict(env_file.env, env_file_encodingutf-8) settings Settings()代码里通过 from app.config import settings 就能访问配置。好处很明显同一个代码库开发环境 .env 连本地数据库生产环境 .env 连线上数据库代码一行都不用改密钥这类敏感信息也不会不小心提交进 Git。第一次用 FastAPI 的读者经常问配置文件到底该怎么初始化pydantic-settings 就是最标准的答案。5. 常见问题与排查技巧实录既然标题里挂了实践两个字我就把这一年多实打实踩过的坑集中列出来。下面这些故障每一个我都在真实项目里见过甚至不止一次。5.1 CORS 配置的三种典型翻车现场第一种开发环境没用 Vite proxy前端 5173 直接 fetch 8000 端口报 CORS 错误。这不奇怪加 CORSMiddleware 即可。但很多人配了中间件还是报错一看代码allow_origins 写成了 [*] 且 allow_credentialsTrue浏览器直接拒绝带凭证的请求。因为规范不允许通配符配合凭据使用你必须把允许的来源域名一个一个列出来。注意当 allow_credentialsTrue 时allow_origins 坚决不要写成 [*]。如果来源域名不固定可以考虑 allow_origin_regex但千万别用 * 加 credentials 的组合。第二种预检请求失败。前端如果发的是带 Authorization 头或者 Content-Type: application/json 的请求浏览器会先发一个 OPTIONS 预检请求确认服务器允许后才发真实请求。FastAPI 的 CORSMiddleware 会统一处理 OPTIONS但如果你不小心在某个路由里自己定义了 OPTIONS 方法就可能覆盖掉中间件默认行为预检请求就会拿不到正确的响应头。第三种生产环境还在配 CORS。这属于对架构理解不深导致的。生产和开发用同一个后端服务前端却从不同的域名访问时生产环境的 CORS 配置需要改成正式的线上域名。如果用了 Nginx 反向代理 同源策略生产环境压根不需要 CORS 中间件绕过了整个问题。所以我建议开发环境用 proxy生产环境用反向代理CORS 在你的工程生命周期里只出现开发时配一次就够了。5.2 接口联调的经典误区404、422、500前后端联调时错误码其实已经帮你定位了大半问题。下面这个表格是我处理接口问题时的第一反应错误码出现位置最常见原因排查方向404前端 Network / 后端访问日志路径不匹配、proxy 去掉了前缀对比 OpenAPI 路径与请求 URL检查 Nginx proxy_pass 末尾斜杠422FastAPI 响应请求体字段缺失或类型错误读取响应 details按提示修正 TypeScript 类型或请求参数500后端日志业务逻辑异常、数据库错误打开 uvicorn/gunicorn 日志定位 traceback404 最常见的原因是路径不匹配。你写的是 /api/tasks但前端请求了 /tasks或者 Nginx 的 proxy_pass 把前缀剥掉了。排查方法很直接打开浏览器 DevTools 看 Network 面板找到请求的完整 URL再回到 FastAPI 的 OpenAPI 文档里对比路径。Vite proxy 配置里如果 target 写错端口也会 404这时候看 Network 里请求是不是停在 5173 上没转发出去。422 是 FastAPI 特有的一类错误表示请求体校验没通过。字段拼错、类型传错、缺了必填字段都会触发 422。FastAPI 返回的错误详情会具体到哪个字段、什么原因前端拿这个信息改起来非常快。我自己调试时返回到 422 反而比 200 更高兴因为这说明后端逻辑根本没往下走错误原因已经明明白白摆出来了。500 就是后端业务出问题了。一定要打开后端日志看栈信息而不是盯着前端报错猜。生产环境我会把日志输出到文件配合 systemd journalctl -u fullstack-demo -f 实时跟踪。5.3 React 前端两个高频问题状态更新和 key第一个是 useEffect 的依赖陷阱。前面提过空依赖数组只请求一次但如果你在 effect 里读取了某个 props 或 state却又不在依赖数组里声明拿到的是过期值声明了吧又可能因为引用类型每次渲染都变化而频繁触发请求。我的经验是能用 zustand 或 React Query 管理的异步状态就别手动写在 useEffect 里。React Query 把请求的 loading、error、缓存、重试都封装好了写起来反而更省心。第二个是列表渲染的 key。很多人图省事key 用数组下标 index。如果列表内容固定倒还好一旦有增删或排序React 会复用错误的 DOM 节点出现数据显示错乱。用后端返回的唯一 id 做 key 是基本纪律这条规矩在团队 code review 里我都会强制要求。5.4 部署阶段最容易忽略的三个细节一是 EnvironmentFile 没配。systemd 启动的后端进程读不到 .env应用拿不到数据库地址直接启动失败。这个坑非常隐蔽因为本地 uv run 一切正常一上 systemd 就崩十有八九是环境变量问题。二是 SPA 刷新 404。前面 Nginx 那段已经给了 try_files 配置这里再强调一遍你没有配前端路由刷新必 404。上线前一定要实际刷新几个带路径的页面而不是只在首页点来点去。三是静态资源缓存策略。dist 里的 JS/CSS 文件名都带 hash可以放心长缓存但 index.html 不能缓存太久否则发版后用户拿到的还是旧页面。我一般给 index.html 配 no-cache给带 hash 的资源配 30 天缓存这样既能保证更新及时又能利用浏览器缓存减少流量。最后再补一个我自己坚持的习惯每次前后端联调前先确认 health 接口通不通再谈业务。很多团队把大量时间浪费在业务接口报错的排查上最后发现是环境没起来、代理没配好、数据库没连上。把这条检查链路固定下来以后我这边接口联调的平均时间缩短了一大半。FastAPI React 这套组合真正的优势不在于某个单一技术有多炫而在于前后端契约清楚、链路透明、出问题能快速定位。这套工程实践值得你在一开始就认真搭好。