跳到正文

我所理解的 Nuxt 最佳实践(4):部署前检查资源与服务端产物

我所理解的 Nuxt 最佳实践

  1. 沿着路由组织页面和自动导入
  2. 按请求隔离状态,让客户端接得住首屏
  3. 用插件依赖声明启动顺序
  4. 部署前检查资源与服务端产物(当前)

图片原地址能打开,经过图片优化却返回 404。服务端代码也可能通过构建,直到 Node 启动才发现找不到依赖子路径。遇到这两种问题,我会沿着部署后的入口查,先找谁在解析这个地址,再看它拿得到哪些文件。

图片要对上优化器能读取的图源

把 assets 里的图片交给 Vite import,拿到的可能是构建后带 hash 的 /_nuxt/ 资源 URL。普通 <img> 可以直接请求这个地址。换成 <NuxtImg> 后,浏览器访问的是 provider 改写过的地址,默认本地图源的 IPX 还要按自己的来源目录去找源图。原图的 URL 可访问,只验证了 Vite 的资源输出。

小图标和组件私有装饰图可以继续交给 Vite 和普通 <img>。需要响应式尺寸或格式优化时,先选 provider,再确认它能读取 public/ 下的原图或允许的远程图源。验证时从浏览器网络面板分别检查原图、优化请求和最终内容类型。一次 assets 图源错配的完整过程见《Nuxt Image 本地图片 404 的排查》。

先确定线上会执行哪份产物

静态生成输出的公开文件可以独立托管。项目如果还有 API,就要确认它另由哪个服务端入口执行。例如搜索应用把 Nuxt 静态前端和 ESA 边缘函数分别打包,本地 Nuxt 路由和远端 fetch 入口共用搜索实现。发布时,公开目录只放浏览器需要的文件,边缘函数与它的凭据有单独的部署边界。见《从搜索动效原型到 Nuxt 应用》和 Nuxt 部署文档。

如果部署的是 Nitro 的 Node 服务,就从 .output/server 查实际保留的 import。工作区的类型声明、开发环境中的依赖路径和 Node 按 package.json 的 exports 解析子路径,分别提供不同的证据。鉴权 wrapper 升级后仍引用旧子路径,就可能出现类型检查通过、部署入口无法加载的情况。见《NextAuth 安全升级撞上 sidebase 旧入口》。

构建、解析和启动分别验

构建后可以从产物提取裸包 import,在目标 Node 环境先检查典型的入口解析失败,并报告实际 specifier 和引用文件。import.meta.resolve() 得到的是 URL。实际加载还可能遇到文件缺失或初始化错误,所以需要在隔离环境启动服务、请求关键路由,并确认进程能退出。边缘函数则需要按目标宿主单独验。脚本范围和可复制实现见《给 Nitro server bundle 补运行时 import 检查》。

构建 Nitro 服务端产物之后,用目标 Node 解析 import,再实际启动服务并请求关键路由

部署配置同样要分层。构建时选哪个环境文件,运行时通过什么入口注入配置,浏览器可以拿到哪些字段,是三个独立的问题。已有《环境变量怎么管理》里的 Nuxt 4 小节专门对照了这几层。