資源打包 (Vite)

簡介
安裝與設定
執行 Vite
使用 JavaScript
- 別名
- Vue
- React
- Inertia
- URL 處理
使用樣式表
使用 Blade 和路由
資源預先擷取
自訂基礎 URL
環境變數
在測試中停用 Vite
伺服器端渲染 (SSR)
腳本和樣式標籤屬性
進階自訂
- 開發伺服器跨來源資源共享 (CORS)
- 修正開發伺服器 URL

簡介

Vite 是一個現代化的前端建置工具，提供極快速的開發環境，並為生產環境打包您的程式碼。當使用 Laravel 建置應用程式時，您通常會使用 Vite 將應用程式的 CSS 和 JavaScript 檔案打包成可供生產環境使用的資源。

Laravel 透過提供官方外掛程式和 Blade 指令來載入您的開發和生產資源，與 Vite 無縫整合。

您正在執行 Laravel Mix 嗎？在新的 Laravel 安裝中，Vite 已取代 Laravel Mix。如需 Mix 文件，請造訪 Laravel Mix 網站。如果您想切換到 Vite，請參閱我們的遷移指南。

Vite 和 Laravel Mix 之間的選擇

在轉換到 Vite 之前，新的 Laravel 應用程式在打包資源時使用 Mix，後者由 webpack 驅動。Vite 專注於在建置豐富的 JavaScript 應用程式時提供更快、更有效率的體驗。如果您正在開發單頁應用程式 (SPA)，包括使用 Inertia 等工具開發的應用程式，Vite 將是完美的選擇。

Vite 也適用於具有 JavaScript「點綴」的傳統伺服器端渲染應用程式，包括使用 Livewire 的應用程式。但是，它缺少 Laravel Mix 支援的某些功能，例如將未在您的 JavaScript 應用程式中直接引用的任意資源複製到建置中的能力。

遷移回 Mix

您是否已使用我們的 Vite 骨架開始新的 Laravel 應用程式，但需要移回 Laravel Mix 和 webpack？沒問題。請參閱我們的從 Vite 遷移到 Mix 的官方指南。

安裝與設定

以下文件討論如何手動安裝和設定 Laravel Vite 外掛程式。但是，Laravel 的入門套件已經包含所有這些骨架，並且是開始使用 Laravel 和 Vite 的最快方法。

安裝 Node

您必須確保已安裝 Node.js (16+) 和 NPM，然後才能執行 Vite 和 Laravel 外掛程式

1node -v
2npm -v

node -v
npm -v

您可以使用來自官方 Node 網站的簡單圖形安裝程式輕鬆安裝最新版本的 Node 和 NPM。或者，如果您正在使用 Laravel Sail，您可以透過 Sail 呼叫 Node 和 NPM

1./vendor/bin/sail node -v
2./vendor/bin/sail npm -v

./vendor/bin/sail node -v
./vendor/bin/sail npm -v

安裝 Vite 和 Laravel 外掛程式

在全新的 Laravel 安裝中，您會在應用程式目錄結構的根目錄中找到一個 package.json 檔案。預設的 package.json 檔案已經包含開始使用 Vite 和 Laravel 外掛程式所需的一切。您可以透過 NPM 安裝應用程式的前端依賴項

1npm install

npm install

設定 Vite

Vite 是透過專案根目錄中的 vite.config.js 檔案設定的。您可以根據您的需求自由自訂此檔案，並且您也可以安裝您的應用程式所需的任何其他外掛程式，例如 @vitejs/plugin-vue 或 @vitejs/plugin-react。

Laravel Vite 外掛程式要求您指定應用程式的進入點。這些可以是 JavaScript 或 CSS 檔案，並包括預處理語言，例如 TypeScript、JSX、TSX 和 Sass。

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel([
 7            'resources/css/app.css',
 8            'resources/js/app.js',
 9        ]),
10    ],
11});

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 建置的應用程式，則 Vite 在沒有 CSS 進入點的情況下效果最佳

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel([
 7            'resources/css/app.css', 
 8            'resources/js/app.js',
 9        ]),
10    ],
11});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

相反地，您應該透過 JavaScript 匯入您的 CSS。通常，這會在您應用程式的 resources/js/app.js 檔案中完成

1import './bootstrap';
2import '../css/app.css'; 

import './bootstrap';
import '../css/app.css';

Laravel 外掛程式也支援多個進入點和進階設定選項，例如 SSR 進入點。

使用安全開發伺服器

如果您的本機開發 Web 伺服器透過 HTTPS 提供您的應用程式，您可能會遇到連線到 Vite 開發伺服器的問題。

如果您正在使用 Laravel Herd 並已保護網站安全，或者您正在使用 Laravel Valet 並已對您的應用程式執行 secure 命令，則 Laravel Vite 外掛程式將自動偵測並使用為您產生的 TLS 憑證。

