Vite 在 Laravel 中不是插件式引入，而是构建层替换——必须停用 Mix、删除 webpack.mix.js，否则两者冲突导致热更新失效、哈希路径错乱、白屏或 404。
Vite 在 Laravel 里不是“插件式引入”，而是“构建层替换”——你必须停用 Mix、删掉 webpack.mix.js，否则两个工具会同时监听文件、冲突热更新、生成错乱的哈希路径，最终导致白屏或资源 404。
为什么不能和 Laravel Mix 共存
Webpack（Mix 底层）和 Vite 的构建模型根本不同：Mix 启动时会扫描全部入口并预构建整个依赖图，Vite 则靠浏览器原生 ESM 按需请求、动态编译。两者同时运行，public/js 和 public/build 目录会被反复覆盖，@vite 指令在开发时依赖 http://localhost:5173 代理，而 Mix 的 dev server 默认占 :8080，端口和中间件逻辑互不感知，结果就是 HMR 失效、CSS 变量丢失、甚至 manifest.json 写入失败。
- 执行
npm run dev前先确认ps aux | grep -i "vite\|webpack"没有残留进程 -
rm -f webpack.mix.js node_modules/.bin/webpack*必须做，不能只改脚本 - 如果项目曾用 Mix 启用过版本控制（
.version()），要清空public/mix-manifest.json，否则 Blade 渲染时可能混用旧路径
如何正确配置 vite.config.js
关键不是“写对语法”，而是让 laravel-vite-plugin 知道哪些文件是真正入口——它不会自动扫描 resources/js 下所有 .js，只处理你显式传入的数组项。比如你用 Vue 单文件组件，就得把 resources/js/app.js 和 resources/js/Pages/Home.vue 都列进去，否则后者不会被纳入 HMR 范围。
- 入口路径必须是相对于项目根目录的字符串，不能用 glob（
"resources/js/**/*.js"不生效） - 若使用 Tailwind，确保
resources/css/app.css已 @import tailwindcss/base 等三部分，Vite 不会像 Mix 那样自动注入 PostCSS 配置 - 开发时想代理 API 请求，直接在
vite.config.js加server.proxy，不要碰mix.webpackConfig配置项（它已失效）
@vite 指令在 Blade 中的实际行为
@vite 不是简单输出 script 标签，它会根据环境自动切换加载方式：开发时注入 http://localhost:5173/@vite/client 和入口模块；生产时读取 public/build/manifest.json，按文件内容哈希匹配路径。如果部署后页面空白，90% 是因为 manifest.json 没上传、或 build.outDir 和 config/vite.php 中的 'build_directory' 不一致。
立即学习“前端免费学习笔记（深入）”；
- 运行
npm run build后，检查public/build/manifest.json是否存在且非空 - Blade 中写法必须是
@vite(['resources/css/app.css', 'resources/js/app.js'])，路径要和vite.config.js里完全一致，大小写敏感 - 如果用了 React 或 Vue 插件，
@viteReactRefresh或@viteVue只在开发环境生效，生产构建时自动降级为普通@vite
静态资源（图片、字体）怎么引用才不丢
Vite 对 public/ 下文件是直接映射，但对 resources/ 下的非 JS/CSS 文件（如 resources/images/logo.png），必须用 new URL(..., import.meta.url) 显式导入，否则构建后路径会断裂。Mix 时代的 asset('images/logo.png') 在 Vite 下仍可用，但那是 PHP 层拼接的，不带哈希，无法利用长期缓存。
- CSS 中引用图片：用
url('@/images/logo.png')（前提是已配别名@指向resources） - JS 中动态加载：写
const img = new URL('../images/logo.png', import.meta.url)，再赋给src - Blade 中硬编码路径：只用于
public/下资源，如<img src="{{ Vite::asset('images/logo.png') }}">，注意这个 helper 从 Laravel 9.19+ 才有
最常被跳过的环节是确认 public/build 目录是否随部署流程一起上线——很多 CI/CD 脚本只同步 public/*，却漏掉 public/build，结果生产环境永远读不到 manifest.json。
