解决换网络导致 Nuxt 白屏
2026-11-21 19:25:55

博客换了个 WiFi,首页突然一片空白,F12 里请求全是红的。

这已经是第三次了——前两次改个 IP 重建容器就完事,这次烦了,直接根治。

正文

博客是 docker compose 部署的,nginx 一个端口同时服务博客前端(Nuxt3 SSR)和后端 API。

换了网络之后,会出现如下的问题:

  • 页面能打开,但文章列表空了(服务端渲染拿不到数据)
  • F12 里 captchaImage、文章列表这些请求全是红色,点开只有一句 Provisional headers are shown,连响应头都没有

“Provisional headers” 的意思不是后端报错,而是这个请求压根没成功过:连不上、被拦截、CORS 失败时都会出现这句,浏览器手里只有一份”打算发什么”的草稿。本例里是 TCP 连接都没握上。

排查

拿 curl 直接打 API:

1
2
curl http://192.168.11.130:8888/api/captchaImage?username=test
# HTTP 000,8 秒超时——这个 IP 根本不通

ipconfig 一看,本机 IP 早就不是 192.168.11.130 了。

原因一句话:compose 环境变量里把 API 地址写死成了本机局域网 IP,而 DHCP 换个网络就换一个 IP。

为什么当初要写 IP

博客前端是 Nuxt3 SSR,apiBase 这个地址两个上下文都要用:

  • 浏览器:发接口请求、拼封面图地址
  • SSR 容器内:服务端 useFetch 也要请求后端

容器里的 localhost 指向容器自己,不能用;所以就写了本机局域网 IP,让两边都够得着。

能跑,但埋了雷:这个 IP 是 DHCP 动态分的,换 WiFi 就变,一变两边同时挂。

根治思路

问题的本质:一个 apiBase 同时伺候”浏览器”和”SSR”两个上下文,只能写一个两边都够得着的地址,于是只能选 IP,于是只能跟着网络走。

拆开就好了:

  • 浏览器改成同源相对路径:请求直接打 nginx 同源的 /api,由 nginx 转发给后端,跟 IP、域名、网络都无关
  • SSR 容器内也发相对路径,在 Nuxt(Nitro)里加一个代理路由,把这些相对请求转发到 docker 内部网络的 server:8080——容器之间用服务名互访,永远有效
1
2
浏览器 --/api--> blog-nginx --proxy--> server:8080        (同源,零 IP)
SSR $fetch('/api/..') --> Nitro 代理路由 --> server:8080 (docker 内部 DNS)

具体改动

两个 Nitro 代理路由

apps/client/server/routes/api/[...].ts:

1
2
3
4
export default defineEventHandler((event) => {
const target = useRuntimeConfig(event).apiProxyTarget as string
return proxyRequest(event, target + (event.node.req.url || ''))
})

profile/[...].ts 同理(封面、头像这类图片资源)。生产环境依赖 nginx 已把 /profile 反代到后端,dev 没有 nginx 时由这条路由兜住。

[...].ts 这种 catch-all 写法需要 Nuxt 3.8+ / Nitro 2,更老的版本要写成 [...slug].ts。

proxyRequest 是 h3 的工具,Nitro 会自动导入,方法、请求头、请求体、状态码全部原样透传,不用自己搬。

nuxt.config 的 runtimeConfig

1
2
3
4
5
6
7
8
runtimeConfig: {
// /api、/profile 代理路由的转发目标(dev 默认打本地后端)
apiProxyTarget: 'http://localhost:8080',
public: {
// 默认空串走同源相对路径
apiBase: ''
}
}

不用写 process.env:

Nuxt 3 会在运行时用 NUXT_API_PROXY_TARGET、NUXT_PUBLIC_API_BASE 自动覆盖同名 key(key 得先在 nuxt.config 里声明)。

写成 process.env 反而是构建期取值,镜像 build 时没注入变量就会把默认值烧进产物,排查起来更绕。

docker compose 给 client 注入转发目标

1
2
3
environment:
NUXT_API_PROXY_TARGET: ${NUXT_API_PROXY_TARGET:-http://server:8080}
NUXT_PUBLIC_API_BASE: ${NUXT_PUBLIC_API_BASE:-}

这里假设 client 和 server 在同一个 compose 网络,服务名 server、端口 8080,换成别的项目要按实际改。

apiBase 置空之后,所有拼 URL 的地方(config.public.apiBase + '/api/xxx')天然变成相对路径,二十多个调用点一行没改。

成立的前提是拼法都带前导斜杠,且没有拿 apiBase 去拼分享链接、RSS 这类绝对地址——改之前值得全量搜一遍 apiBase 确认。

特殊部署(没有 nginx 反代)依然可以用 NUXT_PUBLIC_API_BASE 覆盖回绝对地址,留了后路。

另外注意:改完后浏览器走 nginx,SSR 则直连 server:8080,绕过了 nginx。

本例 nginx 只是纯反代,所以没差别;如果 nginx 上还有鉴权、限流、超时、路径重写之类的逻辑,SSR 和浏览器的行为就不一致了。

验证

  • 首页 SSR 渲染出文章列表,封面 src 变成 /profile/... 相对路径且加载 200
  • 同源 /api 经 nginx 返回 200
  • 容器内直探 Nitro 代理路由:GET 拿到文章数据;POST /api/login 透传了后端 400 参数校验响应——方法、请求体、状态码都通
  • nuxt typecheck 全绿

可以带走的

  • 换网络、换部署机、换域名,零配置,再也不用”改 .env → 重建 client 容器 → 重启 nginx”老三样
  • 浏览器请求全部同源,跨域(CORS)这类问题不会再出现(CORS 本来也只约束浏览器,SSR 的 fetch 不受影响),连带 “Provisional headers are shown” 这类悬案也不会再有
  • 凡是”容器里要访问、浏览器里也要访问”的地址,优先考虑同源 + 反向代理,把环境差异交给服务端配置(docker 内部 DNS)去消化,而不是塞进前端的环境变量里

结语

写死 IP 的方案”能跑”,但它把部署环境和网络环境焊死了。

apiBase 这个变量看着无害,实际上每次换网络都在提醒你:环境变量里的每一个绝对地址,都是一个未来会失效的假设。

前两次我选择了最快路径,第三次才付出真正的一次性成本。

这种”每次都能绕过去”的问题,绕第三次的时候就该动手根治了——修一次要用一辈子的东西,值得花一下午。

参考链接

本篇正文由 ZCode 的 AI 助手(智谱 GLM)协助整理撰写:智谱开放平台