manifest.json缺失、路径错位或配置不匹配是前端资源加载失败主因；必须确保public/build/manifest.json存在且格式合法，vite.config.js中build.outDir未被手动修改，@vite参数为数组且路径以resources/开头，开发时NODE_ENV=development。
前端资源加载失败，大概率是 manifest 文件缺失、路径错位或配置不匹配。Vite 的 manifest.json 是生产环境映射资源的关键，Laravel 的 @vite 指令全靠它把 resources/js/app.js 翻译成 /build/assets/app.abc123.js 这类真实路径。查不到、读不对、配不齐，就必然 404。
确认 manifest.json 是否存在且位置正确
运行 npm run build 后，Vite 默认输出到 public/build/ 目录。必须检查以下三项是否同时满足：
-
public/build/manifest.json文件真实存在（不是空文件，也不是 JSON 格式错误） - 该文件中至少有一组合法键值对，例如：
"resources/js/app.js": "assets/app.xxxx.js" -
public/build/assets/下确实存在对应名称的 JS/CSS 文件（如app.xxxx.js）
如果 public/build/ 整个目录为空，说明 vite build 没执行成功，或 laravel-vite-plugin 未生效（常见于装错插件包或 input 路径不存在）。
检查 vite.config.js 中的 build.outDir 和 laravel 插件配置
Laravel 原生只认 public/build/ 这个路径，硬编码读取 manifest.json。如果你改过 build.outDir，比如设成 'public/assets'，那默认的 @vite 就会失效——它不会自动去找 public/assets/manifest.json。
立即学习“前端免费学习笔记（深入）”；
- 删掉
vite.config.js中手动写的build.outDir字段（laravel-vite-plugin自己控制输出位置） - 确保
laravel()插件调用时传入了正确的入口数组，例如：laravel(['resources/js/app.js']) - 若必须自定义输出目录（如
public/assets），需同步修改config/vite.php中的'build_directory' => 'assets'，否则 @vite 仍会去public/build/找 manifest
验证 Blade 中 @vite 的写法和运行环境
@vite 不是万能路径生成器，它对参数格式、环境变量、模板位置都有严格要求：
- 参数必须是数组：
@vite(['resources/js/app.js'])✅，@vite('resources/js/app.js')❌（PHP 报 Array to string conversion） - 路径必须以
resources/开头，不能带./或../，也不能指向 public 下已存在的文件 - 不能嵌套在
@if、@section或其他 Blade 指令块内部，必须在模板顶层直接使用 - 开发时若看到页面加载的是
/build/xxx.js，说明 Vite 开发服务器没启动，或NODE_ENV不是development（建议在package.json的"dev"脚本里显式加前缀："dev": "NODE_ENV=development vite"）
区分 asset() 和 @vite 的使用场景
很多人混淆这两个机制：
-
{{ asset('js/app.js') }}：只适用于你手动放进public/js/的静态文件，不经过 Vite 编译，也不走 manifest 映射 - @vite(['resources/js/app.js'])：专为 Vite 入口文件设计，开发时连本地服务器，生产时查 manifest.json，二者逻辑完全隔离
- 混用会导致白屏——比如用
asset()加载 Vite 编译后的哈希文件，路径根本不存在；或用 @vite 加载 public 下的旧文件，插件找不到入口直接跳过
