开启build.manifest是Vite实现资源哈希映射的关键，需在vite.config.js中显式配置manifest: true，并确保vite build成功生成合法JSON格式的manifest.json文件，其键为源路径（如resources/js/app.js），值为带hash的产物路径，且后端读取路径必须与outDir严格匹配。
开启 build.manifest 是 Vite 实现资源哈希映射、对接后端 SSR 或传统服务端（如 ThinkPHP/Laravel/Java）的关键一步。它不是自动生效的开关，而是需要明确配置 + 正确构建流程才能生成可用的 manifest.json 文件。
在 vite.config.ts/js 中启用 manifest 生成
只需在 build 选项中设置 manifest: true 即可。Vite 默认会将清单输出到 outDir（通常是 dist 或 public/build）下的 manifest.json：
- 基础写法（推荐）：
export default defineConfig({<br> build: {<br> manifest: true<br> }<br>}); - 若使用 Laravel 或 ThinkPHP 等约定路径，不要手动改
outDir，除非你同步调整后端读取逻辑；否则容易导致后端找不到文件 - 确保入口文件路径正确——manifest 映射的是输入路径（如
resources/js/app.js或src/main.ts）到输出产物的对应关系，不是 HTML 文件名
构建后检查 manifest.json 是否有效
运行 vite build 后，必须验证生成结果是否符合预期，否则后端解析会失败：
- 文件存在且非空：确认
dist/manifest.json（或你配置的outDir下）真实存在，内容是合法 JSON - 结构合理：典型条目形如
{"src/main.ts": {"file": "assets/index.abc123.js", "css": ["assets/index.def456.css"]}}，注意键名是源码入口路径，不是构建后文件名 - CSS/JS 字段齐全：如果用
rollupOptions.output.manualChunks拆分代码，部分 CSS 可能不在入口项里，需遍历整个 manifest 查找isEntry: true且file以.css结尾的条目
配合服务端渲染（SSR）时的特别处理
SSR 场景下，manifest 不仅用于静态资源注入，还参与服务端预渲染的资源收集：
- 启用 SSR manifest（可选但推荐）：
build: { manifest: true, ssrManifest: true }，会额外生成ssr-manifest.json，供服务端确定哪些 chunk 需要提前加载 - 服务端需读取 manifest 并注入到 HTML 模板：例如 Node.js 中用
fs.readFileSync读取，再提取entry对应的 JS/CSS 路径，拼入<link rel="stylesheet">和<script type="module"> - 注意 base 路径一致性：若配置了
base: '/subpath/'，manifest 中的file值已含该前缀，后端拼接 URL 时不要再重复添加
常见失效原因与快速排查
manifest 生成了却没用上？多半卡在这几个环节：
- Vite 构建未真正执行：检查是否误用了
vite dev，manifest 只在build阶段生成 - 后端读取路径错误：ThinkPHP 用
public_path('build/manifest.json')，Laravel 默认找public/build/manifest.json，Java 项目可能映射到resources/static/，路径必须严格匹配 - 入口路径不一致：后端调用时传的 key（如
'src/main.ts'）必须和 manifest 中的键完全一致，大小写、斜杠方向都不能错 - 开发环境误用 manifest：开发时应直连 Vite 开发服务器（
http://localhost:5173/@vite/client），而非读取 manifest，避免混淆环境逻辑
