laravel-vite

介绍如何将 Vite 用作 Laravel 前端构建工具：初始设置和 laravel-vite-plugin、多入口、CSS 预处理器（Sass/Less/PostCSS）、资源处理、带 VITE_ 前缀的环境变量、开发服务器和 HMR（包括 Docker 配置）、构建优化（分块、压缩）、服务端渲染、Inertia 集成、JS 框架插件（Vue/React/Svelte）、CSP nonce 安全性，以及生产环境部署。

Laravel Vite

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每个调用一个 Agent，并指定 name：

1. fuse-ai-pilot:explore-codebase - 检查现有的 vite.config.js、package.json
2. fuse-ai-pilot:research-expert - 通过 Context7 核实最新的 Vite 文档
3. mcp__context7__query-docs - 查询具体模式（SSR、Inertia）

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

Vite 是 Laravel 默认的前端构建工具。它可在开发过程中提供快速 HMR，并为生产环境生成经过优化的构建产物。

特性	用途
HMR	开发期间即时更新
打包	优化生产环境资源
SSR	支持服务端渲染
框架	集成 Vue、React、Svelte

---

重要规则

1. 始终使用 laravel-vite-plugin - 不要使用原生 Vite 配置
2. 环境变量使用 VITE_ 前缀 - 仅向前端公开
3. 使用 @vite 指令 - 不要手动编写 script 标签
4. 部署前先构建 - 在 CI/CD 中运行 npm run build
5. 为 Docker 配置 HMR - 设置 server.host: '0.0.0.0'

---

决策指南

技术栈选择

Using Tailwind CSS?
├── YES → v4? @tailwindcss/vite plugin
│         v3? PostCSS config
└── NO → Just laravel-vite-plugin

Using JavaScript framework?
├── Vue → @vitejs/plugin-vue
├── React → @vitejs/plugin-react
├── Svelte → @sveltejs/vite-plugin-svelte
└── None → Plain JS/CSS only

SSR 决策

Need SEO/fast first paint?
├── YES → Using Inertia?
│   ├── YES → Inertia SSR
│   └── NO → Consider Inertia or Livewire
└── NO → Client-side only

---

参考指南

概念（原因与架构）

主题	参考资料	何时查阅
设置	setup.md	初始配置
入口点	entry-points.md	多个打包产物
预处理器	preprocessors.md	Sass、Less、PostCSS
资源	assets.md	图片、字体、静态资源
环境	environment.md	VITE_ 变量
开发服务器	dev-server.md	HMR、Docker、HTTPS
构建	build-optimization.md	分块、压缩
SSR	ssr.md	服务端渲染
Inertia	inertia.md	无需 API 的 SPA
框架	frameworks.md	Vue、React、Svelte
安全性	security.md	CSP nonce
部署	deployment.md	生产环境、CDN

模板（完整代码）

模板	适用场景
ViteConfig.js.md	标准设置
ViteConfigAdvanced.js.md	完整优化
InertiaSetup.md	Inertia + Vue/React
SSRSetup.md	SSR 配置

---

快速参考

基本设置

// vite.config.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,
        }),
    ],
});

Blade 指令

<!DOCTYPE html>
<head>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

命令

命令	用途
npm run dev	启动开发服务器
npm run build	生产环境构建
npm run preview	预览构建产物

---

最佳实践

应该做

• 使用 refresh: true 实现 Blade HMR
• 配置别名，让导入路径更简洁
• 将供应商代码拆分到单独的分块中
• 为前端环境变量使用 VITE_ 前缀
• 在本地测试 Docker/Sail 配置

不应该做

• 通过 VITE_ 变量公开敏感数据
• 忘记在部署前进行构建
• 对资源使用绝对路径
• 在预发布环境中跳过源映射
• 忽略分块大小警告

Laravel 13 说明

Laravel 13 骨架自带 laravel-vite-plugin ^3.1（当前为 3.2，peer vite ^8）+ Vite 8 + @tailwindcss/vite ^4。相关调整：

• @vite() Blade 助手保持不变
• 对于 Inertia 3 + React 19：使用 @vitejs/plugin-react（当前为 6.x）
• 自托管字体（13.7+）：插件的 fonts 选项（import { google, bunny, fontsource, local } from 'laravel-vite-plugin/fonts'）+ @fonts Blade 指令
• 使用 Vite::devServerUrl()（13.31+）获取开发服务器 URL
• 通过 WebSocket 实现 HMR：开发环境中，Reverb 和 Vite 可以在不同端口上共存
• build.target 是浏览器（JS）目标，与服务器的 PHP 版本无关