如果您使用與應用程式目錄名稱不符的主機保護網站安全，您可以手動在您應用程式的 vite.config.js 檔案中指定主機

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel({
 7            // ...
 8            detectTls: 'my-app.test', 
 9        }),
10    ],
11});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            detectTls: 'my-app.test',
        }),
    ],
});

當使用另一個 Web 伺服器時，您應該產生受信任的憑證並手動設定 Vite 以使用產生的憑證

 1// ...
 2import fs from 'fs'; 
 3 
 4const host = 'my-app.test'; 
 5 
 6export default defineConfig({
 7    // ...
 8    server: { 
 9        host, 
10        hmr: { host }, 
11        https: { 
12            key: fs.readFileSync(`/path/to/${host}.key`), 
13            cert: fs.readFileSync(`/path/to/${host}.crt`), 
14        }, 
15    }, 
16});

// ...
import fs from 'fs';

const host = 'my-app.test';

export default defineConfig({
    // ...
    server: {
        host,
        hmr: { host },
        https: {
            key: fs.readFileSync(`/path/to/${host}.key`),
            cert: fs.readFileSync(`/path/to/${host}.crt`),
        },
    },
});

如果您無法為您的系統產生受信任的憑證，您可以安裝和設定 @vitejs/plugin-basic-ssl 外掛程式。當使用不受信任的憑證時，您需要在瀏覽器中接受 Vite 開發伺服器的憑證警告，方法是在執行 npm run dev 命令時，點擊主控台中的「本機」連結。

在 WSL2 上的 Sail 中執行開發伺服器

當在 Windows Subsystem for Linux 2 (WSL2) 上的 Laravel Sail 中執行 Vite 開發伺服器時，您應該將以下設定新增到您的 vite.config.js 檔案，以確保瀏覽器可以與開發伺服器通訊

 1// ...
 2 
 3export default defineConfig({
 4    // ...
 5    server: { 
 6        hmr: {
 7            host: 'localhost',
 8        },
 9    }, 
10});

// ...

export default defineConfig({
    // ...
    server: {
        hmr: {
            host: 'localhost',
        },
    },
});

如果在開發伺服器執行時，您的檔案變更未反映在瀏覽器中，您可能還需要設定 Vite 的 server.watch.usePolling 選項。

載入您的腳本和樣式

設定好您的 Vite 進入點後，您現在可以在 @vite() Blade 指令中參考它們，您將該指令新增到應用程式根模板的 <head> 中

1<!DOCTYPE html>
2<head>
3    {{-- ... --}}
4 
5    @vite(['resources/css/app.css', 'resources/js/app.js'])
6</head>

<!DOCTYPE html>
<head>
    {{-- ... --}}

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

如果您透過 JavaScript 匯入 CSS，您只需要包含 JavaScript 進入點

1<!DOCTYPE html>
2<head>
3    {{-- ... --}}
4 
5    @vite('resources/js/app.js')
6</head>

<!DOCTYPE html>
<head>
    {{-- ... --}}

    @vite('resources/js/app.js')
</head>

@vite 指令將自動偵測 Vite 開發伺服器並注入 Vite 客戶端以啟用熱模組替換。在建置模式下，指令將載入您編譯和版本化的資源，包括任何匯入的 CSS。

如果需要，您也可以在呼叫 @vite 指令時指定編譯資源的建置路徑

1<!doctype html>
2<head>
3    {{-- Given build path is relative to public path. --}}
4 
5    @vite('resources/js/app.js', 'vendor/courier/build')
6</head>

<!doctype html>
<head>
    {{-- Given build path is relative to public path. --}}

    @vite('resources/js/app.js', 'vendor/courier/build')
</head>

內嵌資源

有時可能需要包含資源的原始內容，而不是連結到資源的版本化 URL。例如，當將 HTML 內容傳遞到 PDF 產生器時，您可能需要直接將資源內容包含到您的頁面中。您可以使用 Vite facade 提供的 content 方法輸出 Vite 資源的內容

 1@use('Illuminate\Support\Facades\Vite')
 2 
 3<!doctype html>
 4<head>
 5    {{-- ... --}}
 6 
 7    <style>
 8        {!! Vite::content('resources/css/app.css') !!}
 9    </style>
10    <script>
11        {!! Vite::content('resources/js/app.js') !!}
12    </script>
13</head>

@use('Illuminate\Support\Facades\Vite')

<!doctype html>
<head>
    {{-- ... --}}

    <style>
        {!! Vite::content('resources/css/app.css') !!}
    </style>
    <script>
        {!! Vite::content('resources/js/app.js') !!}
    </script>
</head>

執行 Vite

