laravel 10+ 默认用 vite 因其启动快、热更新毫秒级、原生支持 es 模块和 typescript，而 mix 基于 webpack，启动慢、配置重、对现代前端生态支持滞后。
为什么 Laravel 10+ 默认用 Vite 而不是 Mix
因为 Vite 启动快、热更新毫秒级、原生支持 ES 模块和 TypeScript，而 Mix 基于 Webpack，启动慢、配置重、对现代前端生态支持滞后。Laravel 10 是首个将 vite 作为默认构建工具的 LTS 版本，npm run dev 实际调用的是 vite 而非 webpack-dev-server。
如果你刚从 Laravel 9 升级上来，会发现 webpack.mix.js 文件没了，resources/js/app.js 开头多了 import './bootstrap';，且 public/mix-manifest.json 不再生成 —— 这些都是 Vite 接管编译的信号。
如何在 Blade 中正确引入 Vite 编译后的资源
Laravel 提供了 @vite 指令自动注入开发时的 HMR 脚本（http://localhost:5173/@vite/client）和生产环境的静态资源链接，它比手写 <script src="/build/xxx.js"></script> 安全得多，能自动处理哈希、代码分割和 CSS 注入。
-
@vite必须放在内，否则 HMR 失效；不能用在子视图（@include）中动态拼接路径 - 多个入口文件要显式列出：
@vite(['resources/js/app.js', 'resources/js/pages/dashboard.js']) - 如果用了 SSR 或 Inertia，需额外加
@viteReactRefresh（仅开发环境），否则组件更新不触发重渲染 - 生产环境运行
npm run build后，@vite会自动读取public/build/manifest.json映射真实文件名
修改 Vite 配置：比如添加别名或调整端口
所有自定义都写在项目根目录的 vite.config.js 中，而不是 Laravel Mix 那套。Laravel 官方脚手架已预置基础配置，但你很可能需要改：
立即学习“前端免费学习笔记（深入）”；
- 添加
@/别名指向resources/js：import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; export default defineConfig({ plugins: [ laravel({ input: ['resources/css/app.css', 'resources/js/app.js'], refresh: true, }), ], resolve: { alias: { '@': '/resources/js', }, }, server: { host: 'localhost', port: 5173, hmr: { overlay: false }, // 关闭浏览器错误浮层（适合 CI 或特定 UI） }, }); - 注意
laravel-vite-plugin的input数组决定哪些文件被监听和输出；漏掉的 JS/CSS 不会进构建流程 - Vite 不支持 Webpack 那种
mix.webpackConfig的“补丁式”配置，所有改动必须在vite.config.js里显式声明
常见报错与绕过方式
Vite 和 Laravel 集成虽顺滑，但几个典型错误容易卡住：
-
504 Gateway Timeout或ERR_CONNECTION_REFUSED：检查vite dev server是否真的在运行（npm run dev），Blade 中的@vite不会自动启服务 -
Cannot find module '@/components/Example.vue'：确认vite.config.js中resolve.alias已生效，且 VS Code 等编辑器没缓存旧路径提示 - 生产环境 JS 报
Failed to fetch dynamically imported module：说明代码分割后 chunk 路径错乱，检查是否误删了public/build目录下除manifest.json外的其他文件，或 Nginx/Apache 没配好静态文件路由 - Inertia 页面切换白屏：确认
app.js中已执行createInertiaApp，且@vite在里，不在底部
Vite 的构建产物结构和加载逻辑跟 Webpack 有本质差异，直接套用 Mix 经验容易踩坑 —— 尤其是资源路径、模块解析和 HMR 生命周期这几个点，得按 Vite 的方式重新理解一遍。
