manifest.json缺失、为空或格式非法会导致@vite失效并引发404和白屏；必须显式配置build.manifest: true，确保laravel-vite-plugin正确加载且input路径存在、合法、可读，并验证manifest键值对及对应资源文件是否真实存在。
当你执行 vite build 后，public/build/manifest.json 文件缺失、为空或格式非法，Laravel 的 @vite 指令就会彻底失效，所有前端资源返回 404，页面白屏或 JS/CSS 不加载——这不是缓存问题，而是构建流程在源头就中断了。
确认 vite.config.js 是否启用 manifest
打开项目根目录下的 vite.config.js（或 .ts），检查 build 配置项中是否明确写了 manifest: true：
✅ 正确写法（必须显式声明）：
复制AI写代码
export default defineConfig({<br> plugins: [laravel({ input: ['resources/js/app.js'] })],<br> build: { manifest: true }<br>});
❌ 错误写法：漏掉 build: { manifest: true }，或仅写 manifest: true 却没包裹在 build 对象里。Vite 不会默认开启该功能，不写就等于关闭。
验证 laravel-vite-plugin 是否被正确加载
方法一：检查插件是否在 plugins: [] 数组中且位置靠前
laravel-vite-plugin 必须位于其他构建插件（如 vue()、react()）之前，否则它无法接管入口解析与 manifest 生成逻辑。
方法二：运行 vite build --debug 观察终端输出
若看到 [laravel-vite-plugin] Building manifest... 或类似日志，则插件已激活；若完全无此提示，说明插件未被识别——常见原因是 import laravel from 'laravel-vite-plugin' 路径错误，或 npm 包未安装（npm install laravel-vite-plugin）。
【注意】 如果你用的是 Laravel 9.19+，但没运行过 php artisan vite:install，则 laravel-vite-plugin 可能未被自动引入到配置中，手动 import 也容易因路径错漏失败。
使用固定的 Next.js/Tailwind/Prisma 技术栈构建并记录独立 SaaS 项目，仅将 FastAPI 用于 Python 工作负载，并遵循严格的架构规范。
检查构建入口路径是否存在且可读
第一步：确认 vite.config.js 中 laravel() 的 input 数组里每个路径都真实存在
例如：laravel(['resources/js/app.js', 'resources/css/app.css']) → 必须确保 resources/js/app.js 这个文件物理存在，哪怕内容为空。缺一个，整个插件初始化就会静默跳过，manifest 不生成。
第二步：禁止使用相对路径或别名laravel(['./resources/js/app.js']) ❌、laravel(['@/js/app.js']) ❌ —— laravel-vite-plugin 只认以 resources/ 开头的绝对路径（相对于项目根目录），否则无法映射源码路径到产物，manifest 键名将为空或错乱。
第三步：检查文件权限
Linux/macOS 下若 resources/js/app.js 权限为 000 或属主不符，Vite 构建时读取失败却无明显报错，manifest.json 会生成空对象 {} 或直接不创建文件。
运行构建并逐级验证输出
① 在项目根目录执行：npm run build（或 yarn build / pnpm build）
② 立即检查 public/build/manifest.json 是否生成：
→ 若文件不存在：说明构建中途退出，回看终端最后一行错误（常见如 TypeScript 类型错误、Vue SFC 解析失败、缺少 @vitejs/plugin-vue）；
→ 若文件存在但内容为空或仅为 {}：大概率是入口路径不存在，或 laravel() 插件根本没执行；
→ 若文件内容为合法 JSON 但键名不是 "resources/js/app.js" 这类路径：说明 input 配置被忽略，可能用了自定义插件覆盖了 laravel 插件逻辑。
③ 打开 manifest.json，确认至少有一条有效映射，例如：{"resources/js/app.js": {"file": "assets/app.abc123.js", "css": ["assets/app.def456.css"]}}
键名必须是源码路径，值对象必须含 file 字段——缺少任一，Laravel 的 @vite 就无法解析出真实资源地址。
④ 同步检查 public/build/assets/ 目录下是否存在对应文件名的 JS/CSS 文件
例如 manifest 中 "file": "assets/app.abc123.js"，则 public/build/assets/app.abc123.js 必须真实存在且非空。若文件缺失，说明构建压缩/输出阶段失败，需查看 Vite 构建日志中 ✓ built in XXXms 前的 warning 或 error。