您可以透過兩種方式執行 Vite。您可以透過 dev 命令執行開發伺服器，這在本地開發時很有用。開發伺服器將自動偵測您檔案的變更，並立即在任何開啟的瀏覽器視窗中反映這些變更。

或者，執行 build 命令將版本化和打包您的應用程式資源，並讓它們準備好部署到生產環境

1# Run the Vite development server...
2npm run dev
3 
4# Build and version the assets for production...
5npm run build

# Run the Vite development server...
npm run dev

# Build and version the assets for production...
npm run build

如果您在 WSL2 上的 Sail 中執行開發伺服器，您可能需要一些其他設定選項。

使用 JavaScript

別名

預設情況下，Laravel 外掛程式提供一個常用的別名，以協助您快速入門並方便地匯入應用程式的資源

1{
2    '@' => '/resources/js'
3}

{
    '@' => '/resources/js'
}

您可以透過將您自己的別名新增到 vite.config.js 設定檔案來覆寫 '@' 別名

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel(['resources/ts/app.tsx']),
 7    ],
 8    resolve: {
 9        alias: {
10            '@': '/resources/ts',
11        },
12    },
13});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel(['resources/ts/app.tsx']),
    ],
    resolve: {
        alias: {
            '@': '/resources/ts',
        },
    },
});

Vue

如果您想使用 Vue 框架建置您的前端，那麼您還需要安裝 @vitejs/plugin-vue 外掛程式

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

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

然後，您可以將外掛程式包含在您的 vite.config.js 設定檔案中。將 Vue 外掛程式與 Laravel 搭配使用時，您需要一些其他選項

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3import vue from '@vitejs/plugin-vue';
 4 
 5export default defineConfig({
 6    plugins: [
 7        laravel(['resources/js/app.js']),
 8        vue({
 9            template: {
10                transformAssetUrls: {
11                    // The Vue plugin will re-write asset URLs, when referenced
12                    // in Single File Components, to point to the Laravel web
13                    // server. Setting this to `null` allows the Laravel plugin
14                    // to instead re-write asset URLs to point to the Vite
15                    // server instead.
16                    base: null,
17 
18                    // The Vue plugin will parse absolute URLs and treat them
19                    // as absolute paths to files on disk. Setting this to
20                    // `false` will leave absolute URLs un-touched so they can
21                    // reference assets in the public directory as expected.
22                    includeAbsolute: false,
23                },
24            },
25        }),
26    ],
27});

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: {
                    // The Vue plugin will re-write asset URLs, when referenced
                    // in Single File Components, to point to the Laravel web
                    // server. Setting this to `null` allows the Laravel plugin
                    // to instead re-write asset URLs to point to the Vite
                    // server instead.
                    base: null,

                    // The Vue plugin will parse absolute URLs and treat them
                    // as absolute paths to files on disk. Setting this to
                    // `false` will leave absolute URLs un-touched so they can
                    // reference assets in the public directory as expected.
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

Laravel 的入門套件已經包含適當的 Laravel、Vue 和 Vite 設定。這些入門套件提供開始使用 Laravel、Vue 和 Vite 的最快方法。

React

如果您想使用 React 框架建置您的前端，那麼您還需要安裝 @vitejs/plugin-react 外掛程式

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

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

然後，您可以將外掛程式包含在您的 vite.config.js 設定檔案中

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3import react from '@vitejs/plugin-react';
 4 
 5export default defineConfig({
 6    plugins: [
 7        laravel(['resources/js/app.jsx']),
 8        react(),
 9    ],
10});

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

您需要確保任何包含 JSX 的檔案都具有 .jsx 或 .tsx 擴展名，並記住更新您的進入點（如果需要），如上面所示。

您還需要將額外的 @viteReactRefresh Blade 指令與您現有的 @vite 指令一起包含在內。

1@viteReactRefresh
2@vite('resources/js/app.jsx')

@viteReactRefresh
@vite('resources/js/app.jsx')

@viteReactRefresh 指令必須在 @vite 指令之前呼叫。

Laravel 的入門套件已經包含適當的 Laravel、React 和 Vite 設定。這些入門套件提供開始使用 Laravel、React 和 Vite 的最快方法。

Inertia

Laravel Vite 外掛程式提供了一個方便的 resolvePageComponent 函式，以協助您解析您的 Inertia 頁面組件。以下是在 Vue 3 中使用輔助函式的範例；但是，您也可以在其他框架（例如 React）中使用該函式

 1import { createApp, h } from 'vue';
 2import { createInertiaApp } from '@inertiajs/vue3';
 3import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
 4 
 5createInertiaApp({
 6  resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),
 7  setup({ el, App, props, plugin }) {
 8    createApp({ render: () => h(App, props) })
 9      .use(plugin)
10      .mount(el)
11  },
12});

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';

