@vite指令不工作主因是vite.config.js配置错误或运行环境不符：server.host设为'0.0.0.0'导致浏览器拒绝连接，应改用true或'localhost'；node_env非development时插件不启用代理逻辑；未在项目根目录运行npm run dev；build.outdir被手动修改或使用了错误插件包；input路径不存在或manifest.json缺失；vue/ts项目未启用refresh、未引入@vitejs/plugin-vue或tsconfig.json中"noemit":true。
@vite 指令不工作？90% 是 vite.config.js 配置错或运行环境不对，不是路径写错了。
为什么 @vite(['resources/js/app.js']) 加载的是 public/build 下的旧文件，而不是开发服务器资源？
根本原因是 Vite 插件没拿到有效的开发服务地址，导致 Blade 渲染时 fallback 到生产路径。常见诱因有两个：
-
server.host设成了'0.0.0.0'—— 浏览器会拒绝连接http://0.0.0.0:5173，必须改成true或显式写'localhost' -
NODE_ENV不是development—— Laravel 的@vite指令只在该环境下启用代理逻辑；Docker、某些终端或 CI 环境可能覆盖它，建议在package.json的"dev"脚本里加前缀："dev": "NODE_ENV=development vite" - 没在项目根目录运行
npm run dev—— 如果误入resources/js目录执行，Vite 找不到vite.config.js，插件不加载，@vite就退化成静态路径注入
build 后 public/build 里没有 manifest.json，或者 JS/CSS 404？
这是 laravel-vite-plugin 没生效的明确信号。它负责生成 manifest.json 并接管输出路径，但极易被误操作破坏：
- 手动改了
build.outDir——laravel-vite-plugin完全忽略这个配置，只认自己的buildDir选项（默认'public/build'）；删掉build.outDir字段即可 - 用了错误的插件包 —— 必须是
laravel-vite-plugin（npm 包名），不是vite-plugin-laravel（已废弃且不兼容） -
input数组里有路径不存在 —— 比如写了'resources/js/app.js'但文件已被删，插件初始化直接跳过，整个 manifest 生成流程中断 - 部署时只传了
.js和.css文件，漏了manifest.json—— 这个文件是@vite映射哈希路径的唯一依据，缺了必 404
Vue/TS 项目热更新失效，改了 .vue 文件不刷新？
HMR 失效往往不是 Vite 本身的问题，而是插件链没接上：
-
refresh选项没开 —— 在laravel-vite-plugin配置里必须显式设refresh: true，官方模板默认有，但重装插件后容易漏 - 没装
@vitejs/plugin-vue或没加进plugins数组 ——laravel-vite-plugin不处理 Vue 语法，它只管资源注入和 HMR 触发入口，Vue 编译得靠自己配 -
input没包含实际使用的 Vue 入口 —— 比如你用resources/js/Pages/Home.vue作为根组件，但input只写了app.js，那改 Home.vue 就不会触发刷新 - TypeScript 的
"noEmit": true—— 这会让 TS 编译器不输出任何 JS，看起来像“没打包”，检查tsconfig.json，确保它设为false或干脆删掉这一项
CDN、Docker、WSL 环境下 @vite 资源加载失败？
这些环境对网络和路径更敏感，关键点不在 Vite 本身，而在服务暴露和路径解析是否一致：
- Docker/WSL：推荐
server.host: '0.0.0.0'+server.port: 5173，但必须在宿主机访问http://localhost:5173（别用127.0.0.1），同时确保容器端口映射正确 - CDN：必须在
vite.config.js中加base: 'https://cdn.example.com/build/'，否则@vite生成的路径仍是相对路径或/build/xxx.js，CDN 域名不会自动补上 - Web 服务器（Nginx/Apache）：要显式允许访问
/build/路径，例如 Nginx 配置中加location /build/ { try_files $uri =404; }，否则 404 不是 Vite 的错，是 Web 服务器拦的 -
APP_URL必须与你实际访问的域名+端口完全一致 —— 开发时设成http://localhost:5173，如果浏览器打的是http://127.0.0.1:8000，HMR 的 WebSocket 请求就会跨域被拒
真正卡住人的地方，从来不是某个配置项写错了，而是 Vite 插件之间谁先执行、谁依赖谁、谁读取谁的输出 —— 尤其是 laravel-vite-plugin 和框架插件（如 @vitejs/plugin-vue）的顺序和职责边界。只要插件链断一环，@vite 就从智能指令退化成静态标签。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
