根本原因是 public/build/manifest.json 缺失或格式不合法，而 @vite 在生产环境完全依赖该文件进行路径映射；同时 vite.config.js 中 build.outDir 被 Laravel 的 laravel-vite-plugin 强制锁定为 public/build，擅自修改将导致断链。
直接用 @vite 指令，别手写 script 标签，否则生产环境必 404；vite.config.js 里别乱改 build.outDir，Laravel 的 laravel-vite-plugin 只认 public/build 这个硬编码路径。
为什么 @vite(['resources/js/app.js']) 在生产环境加载失败？
根本不是路径写错了，而是 public/build/manifest.json 缺失或格式不合法 —— @vite 在生产模式下完全依赖这个文件做路径映射。
-
npm run build后检查public/build/目录是否存在、是否为空；空目录说明构建未触发或被插件拦截 - 确认安装的是
laravel-vite-plugin（不是vite-plugin-laravel），后者不生成 manifest - 运行
npx vite build --debug，若看到[vite] Manifest is disabled，说明插件未生效或配置被覆盖 -
@vite参数必须是数组，传字符串如@vite('resources/js/app.js')会静默失败，报Array to string conversion
vite.config.js 哪些配置动不得？
Laravel 的 laravel-vite-plugin 对部分选项做了强约定，改了就断链。
-
build.outDir：设了也无效，插件强制输出到public/build；手动改成public/assets会导致@vite找不到 manifest -
server.host：开发时别设'0.0.0.0'，浏览器会拒绝连接；应设为true或显式'localhost' -
resolve.alias：加了@别名后，必须同步在tsconfig.json或jsconfig.json里声明，否则 IDE 报错、TS 类型检查失效 -
plugins数组里必须保留laravel(...)，它是@vite解析 manifest 的唯一入口
图片、字体等静态资源怎么引用才不丢？
Vite 不处理 public/ 下的文件，所有需哈希和版本控制的静态资源，必须从 resources/ 目录导入。
- 把 logo.png 放进
resources/images/，然后在 CSS 中写background: url('../images/logo.png');，Vite 会自动复制并哈希到public/build/ - 不要在 Blade 里用
url('/images/logo.png')引用public/images/下的图 —— 它绕过 Vite 构建流程，不会进 manifest，上线后 CDN 缓存无法自动失效 - SVG 作为组件使用时，需配合
@vitejs/plugin-vue或@vitejs/plugin-react，否则import MyIcon from './Icon.vue'会解析失败
APP_URL 和 Vite 开发端口不一致导致 HMR 失效？
不是跨域问题，是 Vite 客户端脚本请求地址错了。HMR 脚本由 @vite 注入，它读取的是 vite.config.js 里的 server 配置，不是 APP_URL。
- 确保
NODE_ENV=development（Laravel 默认设好，但 Docker 或某些终端会覆盖） -
vite.config.js中server.port默认是 5173，页面注入的 HMR 地址就是http://localhost:5173/@vite/client；如果 Laravel 是通过 Nginx 代理访问的，要配server.proxy把/@vite和/__vite_ping转发过去 - Blade 中
@vite必须放在<head>里，不能嵌套在@if、@section等指令中，否则编译阶段无法提前解析
最易被忽略的一点：@vite 不是语法糖，它背后依赖完整的插件链和 manifest 文件结构；删掉 laravel-vite-plugin 或改错 input 路径，整个机制就停摆，且错误往往静默发生，只表现为资源不加载。