createInertiaApp({
  resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .mount(el)
  },
});

如果您將 Vite 的程式碼分割功能與 Inertia 搭配使用，我們建議設定資源預先擷取。

Laravel 的入門套件已經包含適當的 Laravel、Inertia 和 Vite 設定。這些入門套件提供開始使用 Laravel、Inertia 和 Vite 的最快方法。

當使用 Vite 並在應用程式的 HTML、CSS 或 JS 中參考資源時，有幾個注意事項需要考慮。首先，如果您使用絕對路徑參考資源，Vite 將不會將該資源包含在建置中；因此，您應確保該資源在您的 public 目錄中可用。當使用專用的 CSS 進入點時，您應避免使用絕對路徑，因為在開發期間，瀏覽器將嘗試從 Vite 開發伺服器（CSS 託管的位置）而不是從您的 public 目錄載入這些路徑。

當參考相對資源路徑時，您應該記住路徑是相對於參考它們的檔案而言的。任何透過相對路徑參考的資源都將由 Vite 重新寫入、版本化和打包。

考慮以下專案結構

1public/
2  taylor.png
3resources/
4  js/
5    Pages/
6      Welcome.vue
7  images/
8    abigail.png

public/
  taylor.png
resources/
  js/
    Pages/
      Welcome.vue
  images/
    abigail.png

以下範例示範 Vite 將如何處理相對和絕對 URL

1<!-- This asset is not handled by Vite and will not be included in the build -->
2<img src="/taylor.png">
3 
4<!-- This asset will be re-written, versioned, and bundled by Vite -->
5<img src="../../images/abigail.png">

<!-- This asset is not handled by Vite and will not be included in the build -->
<img src="/taylor.png">

<!-- This asset will be re-written, versioned, and bundled by Vite -->
<img src="../../images/abigail.png">

使用樣式表

您可以在 Vite 文件中瞭解更多關於 Vite 的 CSS 支援。如果您正在使用 PostCSS 外掛程式，例如 Tailwind，您可以在專案的根目錄中建立一個 postcss.config.js 檔案，Vite 將自動應用它

1export default {
2    plugins: {
3        tailwindcss: {},
4        autoprefixer: {},
5    },
6};

export default {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};

Laravel 的入門套件已經包含適當的 Tailwind、PostCSS 和 Vite 設定。或者，如果您想在不使用我們的入門套件之一的情況下使用 Tailwind 和 Laravel，請查看 Tailwind 的 Laravel 安裝指南。

使用 Blade 和路由

使用 Vite 處理靜態資源

當在 JavaScript 或 CSS 中參考資源時，Vite 會自動處理並版本化它們。此外，在建置基於 Blade 的應用程式時，Vite 也可以處理和版本化您僅在 Blade 模板中參考的靜態資源。

但是，為了實現此目的，您需要透過將靜態資源匯入應用程式的進入點來讓 Vite 知道您的資源。例如，如果您想處理和版本化儲存在 resources/images 中的所有圖片和儲存在 resources/fonts 中的所有字體，您應該在應用程式的 resources/js/app.js 進入點中新增以下內容

1import.meta.glob([
2  '../images/**',
3  '../fonts/**',
4]);

import.meta.glob([
  '../images/**',
  '../fonts/**',
]);

這些資源現在將在執行 npm run build 時由 Vite 處理。然後，您可以使用 Vite::asset 方法在 Blade 模板中參考這些資源，該方法將傳回給定資源的版本化 URL

1<img src="{{ Vite::asset('resources/images/logo.png') }}">

<img src="{{ Vite::asset('resources/images/logo.png') }}">

儲存時重新整理

當您的應用程式使用傳統的伺服器端渲染與 Blade 建置時，Vite 可以透過在您變更應用程式中的視圖檔案時自動重新整理瀏覽器來改善您的開發工作流程。若要開始使用，您只需將 refresh 選項指定為 true 即可。

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel({
 7            // ...
 8            refresh: true,
 9        }),
10    ],
11});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: true,
        }),
    ],
});

當 refresh 選項為 true 時，儲存以下目錄中的檔案將觸發瀏覽器在您執行 npm run dev 時執行完整頁面重新整理

