知识点深化 · 项目脚手架

全栈项目脚手架：前端(React/Vue)+后端(FastAPI/Express)+DB 一键起

从零搭一个前后端+数据库项目，要配工具链、跨域、代理、环境变量、数据库连接……重复且易错。脚手架就是把这些约定固化成一个模板：clone 下来，改个名，就能开干。这一页带你搭一个 React + FastAPI + Postgres 的一键启动骨架。

① 小白第一课怎么学（4 步走，约 90 分钟）

先理解前后端为什么要分目录、怎么通信，再动手搭。

1理解结构（15 分钟）
读②③：前端跑浏览器、后端跑服务器、DB 存数据，三者靠 HTTP。

2起后端骨架（20 分钟）
读④：FastAPI 一个文件起服务，连 Postgres。

3起前端骨架+打通（30 分钟）
跟着⑤用 Vite 起 React，配代理调后端。

4排错+刷题（25 分钟）
读⑥跨域/端口坑，做⑦⑩。

本课小目标学完你要能：① 说清前后端如何通信；② 用 FastAPI 起一个返回 JSON 的接口；③ 配 Vite 代理解决开发跨域；④ 用 compose 一键起前后端+DB。

② 一图看懂：全栈骨架结构

读法：前端在浏览器发 HTTP 请求 → 后端在服务器处理 → 读写数据库 → 返回 JSON。三部分各自独立，用 compose 拉起。

③ 本质直觉：三个进程，靠 HTTP 对话

全栈项目本质是三个独立进程：前端（跑在用户浏览器，React/Vue）、后端（跑在服务器，FastAPI/Express，提供 API）、数据库（存数据）。

它们怎么连？前端不能直连数据库（密钥会泄露）。正确链路：前端 fetch('/api/xxx') → 后端 → SQL 查数据库 → 返回 JSON → 前端渲染。

开发时的跨域问题：前端跑在 localhost:5173，后端跑在 localhost:8000，浏览器认为这是两个不同源，会拦截。解决办法：开发时用 Vite 代理，让前端请求"看起来"同源。

为什么用脚手架：每次新业务都要重配工具链（lint、格式化、环境变量、CORS、DB 连接、热重载），脚手架把这些默认项配好，clone 即用。

目录约定常见结构：web/（前端）、api/（后端）、docker-compose.yml（根目录编排）。前后端各自有 package.json/requirements.txt，互不干扰。

④ 完整体系：后端、前端、代理、compose

后端骨架（api/main.py，FastAPI）

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],  # 前端地址
    allow_methods=["*"], allow_headers=["*"],
)

@app.get("/api/health")
def health():
    return {"status": "ok"}

@app.get("/api/items")
def list_items():
    return [{"id": 1, "name": "笔记本"}]

# 运行：uvicorn main:app --reload --port 8000

前端骨架（Vite + React）

npm create vite@latest web -- --template react
cd web && npm install

vite.config.ts 配代理（开发期解决跨域）：

export default {
  server: {
    proxy: {
      '/api': { target: 'http://localhost:8000', changeOrigin: true }
    }
  }
}

前端组件里直接 fetch('/api/items')——因为代理把 /api 转发到后端，浏览器看到的是同源。

一键 compose（根目录 docker-compose.yml）

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: dev
    volumes: ["dbdata:/var/lib/postgresql/data"]
  api:
    build: ./api
    ports: ["8000:8000"]
    environment:
      DATABASE_URL: postgresql://postgres:dev@db:5432/postgres
    depends_on: [db]
  web:
    build: ./web
    ports: ["5173:80"]   # 前端构建后由 nginx 提供静态文件
volumes:
  dbdata:

关键约定对照

关注点	做法
跨域	开发用 Vite 代理；生产后端配 CORS 或同域部署
环境变量	后端读 .env（DATABASE_URL），不硬编码
热重载	后端 --reload，前端 Vite HMR
前端构建	npm run build 出静态文件，生产由 nginx 托管

⑤ 用法场景与典型例题

例1（打通前后端）前端 fetch /api/items，浏览器控制台报 CORS 错，怎么办？

开发期最常见的跨域。

① 原因：前端 5173 直连后端 8000，浏览器跨域拦截。
② 开发方案：配 Vite 代理，把 /api 转发到 localhost:8000，前端就请求同源 /api。
③ 生产方案：后端加 CORS 中间件白名单，或把前后端放同一域名下。
答案：别让前端直接跨域调后端，用代理或 CORS。

例2（环境变量）数据库密码能写死在代码里吗？

配置和代码要分离。

① 不能写死，会进 git、泄露。
② 用环境变量：本地 .env 文件（加 .gitignore），代码里 os.getenv("DATABASE_URL")。
③ 生产由 compose/K8s 的 environment 注入。
答案：配置走环境变量，.env 不提交。

例3（一键起）新人 clone 项目后，最理想的启动步骤是？

脚手架的价值就是少踩坑。

① docker compose up -d 一条命令起 db+api+web。
② 访问 localhost:5173。
③ 本地开发则分别起后端 uvicorn --reload 和前端 npm run dev。
答案：好的脚手架新人 clone 后最多一条命令 + npm install 就能跑。

前后端分离 vs 一体分离：前端独立部署、能换技术栈；一体（如模板渲染）：简单但耦合。脚手架默认走分离。

