> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # 使用 Vite 打包资源 > 介绍在 Laravel 项目中使用 Vite 打包 JavaScript 与 CSS，并借助热重载构建舒适开发环境的方法。 ## Laravel 与 Vite [Vite](https://vitejs.dev) 是一款高性能的前端构建工具。开发时提供即时反映改动的热模块替换（HMR），生产构建时生成经过优化的资源。 Laravel 9 以后 Vite 成为标准前端构建工具，通过 `laravel-vite-plugin` 与 Laravel 集成。这个插件的主要职责包括： * 管理入口文件 * 提供开发服务器的 HMR 支持 * 与 `@vite()` Blade 指令联动 * 生产构建时对资源做版本化（缓存破坏）如果你在使用 Laravel Breeze 等 Laravel 起步套件，Vite 和 Tailwind 的配置已经内置。本页介绍从零配置的做法。想了解 Vite 在 Laravel 整体前端方案中的定位，可先看看[前端](/zh/frontend)一节的全景介绍。 ## 安装与配置 ### 检查 Node 是否安装 Vite 需要 Node.js（16 及以上）和 npm。可通过下面命令确认。 ```shell theme={null} node -v npm -v ``` ### 安装依赖新装的 Laravel 项目 `package.json` 中已经包含 `vite` 与 `laravel-vite-plugin`。用下面的命令安装依赖。 ```shell theme={null} npm install ``` ### vite.config.js 配置项目根目录会生成 `vite.config.js`。你需要在其中指定入口文件（打包入口）。 ```js theme={null} import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; export default defineConfig({ plugins: [ laravel([ 'resources/css/app.css', 'resources/js/app.js', ]), ], }); ``` SPA 或 Inertia 项目推荐从 JavaScript 中导入 CSS。此时入口中不再列 `resources/css/app.css`，而是在 `resources/js/app.js` 顶部加入 `import '../css/app.css';`。 ## 启动开发服务器开发时使用 `npm run dev` 启动 Vite 开发服务器。修改文件后浏览器会自动更新（HMR）。 ```shell theme={null} npm run dev ``` 也可以与 Laravel 开发服务器一起启动。 ```shell theme={null} composer run dev ``` `composer run dev` 会同时启动 `php artisan serve` 和 `npm run dev`。 ### Blade 视图自动刷新配置 `refresh: true` 后，保存 Blade 视图或路由文件时浏览器会自动刷新。 ```js theme={null} 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, }), ], }); ``` 启用 `refresh: true` 后，以下目录的变更会被监听： * `resources/views/**` * `app/Livewire/**` * `routes/**` * `lang/**` ## 生产构建部署到生产环境前执行 `npm run build`。资源会被打包并加上版本号，输出到 `public/build/`。 ```shell theme={null} npm run build ``` 构建后的目录结构示例： ```text theme={null} public/ build/ assets/ app-Cv82Mlke.css app-DnAZBF4U.js manifest.json ``` `manifest.json` 记录了文件名和哈希的对应关系，`@vite()` 指令会读取它来加载正确的文件。 `public/build/` 是构建产物，建议加入 `.gitignore`。可以在部署目标机器上构建，也可以在 CI 中构建后部署。 ## 从 Blade 加载资源在布局的 `` 中加入 `@vite()` Blade 指令。 ```blade theme={null} {{ config('app.name') }} @vite(['resources/css/app.css', 'resources/js/app.js']) @yield('content') ``` 如果 CSS 是从 JavaScript 中导入的，只需指定 JS 入口即可。 ```blade theme={null} @vite('resources/js/app.js') ``` `@vite()` 指令会根据开发和生产两种模式自动切换行为。 | 场景 | 行为 | | -------- | ---------------------------------------- | | 开发服务器运行中 | 从 Vite 开发服务器加载资源，启用 HMR | | 生产（已构建） | 读取 `public/build/manifest.json`，加载带版本的文件 | ## 配置 JavaScript / CSS 入口 ### JavaScript 配置 `resources/js/app.js` 是主入口，可以从这里再导入其他模块。 ```js theme={null} import './bootstrap'; import '../css/app.css'; // 导入自定义模块 import './components/modal'; import './utils/format'; ``` ### CSS 配置 `resources/css/app.css` 中写全局样式。 ```css theme={null} /* 使用 Tailwind CSS 时 */ @import 'tailwindcss'; /* 自定义样式 */ body { font-family: 'Noto Sans SC', sans-serif; } ``` ### 多个入口需要为管理后台等页面分别打包时，可以指定多个入口。 ```js theme={null} import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; export default defineConfig({ plugins: [ laravel([ 'resources/css/app.css', 'resources/js/app.js', 'resources/css/admin.css', 'resources/js/admin.js', ]), ], }); ``` Blade 中只加载对应入口。 ```blade theme={null} {{-- 后台布局 --}} @vite(['resources/css/admin.css', 'resources/js/admin.js']) ``` ## 与 Tailwind CSS 集成 Tailwind CSS v4 以后作为 Vite 插件集成。 ```shell theme={null} npm install tailwindcss @tailwindcss/vite ``` ```js theme={null} import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; import tailwindcss from '@tailwindcss/vite'; export default defineConfig({ plugins: [ tailwindcss(), laravel([ 'resources/css/app.css', 'resources/js/app.js', ]), ], }); ``` ```css theme={null} /* resources/css/app.css */ @import 'tailwindcss'; ``` 使用 Tailwind CSS v3 时需要 `tailwind.config.js` 与 `postcss.config.js`。而在最新的 Tailwind CSS v4 中这些文件都不再需要。 ## 别名配置 `laravel-vite-plugin` 自动配置了 `@` 别名，指向 `resources/js` 目录。 ```js theme={null} // 用别名导入 import UserCard from '@/components/UserCard.vue'; // 等同于 import UserCard from '/resources/js/components/UserCard.vue'; ``` 如需自定义别名，可以在 `resolve.alias` 中配置。 ```js theme={null} import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; import path from 'path'; export default defineConfig({ plugins: [ laravel(['resources/js/app.js']), ], resolve: { alias: { '@': '/resources/js', '@css': '/resources/css', '@images': '/resources/images', }, }, }); ``` 使用别名导入示例： ```js theme={null} import logo from '@images/logo.png'; import '@css/custom.css'; ``` ## 各框架的配置 ### Vue ```shell theme={null} npm install --save-dev @vitejs/plugin-vue ``` ```js theme={null} import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; import vue from '@vitejs/plugin-vue'; export default defineConfig({ plugins: [ laravel(['resources/js/app.js']), vue({ template: { transformAssetUrls: { base: null, includeAbsolute: false, }, }, }), ], }); ``` ### React ```shell theme={null} npm install --save-dev @vitejs/plugin-react ``` ```js theme={null} import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [ laravel(['resources/js/app.jsx']), react(), ], }); ``` 使用 React 时，需要在 Blade 模板中将 `@viteReactRefresh` 指令放在 `@vite` 之前。 ```blade theme={null} @viteReactRefresh @vite('resources/js/app.jsx') ``` ## 静态资源的处理 Blade 模板中引用的图片、字体也可以通过 Vite 版本化。用 `assets` 选项指定目录。 ```js theme={null} laravel({ input: 'resources/js/app.js', assets: ['resources/images/**', 'resources/fonts/**'], }) ``` Blade 模板中通过 `Vite::asset()` 获取带版本的 URL。 ```blade theme={null}

``` ## 小结 | 想做的事 | 方法 | | --------------- | --------------------------------------------------------- | | 启动开发服务器 | `npm run dev` | | 构建生产资源 | `npm run build` | | Blade 中加载资源 | `@vite(['resources/css/app.css', 'resources/js/app.js'])` | | Blade 视图变更自动刷新 | 在 `vite.config.js` 中设置 `refresh: true` | | 使用 Tailwind CSS | 添加 `@tailwindcss/vite` 插件 | | 使用 `@` 别名 | 默认指向 `resources/js` | | 静态资源版本化 | 使用 `assets` 选项和 `Vite::asset()` | ## 下一步了解如何使用 Laravel 的缓存能力进一步提升应用性能。 ## Related topics - [前端](/zh/frontend.md) - [打包 Copilot CLI](/zh/packages/laravel-copilot-sdk/bundle-cli.md) - [Eloquent API 资源](/zh/eloquent-resources.md) - [Laravel MCP](/zh/mcp.md) - [安装与配置 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/installation.md)