app/Livewire/**
app/View/Components/**
lang/**
resources/lang/**
resources/views/**
routes/**

如果您正在使用 Ziggy 在應用程式的前端中產生路由連結，則監看 routes/** 目錄很有用。

如果這些預設路徑不符合您的需求，您可以指定您自己的監看路徑清單

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel({
 7            // ...
 8            refresh: ['resources/views/**'],
 9        }),
10    ],
11});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: ['resources/views/**'],
        }),
    ],
});

在幕後，Laravel Vite 外掛程式使用 vite-plugin-full-reload 套件，該套件提供了一些進階設定選項來微調此功能的行為。如果您需要此層級的自訂，您可以提供 config 定義

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel({
 7            // ...
 8            refresh: [{
 9                paths: ['path/to/watch/**'],
10                config: { delay: 300 }
11            }],
12        }),
13    ],
14});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: [{
                paths: ['path/to/watch/**'],
                config: { delay: 300 }
            }],
        }),
    ],
});

別名

在 JavaScript 應用程式中，建立別名到經常參考的目錄很常見。但是，您也可以透過在 Illuminate\Support\Facades\Vite 類別上使用 macro 方法來建立在 Blade 中使用的別名。通常，「巨集」應在服務提供者的 boot 方法中定義

1/**
2 * Bootstrap any application services.
3 */
4public function boot(): void
5{
6    Vite::macro('image', fn (string $asset) => $this->asset("resources/images/{$asset}"));
7}

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Vite::macro('image', fn (string $asset) => $this->asset("resources/images/{$asset}"));
}

一旦定義了巨集，就可以在您的模板中呼叫它。例如，我們可以使用上面定義的 image 巨集來參考位於 resources/images/logo.png 的資源

1<img src="{{ Vite::image('logo.png') }}" alt="Laravel Logo">

<img src="{{ Vite::image('logo.png') }}" alt="Laravel Logo">

資源預先擷取

當使用 Vite 的程式碼分割功能建置 SPA 時，每次頁面導航都會擷取所需的資源。此行為可能會導致 UI 渲染延遲。如果這對您選擇的前端框架來說是一個問題，Laravel 提供了在初始頁面載入時急切地預先擷取應用程式 JavaScript 和 CSS 資源的功能。

您可以指示 Laravel 急切地預先擷取您的資源，方法是在服務提供者的 boot 方法中呼叫 Vite::prefetch 方法

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Support\Facades\Vite;
 6use Illuminate\Support\ServiceProvider;
 7 
 8class AppServiceProvider extends ServiceProvider
 9{
10    /**
11     * Register any application services.
12     */
13    public function register(): void
14    {
15        // ...
16    }
17 
18    /**
19     * Bootstrap any application services.
20     */
21    public function boot(): void
22    {
23        Vite::prefetch(concurrency: 3);
24    }
25}

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Vite;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        // ...
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Vite::prefetch(concurrency: 3);
    }
}

在上面的範例中，資源將在每次頁面載入時以最多 3 個並行下載預先擷取。您可以修改並行性以符合您的應用程式需求，或者如果應用程式應一次下載所有資源，則可以指定無並行性限制

1/**
2 * Bootstrap any application services.
3 */
4public function boot(): void
5{
6    Vite::prefetch();
7}

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Vite::prefetch();
}

預設情況下，預先擷取將在頁面載入事件觸發時開始。如果您想自訂預先擷取開始的時間，您可以指定 Vite 將監聽的事件

1/**
2 * Bootstrap any application services.
3 */
4public function boot(): void
5{
6    Vite::prefetch(event: 'vite:prefetch');
7}

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Vite::prefetch(event: 'vite:prefetch');
}

鑑於上面的程式碼，預先擷取現在將在您在 window 物件上手動分派 vite:prefetch 事件時開始。例如，您可以讓預先擷取在頁面載入三秒後開始

1<script>
2    addEventListener('load', () => setTimeout(() => {
3        dispatchEvent(new Event('vite:prefetch'))
4    }, 3000))
5</script>

<script>
    addEventListener('load', () => setTimeout(() => {
        dispatchEvent(new Event('vite:prefetch'))
    }, 3000))
</script>

自訂基礎 URL

如果您的 Vite 編譯資源部署到與您的應用程式不同的網域（例如透過 CDN），您必須在應用程式的 .env 檔案中指定 ASSET_URL 環境變數

1ASSET_URL=https://cdn.example.com

ASSET_URL=https://cdn.example.com

設定資源 URL 後，所有重新寫入到您的資源的 URL 都將以設定的值作為前綴

1https://cdn.example.com/build/assets/app.9dce8d17.js

https://cdn.example.com/build/assets/app.9dce8d17.js

請記住，絕對 URL 不會被 Vite 重新寫入，因此它們不會被加上前綴。

環境變數

您可以透過在應用程式的 .env 檔案中以 VITE_ 作為前綴，將環境變數注入到您的 JavaScript 中

1VITE_SENTRY_DSN_PUBLIC=http://example.com

VITE_SENTRY_DSN_PUBLIC=http://example.com

您可以透過 import.meta.env 物件存取注入的環境變數

1import.meta.env.VITE_SENTRY_DSN_PUBLIC

import.meta.env.VITE_SENTRY_DSN_PUBLIC

在測試中停用 Vite

