核心是确保 laravel-vite-plugin 正确生成 public/build/manifest.json：插件必须位于 vite.config.js 的 plugins 数组首位、build.outDir 不可修改、且须安装官方插件而非 vite-plugin-laravel。
Mac 下 Laravel 9 使用 Vite 打包，核心就一条：别碰 vite.config.js 里 build.outDir 和 plugins 顺序，否则 @vite 指令在生产环境必报 404 —— 这不是路径写错了，是 manifest.json 根本没生成或没被读到。
为什么 npm run build 后 public/build 里没有 manifest.json
这是 Mac 用户最常卡住的第一步。Laravel 的 laravel-vite-plugin 在构建时必须生成 public/build/manifest.json，而这个文件是 @vite 指令在生产环境解析资源路径的唯一依据。
- 运行
npx vite build --debug，如果终端第一行出现[vite] Manifest is disabled，说明插件根本没生效 —— 很可能你装的是vite-plugin-laravel（不兼容），而不是官方的laravel-vite-plugin -
build.outDir被手动改成public/assets或其他路径？别改。Laravel 硬编码只认public/build，改了等于废掉@vite -
laravel()插件没放在plugins数组第一位？它必须在vue()或react()之前，否则 manifest 不生成
@vite 指令在 Blade 中怎么写才不 500
@vite 不是语法糖，它是服务端指令，编译阶段就执行，对写法极其敏感。
- 参数必须是数组：
@vite(['resources/js/app.js', 'resources/css/app.css'])；传字符串如@vite('resources/js/app.js')会触发 PHP 的Array to string conversion错误 - 路径必须以
resources/开头，不能带./或../，比如@vite(['./resources/js/app.js'])会找不到入口 - 不能嵌套在
@if、@section、@push等 Blade 指令块内，它得在模板顶层直接出现 - 开发时它注入的是
http://localhost:5173/@vite/client，生产时自动 fallback 到public/build/下的哈希文件 —— 所以你不需要也不应该手动切环境
Mac 上 npm run dev 启动失败或 HMR 不生效
Mac 系统常见干扰项集中在端口、host 和 Node 版本兼容性上。
- 终端报
command not found: vite？检查package.json的scripts里有没有"dev": "vite"，并且你是在项目根目录（含vite.config.js和package.json）下执行的 - 浏览器控制台报 WebSocket 连接失败？
vite.config.js里server.host别设成'0.0.0.0'，Mac 上容易被 Safari/Chrome 拒绝；设为true或显式'localhost'更稳 - HMR 改了 Vue 组件没反应？确认
laravel({ refresh: true })已启用，且resources/js/app.js里确实import了该组件（空文件或没 import 就不会监听） - APP_URL 设成
http://localhost:8000，但 Vite 默认跑在:5173—— 这没关系，HMR 请求地址由vite.config.js的server配置决定，不是 APP_URL
图片、字体等静态资源引用失效怎么办
Vite 不处理 public/ 下的文件，所有需要哈希和 CDN 缓存失效的资源，必须走构建流程。
- 把
logo.png放进resources/images/，然后在 CSS 里写background: url('../images/logo.png');—— Vite 会自动哈希并复制到public/build/ - 千万别在 Blade 里用
url('/images/logo.png')引用public/images/下的图，它绕过 Vite，不会进 manifest，上线后缓存永远不更新 - SVG 当组件用？确保已安装对应框架插件（如
@vitejs/plugin-vue），否则import Icon from './Icon.vue'会解析失败
真正容易被忽略的点是：manifest.json 的存在与否，决定了整个生产环境是否可用；而它的生成，完全取决于 laravel-vite-plugin 是否被正确加载、是否在插件列表首位、以及 build.outDir 是否保持默认值 —— 其他配置再炫酷，这三项错一个，@vite 就形同虚设。
