Gin 不该直接提供静态资源，因其会阻塞协程、触发冗余中间件、缺乏缓存控制且易暴露路径；生产环境必须由 Nginx 托管静态文件并反向代理 API 请求，实现动静分离。
静态资源不该由 Gin 服务直接提供——它会挤占协程、干扰中间件链、拖慢 API 响应，还容易暴露敏感路径。生产环境必须分离。
为什么不能用 router.Static() 托管前端资源
很多人图省事在 Gin 路由里加一句 router.Static("/assets", "./dist/assets")，但这是开发阶段的权宜之计。问题在于：
- Gin 的每个静态文件请求仍会走完整中间件链（日志、鉴权、CORS），哪怕你没配任何中间件，
gin.Default()默认带的recovery和logger也会执行 - 静态文件读取是同步阻塞 I/O，没有利用 Go 协程优势；高并发下大量
os.Open+io.Copy会抬高 P99 延迟 -
Static不支持缓存头精细化控制（如immutable、基于 ETag 的协商缓存），也难对接 CDN 回源策略 - 一旦前端构建产物路径变更（比如加了 hash 后缀），Gin 不会自动刷新
fs.Stat缓存，可能返回 404 或旧文件
真正可行的分离方案：Nginx 反向代理 + Gin 纯 API 模式
把 Gin 降级为纯粹的后端 API 服务，所有 /api/、/health 等路径交由它处理；其余路径（/、/login、/assets/）全部由 Nginx 托管。典型配置片段：
server {
listen 80;
root /var/www/my-app/dist;
index index.html;
<pre class='brush:php;toolbar:false;'># 所有以 /api/ 开头的请求转发给 Gin
location ^~ /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# 健康检查不走前端目录，直通 Gin
location = /health {
proxy_pass http://127.0.0.1:8080;
}
# SPA 路由 fallback：除 API 和健康检查外，其他路径都返回 index.html
location / {
try_files $uri $uri/ /index.html;
}}
关键点：
- 确保 Gin 启动时不监听 80 端口，只绑
:8080（或内网端口），避免端口冲突 -
try_files必须放在location /下，且顺序不能颠倒；否则 Vue/React 的前端路由会 404 - 不要在 Gin 里再注册
router.NoRoute()处理前端 fallback —— 那是 Nginx 的事
Docker 容器化时的路径与挂载陷阱
本地跑得通，一进 Docker 就 404？大概率是三类路径没对齐：
- Nginx 容器里的
root路径（如/usr/share/nginx/html）和宿主机映射的前端构建产物目录不一致 - Gin 容器没做健康检查探针，K8s 在 Nginx 尝试反代时发现后端不可达，直接返回 502
- 前端代码里写的 API 基地址是
/api/，但 Nginx 没把/api/重写干净，导致 Gin 收到的c.Request.URL.Path是/api/v1/users—— 这本身没问题；但如果 Gin 路由定义成了router.GET("/v1/users")，就匹配不上了
验证方法：进 Nginx 容器执行 curl -v http://localhost:8080/api/health，看是否能拿到 Gin 的 {"status":"ok"}；再从宿主机 curl -v http://localhost/health，确认 Nginx 是否透传成功。
CI/CD 流水线里如何保证前后端部署原子性
前端更新 HTML、JS，后端同时升级 API 接口，两者版本错配会导致白屏或 500。解决思路不是“一起发”，而是“分层解耦”：
- 前端构建产物打唯一 tag（如 Git SHA），Nginx 配置中
root指向带版本号的子目录：/var/www/my-app/dist/abc123 - Gin 服务通过
APP_VERSION环境变量注入当前版本，并在/health接口返回该字段，供 Nginx 日志或监控采集 - 禁止在前端 JS 中硬编码后端域名；统一用相对路径（
/api/v1/login），靠 Nginx 的location ^~ /api/规则兜底 - 灰度发布时，先切 Nginx 的 upstream 到新 Gin 实例，等
/health返回稳定后再更新前端 root 目录 —— 顺序不能反
最易被忽略的一点：Nginx reload 不是原子操作，nginx -s reload 瞬间会有少量请求落在旧 worker 进程上。如果前后端版本强依赖，就得在 Gin 层加兼容逻辑，比如对已废弃的 /v1/xxx 接口返回 301 跳转到新路径，而不是直接 404。
