跳转到主要内容

​
Laravel 与 Vite

Vite 是一款高性能的前端构建工具。开发时提供即时反映改动的热模块替换（HMR），生产构建时生成经过优化的资源。 Laravel 9 以后 Vite 成为标准前端构建工具，通过 laravel-vite-plugin 与 Laravel 集成。这个插件的主要职责包括：
  • 管理入口文件
  • 提供开发服务器的 HMR 支持
  • 与 @vite() Blade 指令联动
  • 生产构建时对资源做版本化（缓存破坏）
如果你在使用 Laravel Breeze 等 Laravel 起步套件，Vite 和 Tailwind 的配置已经内置。本页介绍从零配置的做法。
想了解 Vite 在 Laravel 整体前端方案中的定位，可先看看前端一节的全景介绍。

​
安装与配置

​
检查 Node 是否安装

Vite 需要 Node.js（16 及以上）和 npm。可通过下面命令确认。 
node -v
npm -v

​
安装依赖

新装的 Laravel 项目 package.json 中已经包含 vite 与 laravel-vite-plugin。用下面的命令安装依赖。 
npm install

​
vite.config.js 配置

项目根目录会生成 vite.config.js。你需要在其中指定入口文件（打包入口）。 
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）。 
npm run dev
也可以与 Laravel 开发服务器一起启动。 
composer run dev
composer run dev 会同时启动 php artisan serve 和 npm run dev。

​
Blade 视图自动刷新

配置 refresh: true 后，保存 Blade 视图或路由文件时浏览器会自动刷新。 
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/。 
npm run build
构建后的目录结构示例： 
public/
  build/
    assets/
      app-Cv82Mlke.css
      app-DnAZBF4U.js
    manifest.json
manifest.json 记录了文件名和哈希的对应关系，@vite() 指令会读取它来加载正确的文件。
public/build/ 是构建产物，建议加入 .gitignore。可以在部署目标机器上构建，也可以在 CI 中构建后部署。

​
从 Blade 加载资源

在布局的 <head> 中加入 @vite() Blade 指令。 
<!DOCTYPE html>
<html lang="zh">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ config('app.name') }}</title>

    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    @yield('content')
</body>
</html>
如果 CSS 是从 JavaScript 中导入的，只需指定 JS 入口即可。 
@vite('resources/js/app.js')
@vite() 指令会根据开发和生产两种模式自动切换行为。
场景行为
开发服务器运行中从 Vite 开发服务器加载资源，启用 HMR
生产（已构建）读取 public/build/manifest.json，加载带版本的文件

​
配置 JavaScript / CSS 入口

​
JavaScript 配置

resources/js/app.js 是主入口，可以从这里再导入其他模块。 
import './bootstrap';
import '../css/app.css';

// 导入自定义模块
import './components/modal';
import './utils/format';

​
CSS 配置

resources/css/app.css 中写全局样式。 
/* 使用 Tailwind CSS 时 */
@import 'tailwindcss';

/* 自定义样式 */
body {
    font-family: 'Noto Sans SC', sans-serif;
}

​
多个入口

需要为管理后台等页面分别打包时，可以指定多个入口。 
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 中只加载对应入口。 
{{-- 后台布局 --}}
@vite(['resources/css/admin.css', 'resources/js/admin.js'])

​
与 Tailwind CSS 集成

Tailwind CSS v4 以后作为 Vite 插件集成。
1

安装 Tailwind

npm install tailwindcss @tailwindcss/vite
2

在 vite.config.js 中添加插件

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',
        ]),
    ],
});
3

在 CSS 中导入 Tailwind

/* resources/css/app.css */
@import 'tailwindcss';
使用 Tailwind CSS v3 时需要 tailwind.config.js 与 postcss.config.js。而在最新的 Tailwind CSS v4 中这些文件都不再需要。

​
别名配置

laravel-vite-plugin 自动配置了 @ 别名，指向 resources/js 目录。 
// 用别名导入
import UserCard from '@/components/UserCard.vue';
// 等同于
import UserCard from '/resources/js/components/UserCard.vue';
如需自定义别名，可以在 resolve.alias 中配置。 
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',
        },
    },
});
使用别名导入示例： 
import logo from '@images/logo.png';
import '@css/custom.css';

​
各框架的配置

​
Vue

npm install --save-dev @vitejs/plugin-vue

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

npm install --save-dev @vitejs/plugin-react

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 之前。 
@viteReactRefresh
@vite('resources/js/app.jsx')

​
静态资源的处理

Blade 模板中引用的图片、字体也可以通过 Vite 版本化。用 assets 选项指定目录。 
laravel({
    input: 'resources/js/app.js',
    assets: ['resources/images/**', 'resources/fonts/**'],
})
Blade 模板中通过 Vite::asset() 获取带版本的 URL。 
<img src="{{ Vite::asset('resources/images/logo.png') }}" alt="Logo">

​
小结

想做的事方法
启动开发服务器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 的缓存能力进一步提升应用性能。
最后修改于 2026年7月13日

相关主题

前端打包 Copilot CLIEloquent API 资源Laravel MCP安装与配置 - VOICEVOX for Laravel