Laravel 的 Vite 整合將嘗試在執行測試時解析您的資源，這需要您執行 Vite 開發伺服器或建置您的資源。

如果您希望在測試期間模擬 Vite，您可以呼叫 withoutVite 方法，該方法適用於任何擴展 Laravel 的 TestCase 類別的測試

1test('without vite example', function () {
2    $this->withoutVite();
3 
4    // ...
5});

test('without vite example', function () {
    $this->withoutVite();

    // ...
});

 1use Tests\TestCase;
 2 
 3class ExampleTest extends TestCase
 4{
 5    public function test_without_vite_example(): void
 6    {
 7        $this->withoutVite();
 8 
 9        // ...
10    }
11}

use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function test_without_vite_example(): void
    {
        $this->withoutVite();

        // ...
    }
}

如果您想為所有測試停用 Vite，您可以從基本 TestCase 類別的 setUp 方法中呼叫 withoutVite 方法

 1<?php
 2 
 3namespace Tests;
 4 
 5use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
 6 
 7abstract class TestCase extends BaseTestCase
 8{
 9    protected function setUp(): void
10    {
11        parent::setUp();
12 
13        $this->withoutVite();
14    }
15}

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        $this->withoutVite();
    }
}

伺服器端渲染 (SSR)

Laravel Vite 外掛程式讓使用 Vite 設定伺服器端渲染變得輕鬆。若要開始使用，請在 resources/js/ssr.js 建立一個 SSR 進入點，並透過將設定選項傳遞到 Laravel 外掛程式來指定進入點

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel({
 7            input: 'resources/js/app.js',
 8            ssr: 'resources/js/ssr.js',
 9        }),
10    ],
11});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            ssr: 'resources/js/ssr.js',
        }),
    ],
});

為了確保您不會忘記重建 SSR 進入點，我們建議擴充應用程式 package.json 中的「build」腳本，以建立您的 SSR 建置

1"scripts": {
2     "dev": "vite",
3     "build": "vite build" 
4     "build": "vite build && vite build --ssr" 
5}

"scripts": {
     "dev": "vite",
     "build": "vite build"
     "build": "vite build && vite build --ssr"
}

然後，若要建置和啟動 SSR 伺服器，您可以執行以下命令

1npm run build
2node bootstrap/ssr/ssr.js

npm run build
node bootstrap/ssr/ssr.js

如果您正在使用 Inertia 的 SSR，您可以改用 inertia:start-ssr Artisan 命令來啟動 SSR 伺服器

1php artisan inertia:start-ssr

php artisan inertia:start-ssr

Laravel 的入門套件已經包含適當的 Laravel、Inertia SSR 和 Vite 設定。這些入門套件提供開始使用 Laravel、Inertia SSR 和 Vite 的最快方法。

腳本和樣式標籤屬性

內容安全策略 (CSP) Nonce

如果您希望在您的腳本和樣式標籤上包含 nonce 屬性，作為您的內容安全策略的一部分，您可以使用自訂中介層中的 useCspNonce 方法產生或指定 nonce

 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6use Illuminate\Http\Request;
 7use Illuminate\Support\Facades\Vite;
 8use Symfony\Component\HttpFoundation\Response;
 9 
10class AddContentSecurityPolicyHeaders
11{
12    /**
13     * Handle an incoming request.
14     *
15     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
16     */
17    public function handle(Request $request, Closure $next): Response
18    {
19        Vite::useCspNonce();
20 
21        return $next($request)->withHeaders([
22            'Content-Security-Policy' => "script-src 'nonce-".Vite::cspNonce()."'",
23        ]);
24    }
25}

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Vite;
use Symfony\Component\HttpFoundation\Response;

class AddContentSecurityPolicyHeaders
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        Vite::useCspNonce();

        return $next($request)->withHeaders([
            'Content-Security-Policy' => "script-src 'nonce-".Vite::cspNonce()."'",
        ]);
    }
}

在呼叫 useCspNonce 方法後，Laravel 將自動在所有產生的腳本和樣式標籤上包含 nonce 屬性。

如果您需要在其他地方指定 nonce，包括 Laravel 的入門套件中包含的 Ziggy @route 指令，您可以使用 cspNonce 方法檢索它

1@routes(nonce: Vite::cspNonce())

@routes(nonce: Vite::cspNonce())

如果您已經有一個您想指示 Laravel 使用的 nonce，您可以將 nonce 傳遞到 useCspNonce 方法

1Vite::useCspNonce($nonce);

Vite::useCspNonce($nonce);

子資源完整性 (SRI)

如果您的 Vite manifest 包含資源的 integrity 雜湊，Laravel 將自動在它產生的任何腳本和樣式標籤上新增 integrity 屬性，以強制執行子資源完整性。預設情況下，Vite 不會在 manifest 中包含 integrity 雜湊，但您可以透過安裝 vite-plugin-manifest-sri NPM 外掛程式來啟用它