⑥ 高频错误诊断（4 条）

错误 1：CORS 跨域报错前端直连后端不同源。开发用 Vite 代理，生产配 CORS 白名单或同域部署。别在前端绕过。

错误 2：环境变量在容器里读不到本地 .env 没挂进容器，或变量名拼错。compose 里显式 environment 传入，或用 env_file。

错误 3：前端 build 后空白页/404前端路由用 history 模式，nginx 没配 fallback 到 index.html；或静态资源路径用了绝对路径 /assets 在子路径下 404。

错误 4：前端直接连数据库把数据库密码写进前端代码 = 任何人 F12 都能看到。前端永远只能调后端 API。

⑦ 考点真题演练（4 题）

考点分布

考法	出题形式	应对
架构	前后端如何通信	HTTP/JSON，前端不直连DB
跨域	CORS 怎么解	代理/CORS
配置	密钥放哪	环境变量
启动	一键起怎么做	compose

真题基础1. 前端应该如何获取数据库里的数据？

真题中档2. 开发时前端(5173)调后端(8000)报 CORS，推荐做法？

真题中档3. 数据库密码应该放哪？

真题拔高4. 好的脚手架对新人最大的价值是？

⑧ 必背命令/知识点卡

三层：web 前端 / api 后端 / db 数据库 目录分开
通信：前端 fetch /api → 后端 → DB JSON
起后端：uvicorn main:app --reload --port 8000 FastAPI
起前端：npm create vite → npm run dev 5173 端口
跨域：Vite proxy /api → 后端 开发期
配置：环境变量 .env，不进 git 密钥安全
一键起：docker compose up -d 三部分同起

⑨ 应用输出：从零搭一个全栈待办应用

场景：React 前端 + FastAPI 后端 + Postgres，能增删待办

① 建目录：todo-app/{web,api,docker-compose.yml}。

② 后端：FastAPI 写 GET/POST /api/todos，连 Postgres，加 CORS。

③ 前端：Vite+React，列表展示 todos，加输入框调 POST /api/todos。

④ 配代理：vite.config 把 /api 转发 8000。

⑤ DB：compose 起 Postgres，后端 DATABASE_URL 指向 db 服务。

⑥ 起：docker compose up -d，访问 5173，添加待办，刷新还在（数据落库）。

口述搭架思路"前端只调 /api，后端查库返回 JSON，配置走环境变量，跨域靠代理，最后用 compose 一键把三部分拉起来。"

⑩ 分层练习 15 题（基础 5 + 中档 5 + 拔高 5）

▍基础 5 题

基础1前端跑在什么环境？后端呢？

前端跑用户浏览器；后端跑服务器。

基础2前后端用什么格式通信？

HTTP 请求，交换 JSON。

基础3FastAPI 开发热重载启动命令？

uvicorn main:app --reload --port 8000。

基础4前端脚手架常用什么构建工具？

Vite（npm create vite）。

基础5.env 文件要不要提交 git？

不要，加进 .gitignore；只提交 .env.example。

▍中档 5 题

中档6为什么前端不能直连数据库？

数据库凭据会暴露在浏览器，且没有业务校验层，不安全。

中档7Vite proxy 的作用？

把前端 /api 请求转发到后端，开发期绕过浏览器跨域限制。

中档8生产环境前端 build 出的静态文件由谁托管？

通常由 nginx 或后端静态托管，再通过同一域名访问。

中档9compose 里后端连数据库用什么主机名？

用数据库服务名（如 db），compose 内置 DNS 解析。

中档10前后端分离相对模板渲染的好处？

前后端可独立开发/部署、可换技术栈、利于多端复用同一 API。

▍拔高 5 题

拔高11前端 history 路由部署后刷新 404，为什么？

nginx 找不到对应后端文件。要配 try_files 全部回退到 index.html，交给前端路由处理。

拔高12怎么让本地后端改代码自动重启？

uvicorn 加 --reload；前端 Vite 自带 HMR。容器里要挂卷并开 reload。

拔高13多环境（dev/prod）配置怎么管？

.env.dev / .env.prod，启动时加载对应文件；代码只读环境变量，不写死。

拔高14前端生产调后端 API 还会跨域吗？

若前后端同域名（/api 反代到后端）就不跨域；若分开域名则后端配 CORS 白名单。

拔高15为什么脚手架要锁版本（lock 文件）？

保证不同人 install 出的依赖一致，避免"我这能跑"；package-lock/requirements 锁版提交。

⑪ 记忆口诀 + 7 天复习计划

三句口诀 ① 前端浏览器、后端服务器、DB 存数据，三者 HTTP 对话。
② 前端不碰库，配置走环境变量，跨域用代理。
③ 脚手架 clone 即跑，compose 一键起三件套。

天	任务	自检
第 1 天	读②③，起一个 FastAPI health 接口	返回 JSON
第 2 天	背知识点卡 + 做基础 1-5	基础全对
第 3 天	起 Vite 前端，配代理打通 /api	页面调通接口
第 4 天	做中档 6-10，加 Postgres	数据落库
第 5 天	做拔高 11-15 + 真题 4 题	会排跨域404
第 6-7 天	compose 一键起，口述三层架构	不看资料全默对

← 返回 FDE 培养总览