Vite manifest.json 产物清单与资源预加载

把 Vite 前端交给传统后端渲染时，真正需要解决的不是“怎么拼一个 JS 文件名”，而是源码入口如何对应到带哈希的 JS、CSS 和依赖资源。开启 build.manifest 后，Vite 会生成 .vite/manifest.json，后端以源码入口为 key 读取 file、css、imports 等字段，再输出稳定的资源标签。资源预加载也应该从这份依赖关系出发，只给当前页面很快会用到的模块添加 modulepreload。

Vite manifest.json 解决的是哪一层路径问题

生产构建通常会把 main.js 变成类似 assets/main-BRBmoGS9.js 的文件。文件名中的哈希用于缓存，但也意味着后端不能继续写死源码文件名。Vite manifest 的职责就是保存这层映射：入口 key 仍接近源码路径，file 指向最终 JS，css 保存关联样式，imports 指向其他 manifest key。

它和 SSR manifest 不是一回事。普通后端模板需要的是构建产物映射；只有 SSR 场景还要根据服务端渲染结果判断样式和预加载指令时，才另看 build.ssrManifest。

配置 build.manifest 并读取入口记录

默认情况下不会生成 manifest。对需要后端模板的项目，可以在 Vite 配置中开启它；写成 true 时，文件位于输出目录下的 .vite/manifest.json。如果后端更容易读取固定文件名，也可以把 manifest 写成相对于 build.outDir 的字符串。

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    // 让后端用源码入口找到带哈希的构建产物
    manifest: true,
    // 公开资源统一放到这个输出目录
    outDir: 'dist'
  }
})

读取时不要按随机生成的文件名查找，而要固定入口 key。以下示例只取当前页面的入口记录，并在缺失时立即报错；真实项目中可以把这个函数放在模板渲染层的资源加载器里。

import { readFile } from 'node:fs/promises'

export async function readEntryManifest(path, entryKey) {
  // manifest 由同一次构建生成，先整体读取再按入口取记录
  const text = await readFile(path, 'utf8')
  const manifest = JSON.parse(text)
  const entry = manifest[entryKey]
  if (!entry?.file) {
    // 入口名写错或构建配置变化时，不要静默输出坏链接
    throw new Error(`manifest entry not found: ${entryKey}`)
  }
  return entry
}

沿 imports 和 css 组装资源标签

后端模板最容易漏掉的是共享 chunk。入口记录的 imports 不是最终文件名数组，而是 manifest 中其他记录的 key，所以需要递归查找。每个记录的 css 也要合并去重，否则同一个共享样式可能被输出多次。

export function collectImportedChunks(manifest, entryKey) {
  const seen = new Set()
  const result = []

  function visit(key) {
    // 循环依赖或多个入口共享同一 chunk 时只处理一次
    if (seen.has(key)) return
    seen.add(key)
    const chunk = manifest[key]
    if (!chunk) return
    for (const importedKey of chunk.imports ?? []) visit(importedKey)
    result.push(chunk)
  }

  visit(entryKey)
  return result
}

随后可以用一组集合构造 HTML。推荐先输出入口及依赖 CSS，再输出入口脚本；对确定会在当前页面执行的依赖 JS，才添加 modulepreload。

modulepreload 与 preload 的选择边界

modulepreload 面向 JavaScript 模块：浏览器不仅提前下载，还会解析、编译并放入模块映射表。Vite 的后端集成示例也把它放在入口脚本旁，用于提前获取递归 imports。普通 preload 更像“先下载并缓存”，适合字体、图片或非模块资源；处理 JavaScript 模块时优先考虑前者。

预加载不是越多越好。首屏入口的共享依赖、马上会执行的模块值得提前获取；点击后才打开的管理页、低概率弹窗和动态 import chunk 则继续让运行时按需拉取。过度预加载会抢占 CSS、图片和真正关键请求的带宽与解析时间。

发布前用一张清单检查资源引用

• 检查后端读取的入口 key 与构建输入一致，尤其是多页面项目不要把页面名称误当成 key。
• 检查 base、CDN 前缀和后端公开路径只拼接一次，避免出现双斜杠或缺少部署前缀。
• 检查 HTML 中的 CSS、入口 JS 和关键 modulepreload 是否全部来自同一份 manifest。
• 检查浏览器网络面板：每个哈希文件应命中当前发布目录，旧 HTML 不应引用已被清理的旧版本资源。

如果资源 404，优先回到“HTML、manifest、静态目录是否同一版”这条链路排查；如果首屏反而变慢，先减少非关键模块的预加载，再观察请求优先级和脚本执行时间。

相关问题

build.manifest 写成字符串和写成 true 有什么区别？

true 使用输出目录下的默认 .vite/manifest.json 路径；字符串则指定相对于 outDir 的 manifest 路径，方便后端固定读取。

为什么只读取入口的 file 仍然会缺少样式？

样式通常记录在入口或其依赖 chunk 的 css 数组中，只输出 file 不会自动把 CSS 标签注入后端 HTML。

动态 import 的 chunk 要不要全部加 modulepreload？

通常不要。只有当前页面马上会用到的模块才值得预加载，其他动态 chunk 保持按需获取，避免浪费首屏网络和解析资源。