使用 Vite 打包资源 - Knowledge of Laravel

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 插件集成。

安装 Tailwind

npm install tailwindcss @tailwindcss/vite

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

在 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 的缓存能力进一步提升应用性能。

​Laravel 与 Vite

​安装与配置

​检查 Node 是否安装

​安装依赖

​vite.config.js 配置

​启动开发服务器

​Blade 视图自动刷新

​生产构建

​从 Blade 加载资源

​配置 JavaScript / CSS 入口

​JavaScript 配置

​CSS 配置

​多个入口

​与 Tailwind CSS 集成

​别名配置

​各框架的配置

​Vue

​React

​静态资源的处理

​小结

​下一步

缓存

Laravel 与 Vite

安装与配置

检查 Node 是否安装

安装依赖

vite.config.js 配置

启动开发服务器

Blade 视图自动刷新

生产构建

从 Blade 加载资源

配置 JavaScript / CSS 入口

JavaScript 配置

CSS 配置

多个入口

与 Tailwind CSS 集成

别名配置

各框架的配置

Vue

React

静态资源的处理

小结

下一步