laravel 9.19+ 原生支持 vite，但必须执行 php artisan vite:install 初始化，且 @vite 指令正常工作依赖开发服务器运行、入口路径匹配、vite.config.js 正确识别，任一环节缺失均导致资源 404 或热更新失效。
直接上结论：Laravel 9.19+ 已原生支持 Vite，但不是“装完就能用”，必须执行 php artisan vite:install 初始化，且 @vite 指令能否正常工作，完全取决于开发服务器是否在运行、入口路径是否匹配、vite.config.js 是否被正确识别——漏掉任一环，都会表现为 JS/CSS 404 或热更新失效。
为什么 @vite(['resources/js/app.js']) 报错或不加载资源
这是最常卡住人的第一步。报错往往不是语法问题，而是环境或配置链断裂：
-
@vite参数必须是数组，写成@vite('resources/js/app.js')会触发Array to string conversionPHP 错误 - 路径必须以
resources/开头，不能带./或../，否则laravel-vite-plugin找不到入口文件 - 开发时若页面加载的是
/build/xxx.js（生产路径），说明 Vite 开发服务器没启动，或NODE_ENV被意外设为production - Blade 中
@vite不能放在@if、@section等指令块内部，它必须在模板编译阶段就被解析
vite.config.js 哪几项改了就大概率出问题
Laravel 的 laravel-vite-plugin 对配置有强约定，乱动关键字段等于主动绕过集成逻辑：
-
build.outDir默认是public/build，这是 Laravel 硬编码读取 manifest 的路径；改成public/assets后，@vite会彻底找不到文件 -
server.host设为'0.0.0.0'时，Vite 插件可能注入http://0.0.0.0:5173到页面，导致浏览器拒绝连接；应设为'localhost'或true -
resolve.alias里如果改了@别名（比如指向src/），必须同步在jsconfig.json或tsconfig.json中声明，否则 IDE 不认、TS 类型检查挂掉 - 删掉
laravel()插件，或把它放在其他插件之后（如vue()之前），会导致manifest.json不生成、@vite失效
npm run dev 启动失败或 HMR 不生效的排查点
错误信息常被忽略，但线索都在终端第一行：
- 运行
vite报command not found？先确认package.json里有"dev": "vite"，且你是在项目根目录（含package.json和vite.config.js）下执行的 - 启动后控制台出现
[vite] Manifest is disabled？说明laravel-vite-plugin没生效，检查是否装错了包（vite-plugin-laravel不兼容）或版本不匹配 - HMR 改了 Vue 组件没反应？确认
laravel({ refresh: true })已启用，且resources/js/app.js里确实 import 了组件（空文件不会触发监听） - 浏览器控制台报 WebSocket 连接失败？可能是反向代理（Nginx / Docker）没透传
ws://协议，或防火墙拦截了 5173 端口
public/build 下没有 manifest.json 怎么办
这代表构建流程在中途断掉了，不是路径问题，而是插件或配置破坏了默认行为：
- 先运行
npx vite build --debug，看是否有[vite] Manifest is disabled提示——有则 100% 是laravel-vite-plugin未加载 - 检查
vite.config.js是否用了build.rollupOptions.output.manualChunks，这个选项会干扰插件对 chunk 的映射逻辑 - 确认
composer require laravel/vite已执行（注意不是laravel-vite-pluginnpm 包，那是旧名） - 如果用了自定义
build.base或publicDir，Vite 会跳过 manifest 生成；Laravel 只认public/build，别试图改它
真正容易被忽略的点是：Vite 的开发服务器和 Laravel 的 PHP 服务是两个独立进程，@vite 指令本身不启动任何服务，它只是根据当前环境变量决定注入开发代理地址还是读取 manifest.json。很多人以为“配完就能热更”，结果连开发服务器都没手动跑起来。