1npm install --save-dev vite-plugin-manifest-sri

npm install --save-dev vite-plugin-manifest-sri

然後，您可以在您的 vite.config.js 檔案中啟用此外掛程式

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3import manifestSRI from 'vite-plugin-manifest-sri';
 4 
 5export default defineConfig({
 6    plugins: [
 7        laravel({
 8            // ...
 9        }),
10        manifestSRI(),
11    ],
12});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import manifestSRI from 'vite-plugin-manifest-sri';

export default defineConfig({
    plugins: [
        laravel({
            // ...
        }),
        manifestSRI(),
    ],
});

如果需要，您也可以自訂可以在其中找到完整性雜湊的 manifest 金鑰

1use Illuminate\Support\Facades\Vite;
2 
3Vite::useIntegrityKey('custom-integrity-key');

use Illuminate\Support\Facades\Vite;

Vite::useIntegrityKey('custom-integrity-key');

如果您想完全停用此自動偵測，您可以將 false 傳遞到 useIntegrityKey 方法

1Vite::useIntegrityKey(false);

Vite::useIntegrityKey(false);

任意屬性

如果您需要在您的腳本和樣式標籤上包含其他屬性，例如 data-turbo-track 屬性，您可以透過 useScriptTagAttributes 和 useStyleTagAttributes 方法指定它們。通常，此方法應從服務提供者呼叫

 1use Illuminate\Support\Facades\Vite;
 2 
 3Vite::useScriptTagAttributes([
 4    'data-turbo-track' => 'reload', // Specify a value for the attribute...
 5    'async' => true, // Specify an attribute without a value...
 6    'integrity' => false, // Exclude an attribute that would otherwise be included...
 7]);
 8 
 9Vite::useStyleTagAttributes([
10    'data-turbo-track' => 'reload',
11]);

use Illuminate\Support\Facades\Vite;

Vite::useScriptTagAttributes([
    'data-turbo-track' => 'reload', // Specify a value for the attribute...
    'async' => true, // Specify an attribute without a value...
    'integrity' => false, // Exclude an attribute that would otherwise be included...
]);

Vite::useStyleTagAttributes([
    'data-turbo-track' => 'reload',
]);

如果您需要有條件地新增屬性，您可以傳遞一個回呼，該回呼將接收資源來源路徑、其 URL、其 manifest chunk 和整個 manifest

1use Illuminate\Support\Facades\Vite;
2 
3Vite::useScriptTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
4    'data-turbo-track' => $src === 'resources/js/app.js' ? 'reload' : false,
5]);
6 
7Vite::useStyleTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
8    'data-turbo-track' => $chunk && $chunk['isEntry'] ? 'reload' : false,
9]);

use Illuminate\Support\Facades\Vite;

Vite::useScriptTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $src === 'resources/js/app.js' ? 'reload' : false,
]);

Vite::useStyleTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $chunk && $chunk['isEntry'] ? 'reload' : false,
]);

當 Vite 開發伺服器正在執行時，$chunk 和 $manifest 引數將為 null。

進階自訂

開箱即用，Laravel 的 Vite 外掛程式使用合理的慣例，這些慣例應該適用於大多數應用程式；但是，有時您可能需要自訂 Vite 的行為。為了啟用其他自訂選項，我們提供以下方法和選項，這些方法和選項可以取代 @vite Blade 指令使用

 1<!doctype html>
 2<head>
 3    {{-- ... --}}
 4 
 5    {{
 6        Vite::useHotFile(storage_path('vite.hot')) // Customize the "hot" file...
 7            ->useBuildDirectory('bundle') // Customize the build directory...
 8            ->useManifestFilename('assets.json') // Customize the manifest filename...
 9            ->withEntryPoints(['resources/js/app.js']) // Specify the entry points...
10            ->createAssetPathsUsing(function (string $path, ?bool $secure) { // Customize the backend path generation for built assets...
11                return "https://cdn.example.com/{$path}";
12            })
13    }}
14</head>

<!doctype html>
<head>
    {{-- ... --}}

    {{
        Vite::useHotFile(storage_path('vite.hot')) // Customize the "hot" file...
            ->useBuildDirectory('bundle') // Customize the build directory...
            ->useManifestFilename('assets.json') // Customize the manifest filename...
            ->withEntryPoints(['resources/js/app.js']) // Specify the entry points...
            ->createAssetPathsUsing(function (string $path, ?bool $secure) { // Customize the backend path generation for built assets...
                return "https://cdn.example.com/{$path}";
            })
    }}
</head>

