平台工程

本地部署 FastAPI 静态站到 3000 端口 · 复盘

入档:2026-07-17 来源:本地运行 taowhale 站点，目标是通过 localhost:3000 访问 状态:已完成本地部署验证，HTTP 200

一句话总结

要让一个基于 FastAPI 的静态站在本地通过 localhost:3000 访问，关键不是改前端文件，而是把后端启动脚本改为监听目标端口，并确认静态文件入口和依赖都能正常加载。

现象

• 项目本身是 FastAPI 后端 + 静态页面入口。
• 现有本地启动脚本默认监听 8000。
• 目标是通过 3000 端口访问站点。
• 本地启动后，直接请求 http://127.0.0.1:3000/ 返回 200，说明部署成功。

根因

1. 本地启动脚本中端口写死为 8000。
2. 运行入口使用 uvicorn.run(..., port=8000)，因此默认不满足目标端口要求。
3. 站点是 SPA 风格，后端会把未命中的路径回退到静态入口 index.html，所以只要后端启动成功、静态文件存在即可通过浏览器访问。

处理步骤

1. 读取项目启动入口与依赖文件。
2. 确认后端是 FastAPI，静态资源目录为 static/。
3. 将本地启动脚本改为支持环境变量 PORT，默认值为 3000。
4. 安装必要依赖：fastapi 与 uvicorn。
5. 启动服务并验证 http://127.0.0.1:3000/ 返回页面内容。

关键修复

在本地启动脚本中加入端口变量读取：

port = int(os.environ.get("PORT", "3000"))
uvicorn.run("main:app", host="0.0.0.0", port=port, log_level="warning")

这样可同时兼容：

• 默认 3000 端口
• 通过环境变量覆写端口
• 便于后续部署到不同环境

验证结论

已实际执行请求：

Invoke-WebRequest -UseBasicParsing http://127.0.0.1:3000/ -TimeoutSec 10

结果为 StatusCode: 200，说明站点已能在本地通过 localhost:3000 正常打开。

可复用经验

1. 先确认项目本身的启动方式，而不是直接猜前端端口。
2. 对于 FastAPI + 静态入口的项目，后端启动成功通常就能把 SPA 页面打通。
3. 端口配置最好做成环境变量驱动，避免以后部署时再次踩硬编码。
4. 对于“看起来像前端问题”的现象，优先检查后端服务是否真的在正确端口启动。

关联文档

• 双部署目标的base路径陷阱_根路径拼出双斜杠_v1 —— 说明环境变量与路径拼接在部署场景下的坑
• 内测反馈渠道上线_匿名兜底与422探针验证_v1 —— 同款验证链路(本地起服务+HTTP 实测);其临时起服时的 503 也是静态目录相对 cwd 解析的同类路径坑
• 09_平台工程索引 —— 平台工程相关复盘入口