本文详解 go web 服务通过 nginx 反向代理部署时，静态文件（css/js/图片）无法加载、路由 404 的根本原因与完整解决方案，涵盖配置分离、路径匹配、头信息设置及生产级最佳实践。
本文详解 go web 服务通过 nginx 反向代理部署时，静态文件（css/js/图片）无法加载、路由 404 的根本原因与完整解决方案，涵盖配置分离、路径匹配、头信息设置及生产级最佳实践。
你在 Ubuntu Server 上首次部署 Go 应用时遇到的「HTML 能加载但 CSS/JS/图片全 404」问题，并非 Go 代码缺陷，而是 Nginx 配置逻辑冲突所致。你当前配置中 location / { ... try_files ... proxy_pass ... } 将静态文件查找与反向代理混在同一块内，导致 Nginx 在尝试 try_files $uri $uri/ =404 失败后，仍强行执行 proxy_pass——而你的 Go 应用（如使用 net/http 或 Gin 默认路由）通常并未注册 /css/app.css 等静态路径，自然返回 404。
✅ 正确解法是：*让 Nginx 自己处理静态资源，仅将动态请求（如 `/api/` 或未命中文件的路径）交由 Go 服务**。这既提升性能（Nginx 静态服务速度远超 Go），又避免路由错乱。
一、推荐配置：静态资源由 Nginx 托管，动态请求交由 Go
假设你的 Go 应用监听 127.0.0.1:8001，所有前端构建产物（dist/ 目录）已上传至 /var/www/myapp（结构如 dist/css/, dist/js/, dist/index.html）：
server {
listen 80;
server_name example.com;
# ✅ 静态资源根目录（指向 dist 的父级！）
root /var/www/myapp/dist;
index index.html;
# ✅ 优先匹配静态文件：CSS/JS/IMG/字体等
location ~ ^/(css|js|images|img|fonts|favicon\.ico|manifest\.json|robots\.txt)/ {
expires 1h;
add_header Cache-Control "public, immutable";
# Nginx 自动拼接路径，如请求 /js/app.js → 查找 /var/www/myapp/dist/js/app.js
}
# ✅ SPA 入口：所有未匹配静态文件的请求，均返回 index.html（支持前端路由）
location / {
try_files $uri $uri/ /index.html;
}
# ✅ 动态 API 请求：明确以 /api/ 开头的路径，直接代理到 Go 后端
location /api/ {
proxy_pass http://127.0.0.1:8001/;
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_set_header X-Forwarded-Proto $scheme;
# ⚠️ 关键：尾部斜杠 / 不可省略！确保 /api/users → 后端接收为 /users
}
}
? 为什么你的原配置失败？
try_files $uri $uri/ =404;在location /块中会先检查文件是否存在；若不存在（如/css/main.css），立即返回 404，根本不会执行后续的proxy_pass—— 这与你期望的「找不到才转发」逻辑相悖。而@proxy命名位置（named location）方案虽可行，但属于「兜底转发」，不如显式分离静态与动态路径清晰、高效且符合生产规范。
二、Go 服务必须配合的关键调整
-
监听地址必须为
127.0.0.1（非0.0.0.0）// ✅ 正确：仅允许本地 Nginx 访问 http.ListenAndServe("127.0.0.1:8001", handler) // ❌ 危险：暴露公网，绕过 Nginx 安全层 // http.ListenAndServe(":8001", handler) -
API 路由前缀需与 Nginx 一致
若 Nginx 中location /api/代理到 Go，则 Go 内部应注册/users而非/api/users：r := gin.Default() r.GET("/users", getUser) // 接收的是 /api/users → Nginx 剥离 /api/ 后传递 /users -
正确读取真实客户端信息
不要再用r.RemoteAddr或r.TLS判断 HTTPS：// ✅ 真实 IP（注意：X-Forwarded-For 可伪造，生产环境需配置 trusted proxies） clientIP := r.Header.Get("X-Real-IP") if clientIP == "" { clientIP = r.Header.Get("X-Forwarded-For") } // ✅ 是否 HTTPS isHTTPS := r.Header.Get("X-Forwarded-Proto") == "https"
三、验证与调试清单
| 检查项 | 命令/方法 | 预期结果 |
|---|---|---|
| ✅ Nginx 配置语法 | sudo nginx -t |
syntax is ok, test is successful
|
| ✅ Go 服务绑定地址 | sudo ss -tln \| grep :8001 |
输出含 127.0.0.1:8001，不含 *:8001
|
| ✅ 静态文件路径 | curl -I http://localhost/css/app.css |
HTTP/1.1 200 OK + Content-Type: text/css
|
| ✅ API 代理通路 | curl http://localhost/api/users |
返回 Go 服务的 JSON 数据 |
| ✅ HTTPS 头透传 | 在 Go 中打印 r.Header.Get("X-Forwarded-Proto")
|
http（HTTP 访问）或 https（Nginx 终止 SSL 后） |
? 进阶提示：若使用 Vue/React 等 SPA，
location / { try_files $uri $uri/ /index.html; }是必需的，否则前端路由（如/dashboard）会触发 Nginx 404。同时，务必在 Go 服务中禁用 HTML5 History fallback（如 Gin 的r.NoRoute(...)），避免与 Nginx 冲突。
遵循以上配置，你的 Go 应用将获得生产级的静态资源服务能力、安全的网络边界、正确的客户端信息识别，以及清晰可维护的架构分层——这才是云原生时代 Go Web 部署的起点。