在 vite.config.js 檔案中，您應該指定相同的設定

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel({
 7            hotFile: 'storage/vite.hot', // Customize the "hot" file...
 8            buildDirectory: 'bundle', // Customize the build directory...
 9            input: ['resources/js/app.js'], // Specify the entry points...
10        }),
11    ],
12    build: {
13      manifest: 'assets.json', // Customize the manifest filename...
14    },
15});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            hotFile: 'storage/vite.hot', // Customize the "hot" file...
            buildDirectory: 'bundle', // Customize the build directory...
            input: ['resources/js/app.js'], // Specify the entry points...
        }),
    ],
    build: {
      manifest: 'assets.json', // Customize the manifest filename...
    },
});

開發伺服器跨來源資源共享 (CORS)

如果您在從 Vite 開發伺服器擷取資源時遇到瀏覽器中的跨來源資源共享 (CORS) 問題，您可能需要授與您的自訂來源存取開發伺服器的權限。Vite 與 Laravel 外掛程式結合使用，允許以下來源，而無需任何其他設定

::1
127.0.0.1
localhost
*.test
*.localhost
專案 .env 中的 APP_URL

允許專案的自訂來源的最簡單方法是確保您的應用程式的 APP_URL 環境變數與您在瀏覽器中造訪的來源相符。例如，如果您造訪 https://my-app.laravel，您應該更新您的 .env 以符合

1APP_URL=https://my-app.laravel

APP_URL=https://my-app.laravel

如果您需要更精細地控制來源（例如支援多個來源），您應該使用 Vite 全面且彈性的內建 CORS 伺服器設定。例如，您可以在專案 vite.config.js 檔案的 server.cors.origin 設定選項中指定多個來源

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel({
 7            input: 'resources/js/app.js',
 8            refresh: true,
 9        }),
10    ],
11    server: {  
12        cors: {  
13            origin: [  
14                'https://backend.laravel',  
15                'http://admin.laravel:8566',  
16            ],  
17        },  
18    },  
19});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            refresh: true,
        }),
    ],
    server: {
        cors: {
            origin: [
                'https://backend.laravel',
                'http://admin.laravel:8566',
            ],
        },
    },
});

您也可以包含 regex 模式，如果您想允許給定頂層網域的所有來源（例如 *.laravel），這可能會很有用

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3 
 4export default defineConfig({
 5    plugins: [
 6        laravel({
 7            input: 'resources/js/app.js',
 8            refresh: true,
 9        }),
10    ],
11    server: {  
12        cors: {  
13            origin: [ 
14                // Supports: SCHEME://DOMAIN.laravel[:PORT] 
15                /^https?:\/\/.*\.laravel(:\d+)?$/, 
16            ], 
17        }, 
18    }, 
19});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            refresh: true,
        }),
    ],
    server: {
        cors: {
            origin: [
                // Supports: SCHEME://DOMAIN.laravel[:PORT]
                /^https?:\/\/.*\.laravel(:\d+)?$/,
            ],
        },
    },
});

修正開發伺服器 URL

Vite 生態系統中的某些外掛程式假設以正斜線開頭的 URL 將始終指向 Vite 開發伺服器。但是，由於 Laravel 整合的性質，情況並非如此。

例如，vite-imagetools 外掛程式在 Vite 提供您的資源時輸出如下 URL

1<img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

<img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

vite-imagetools 外掛程式預期輸出 URL 將被 Vite 攔截，並且外掛程式可以處理所有以 /@imagetools 開頭的 URL。如果您正在使用預期此行為的外掛程式，您將需要手動修正 URL。您可以使用 transformOnServe 選項在您的 vite.config.js 檔案中執行此操作。

在此特定範例中，我們將開發伺服器 URL 前置到產生的程式碼中所有出現的 /@imagetools

 1import { defineConfig } from 'vite';
 2import laravel from 'laravel-vite-plugin';
 3import { imagetools } from 'vite-imagetools';
 4 
 5export default defineConfig({
 6    plugins: [
 7        laravel({
 8            // ...
 9            transformOnServe: (code, devServerUrl) => code.replaceAll('/@imagetools', devServerUrl+'/@imagetools'),
10        }),
11        imagetools(),
12    ],
13});

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { imagetools } from 'vite-imagetools';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            transformOnServe: (code, devServerUrl) => code.replaceAll('/@imagetools', devServerUrl+'/@imagetools'),
        }),
        imagetools(),
    ],
});

現在，當 Vite 提供資源時，它將輸出指向 Vite 開發伺服器的 URL

1- <img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">
2+ <img src="http://[::1]:5173/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

- <img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">
+ <img src="http://[::1]:5173/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

前言

開始使用

架構概念

基礎

深入探討

安全性

資料庫

Eloquent ORM

測試

套件

資源打包 (Vite)

產品

套件

資源