AssetMapper：簡單、現代的 CSS & JS 管理

在開發環境與生產環境中提供資源

在 `dev` 環境中，URL `/assets/images/duck-3c16d92m.png` 由您的 Symfony 應用程式處理並傳回。

對於 `prod` 環境，在部署之前，您應該執行

1

$ php bin/console asset-map:compile

這會將所有檔案從您對應的目錄實際複製到 `public/assets/`，以便它們由您的 Web 伺服器直接提供。如需更多詳細資訊，請參閱 部署。

除錯：查看所有已對應的資源

若要查看應用程式中所有已對應的資源，請執行

1

$ php bin/console debug:asset-map

這會顯示所有已對應的路徑以及每個路徑內的資源

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

AssetMapper Paths
------------------

--------- ------------------
 Path      Namespace prefix
--------- ------------------
assets

Mapped Assets
-------------

------------------ ----------------------------------------------------
 Logical Path       Filesystem Path
------------------ ----------------------------------------------------
 app.js             assets/app.js
 styles/app.css     assets/styles/app.css
 images/duck.png    assets/images/duck.png

「邏輯路徑」是在參考資源時要使用的路徑，例如從範本。

`debug:asset-map` 命令提供數個選項來篩選結果

1
2
3
4
5
6
7
8
9
10
11
12
13

# provide an asset name or dir to only show results that match it
$ php bin/console debug:asset-map bootstrap.js
$ php bin/console debug:asset-map style/

# provide an extension to only show that file type
$ php bin/console debug:asset-map --ext=css

# you can also only show assets in vendor/ dir or exclude any results from it
$ php bin/console debug:asset-map --vendor
$ php bin/console debug:asset-map --no-vendor

# you can also combine all filters (e.g. find bold web fonts in your own asset dirs)
$ php bin/console debug:asset-map bold --no-vendor --ext=woff2

匯入第三方 JavaScript 套件

假設您想要使用 npm 套件，例如 bootstrap。從技術上來說，這可以透過匯入其完整 URL 來完成，例如從 CDN

1

import { Alert } from 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/+esm';

但是，糟了！需要包含該 URL 很麻煩！相反地，我們可以透過 `importmap:require` 命令將此套件新增到我們的「importmap」。此命令可用於新增任何 npm 套件

1

$ php bin/console importmap:require bootstrap

這會將 `bootstrap` 套件新增到您的 `importmap.php` 檔案

1
2
3
4
5
6
7
8
9
10

// importmap.php
return [
    'app' => [
        'path' => './assets/app.js',
        'entrypoint' => true,
    ],
    'bootstrap' => [
        'version' => '5.3.0',
    ],
];

現在您可以像平常一樣匯入 `bootstrap` 套件

1
2

import { Alert } from 'bootstrap';
// ...

`importmap.php` 中的所有套件都會下載到 `assets/vendor/` 目錄中，該目錄應由 git 忽略（Flex recipe 會將其新增到 `.gitignore` 給您）。如果遺失某些檔案，您需要執行以下命令才能在其他電腦上下載檔案

1

$ php bin/console importmap:install

您可以執行以下命令，將您的第三方套件更新到其目前版本

1
2
3
4
5
6
7
8

# lists outdated packages and shows their latest versions
$ php bin/console importmap:outdated
# updates all the outdated packages
$ php bin/console importmap:update

# you can also run the commands only for the given list of packages
$ php bin/console importmap:update bootstrap lodash
$ php bin/console importmap:outdated bootstrap lodash

importmap 如何運作？

此 `importmap.php` 檔案如何讓您匯入 `bootstrap`？這要歸功於 `base.html.twig` 中的 `{{ importmap() }}` Twig 函數，它會輸出 importmap

1
2
3
4
5
6
7

<script type="importmap">{
    "imports": {
        "app": "/assets/app-4e986c1a.js",
        "/assets/duck.js": "/assets/duck-1b7a64b3.js",
        "bootstrap": "/assets/vendor/bootstrap/bootstrap.index-f093544d.js"
    }
}</script>

Import map 是原生瀏覽器功能。當您從 JavaScript 匯入 `bootstrap` 時，瀏覽器會查看 `importmap`，並發現它應該從關聯的路徑擷取套件。

但是 `/assets/duck.js` 匯入項目從何而來？它並不存在於 `importmap.php` 中。問得好！

上面的 `assets/app.js` 檔案匯入 `./duck.js`。當您使用相對路徑匯入檔案時，您的瀏覽器會尋找相對於匯入檔案的檔案。因此，它會尋找 `/assets/duck.js`。該 URL 會是正確的，除了 `duck.js` 檔案已進行版本控制。幸運的是，AssetMapper 組件會看到匯入，並新增從 `/assets/duck.js` 到正確、已版本控制的檔案名稱的對應。結果：匯入 `./duck.js` 就能正常運作！

`importmap()` 函數也會輸出 ES module shim，以便 較舊的瀏覽器 能夠理解 importmap（請參閱 polyfill 組態）。

「app」進入點 & 預先載入

「進入點」是瀏覽器載入的主要 JavaScript 檔案，您的應用程式預設會從一個進入點開始

1
2
3
4
5
6
7
8

// importmap.php
return [
    'app' => [
        'path' => './assets/app.js',
        'entrypoint' => true,
    ],
    // ...
];

除了 importmap 之外，`base.html.twig` 中的 `{{ importmap('app') }}` 還會輸出其他一些項目，包括

1

<script type="module">import 'app';</script>

此行指示瀏覽器載入 `app` importmap 項目，這會導致執行 `assets/app.js` 中的程式碼。

`importmap()` 函數也會輸出一組「預先載入」

1
2

<link rel="modulepreload" href="/assets/app-4e986c1a.js">
<link rel="modulepreload" href="/assets/duck-1b7a64b3.js">

這是一種效能最佳化，您可以在下方的 效能：新增預先載入中深入瞭解。

從第三方套件匯入特定檔案

有時您需要從套件匯入特定檔案。例如，假設您正在整合 highlight.js，並且只想匯入核心和特定語言

1
2
3
4
5

import hljs from 'highlight.js/lib/core';
import javascript from 'highlight.js/lib/languages/javascript';

hljs.registerLanguage('javascript', javascript);
hljs.highlightAll();

在這種情況下，將 `highlight.js` 套件新增到您的 `importmap.php` 檔案將無法運作：無論您匯入什麼 - 例如 `highlight.js/lib/core` - 都需要與 `importmap.php` 檔案中的項目完全相符。

請改用 `importmap:require` 並將您需要的確切路徑傳遞給它。這也示範了如何一次要求多個套件

1

$ php bin/console importmap:require highlight.js/lib/core highlight.js/lib/languages/javascript

全域變數，例如 jQuery

您可能習慣依賴全域變數 - 例如 jQuery 的 `$` 變數

1
2
3
4
5

// assets/app.js
import 'jquery';

// app.js or any other file
$('.something').hide(); // WILL NOT WORK!

但在模組環境中（例如使用 AssetMapper），當您匯入程式庫（例如 `jquery`）時，它不會建立全域變數。相反地，您應該在每個需要它的檔案中匯入它並將其設定為變數

1
2

import $ from 'jquery';
$('.something').hide();

您甚至可以從內嵌 script 標籤執行此操作

1
2
3
4

<script type="module">
    import $ from 'jquery';
    $('.something').hide();
</script>

如果您確實需要將某些項目變成全域變數，您可以從 `app.js` 內部手動執行此操作

1
2
3

import $ from 'jquery';
// things on "window" become global variables
window.$ = $;

處理第三方 CSS

有時，JavaScript 套件會包含一個或多個 CSS 檔案。例如，`bootstrap` 套件具有 dist/css/bootstrap.min.css 檔案。

您可以像 JavaScript 檔案一樣要求 CSS 檔案

1

$ php bin/console importmap:require bootstrap/dist/css/bootstrap.min.css

若要在頁面上包含它，請從 JavaScript 檔案匯入它

1
2
3
4

// assets/app.js
import 'bootstrap/dist/css/bootstrap.min.css';

// ...

CSS 檔案內的路徑

從 CSS 內部，您可以使用一般的 CSS `url()` 函數和目標檔案的相對路徑來參考其他檔案

1
2
3
4
5

/* assets/styles/app.css */
.quack {
    /* file lives at assets/images/duck.png */
    background-image: url('../images/duck.png');
}

最終 `app.css` 檔案中的路徑將自動包含 `duck.png` 的已版本控制 URL

1
2
3
4

/* public/assets/styles/app-3c16d92m.css */
.quack {
    background-image: url('../images/duck-3c16d92m.png');
}

使用 Tailwind CSS

若要搭配 AssetMapper 組件使用 Tailwind CSS 框架，請查看 symfonycasts/tailwind-bundle。

使用 Sass

若要搭配 AssetMapper 組件使用 Sass，請查看 symfonycasts/sass-bundle。

從 JavaScript 檔案延遲匯入 CSS

如果您有一些想要延遲載入的 CSS，您可以透過一般的「動態」匯入語法來完成

1
2
3
4

// assets/any-file.js
import('./lazy.css');

// ...

在這種情況下，`lazy.css` 將會非同步下載，然後新增到頁面。如果您使用動態匯入來延遲載入 JavaScript 檔案，而該檔案匯入 CSS 檔案（使用非動態 `import` 語法），則該 CSS 檔案也會非同步下載。

遺失 importmap 項目

最常見的錯誤之一來自您的瀏覽器主控台，看起來會像這樣

Failed to resolve module specifier " bootstrap". Relative references must start with either "/", "./", or "../".

或

The specifier "bootstrap" was a bare specifier, but was not remapped to anything. Relative module specifiers must start with "./", "../" or "/".

這表示，在您的 JavaScript 中的某個地方，您正在匯入第三方套件 - 例如 `import 'bootstrap'`。瀏覽器嘗試在您的 `importmap` 檔案中尋找此套件，但它不在那裡。

修正方法幾乎總是將其新增到您的 `importmap`

1

$ php bin/console importmap:require bootstrap

JavaScript、CSS 或圖片檔案 404 找不到

有時，您正在匯入的 JavaScript 檔案（例如 `import './duck.js'`），或您正在參考的 CSS/圖片檔案將找不到，您將在瀏覽器主控台中看到 404 錯誤。您也會注意到，404 URL 的檔案名稱中遺失了版本雜湊（例如，404 到 `/assets/duck.js`，而不是像 `/assets/duck-1b7a64b3.js` 的路徑）。

這通常是因為路徑錯誤。如果您直接在 Twig 範本中參考檔案

1

<img src="{{ asset('images/duck.png') }}">

那麼您傳遞給 `asset()` 的路徑應該是檔案的「邏輯路徑」。使用 `debug:asset-map` 命令來查看應用程式中所有有效的邏輯路徑。

更可能的是，您正在從 CSS 檔案（例如 `@import url('other.css')`）或 JavaScript 檔案匯入失敗的資源

1
2

// assets/controllers/farm-controller.js
import '../farm/chicken.js';

執行此操作時，路徑應相對於匯入它的檔案（並且，在 JavaScript 檔案中，應以 `./` 或 `../` 開頭）。在這種情況下，`../farm/chicken.js` 將指向 `assets/farm/chicken.js`。若要查看應用程式中所有無效匯入的清單，請執行

1
2

$ php bin/console cache:clear
$ php bin/console debug:asset-map

任何無效的匯入都會在螢幕頂端顯示為警告（請確保您已安裝 symfony/monolog-bundle）

1
2

WARNING   [asset_mapper] Unable to find asset "../images/ducks.png" referenced in "assets/styles/app.css".
WARNING   [asset_mapper] Unable to find asset "./ducks.js" imported from "assets/app.js".

註解程式碼中遺失資源警告

AssetMapper 組件會在您的 JavaScript 檔案中尋找 import 行，以便它可以自動將它們新增到您的 importmap。這是透過正則表達式完成的，效果很好，但並非完美。如果您註解掉一個 import，它仍然會被找到並新增到您的 importmap 中。這不會造成任何損害，但可能會令人感到意外。

如果找不到匯入的路徑，當該資源正在建置時，您會看到警告日誌，您可以忽略它。

效能：理解預先載入

Lighthouse 可能會報告的一個問題是

避免鏈接關鍵請求

為了理解這個問題，想像一下這個理論上的設置

• assets/app.js 匯入 ./duck.js
• assets/duck.js 匯入 bootstrap

在沒有預先載入的情況下，當瀏覽器下載頁面時，會發生以下情況

1. 瀏覽器下載 assets/app.js；
2. 然後它看到 ./duck.js 匯入並下載 assets/duck.js；
3. 然後它看到 bootstrap 匯入並下載 assets/bootstrap.js。

瀏覽器不會並行下載所有 3 個檔案，而是被迫在發現它們時逐一下載。這會損害效能。

AssetMapper 通過輸出「preload」link 標籤來避免這個問題。邏輯如下

A) 當您在範本中呼叫 importmap('app') 時，AssetMapper 組件會查看 assets/app.js 檔案，並找到它匯入的所有 JavaScript 檔案，或那些檔案匯入的檔案等等。

B) 然後它為每個檔案輸出一個 link 標籤，並帶有一個 rel="preload" 屬性。這告訴瀏覽器立即開始下載這些檔案，即使它尚未看到它們的 import 語句。

此外，如果您的應用程式中可以使用 WebLink 組件，Symfony 將在回應中新增一個 Link 標頭以預先載入 CSS 檔案。

AssetMapper 組件會合併資源嗎？

不是！但那是因為這不再是必要的了！

過去，合併資源以減少發出的 HTTP 請求數量是很常見的。由於像 HTTP/2 這樣的網頁伺服器的進步，將您的資源分開並讓瀏覽器並行下載它們通常不是問題。事實上，透過保持它們分開，當您更新一個資源時，瀏覽器可以繼續使用所有其他資源的快取版本。

請參閱 最佳化 以取得更多詳細資訊。

AssetMapper 組件會最小化資源嗎？

不是！在大多數情況下，這完全沒問題。網頁伺服器在發送資源之前執行的網頁資源壓縮通常就足夠了。但是，如果您認為您可以從最小化資源中受益（除了稍後壓縮它們之外），您可以使用 SensioLabs Minify Bundle。

這個 bundle 與 AssetMapper 無縫整合，並在運行 asset-map:compile 命令時自動最小化所有網頁資源（如在生產環境中提供資源章節中所述）。

請參閱 最佳化 以取得更多詳細資訊。

AssetMapper 組件是否已準備好用於生產環境？效能好嗎？

是的！非常！AssetMapper 組件利用了瀏覽器技術（如 importmaps 和原生 import 支援）和網頁伺服器（如 HTTP/2，它允許並行下載資源）的進步。請參閱關於最小化和合併的其他問題以及 最佳化 以取得更多詳細資訊。

https://ux.symfony.com 網站運行在 AssetMapper 組件上，並具有 99% 的 Google Lighthouse 分數。

AssetMapper 組件是否適用於所有瀏覽器？

是的！像 importmaps 和 import 語句這樣的功能在所有現代瀏覽器中都受到支援，但 AssetMapper 組件附帶一個 ES module shim 以支援舊瀏覽器中的 importmap。因此，它在任何地方都有效（請參閱下面的註解）。

在您自己的程式碼中，如果您依賴現代 ES6 JavaScript 功能，例如 class 語法，這在除了最舊的瀏覽器之外的所有瀏覽器中都受到支援。如果您確實需要支援非常舊的瀏覽器，您應該使用像 Encore 而不是 AssetMapper 組件這樣的工具。

1
2
3
4
5
6
7

// this works
import { add } from './math.js';

// this will not work in the oldest browsers
import('./math.js').then(({ add }) => {
    // ...
});

我可以搭配 Sass 或 Tailwind 使用嗎？

當然！請參閱 使用 Tailwind CSS 或 使用 Sass。

我可以搭配 TypeScript 使用嗎？

當然！請參閱 使用 TypeScript。

我可以搭配 JSX 或 Vue 使用嗎？

可能不會。如果您正在用 React、Svelte 或其他前端框架編寫應用程式，您最好直接使用它們的工具。

JSX 可以直接編譯為原生 JavaScript 檔案，但如果您使用大量的 JSX，您可能需要使用像 Encore 這樣的工具。有關將其與 AssetMapper 組件一起使用的更多詳細資訊，請參閱 UX React 文件。

Vue 檔案可以用原生 JavaScript 撰寫，這些檔案將與 AssetMapper 組件一起工作。但是您不能使用組件撰寫單一檔案組件（即 .vue 檔案），因為這些組件必須在建置系統中使用。有關將其與 AssetMapper 組件一起使用的更多詳細資訊，請參閱 UX Vue.js 文件。

我可以檢查程式碼風格並格式化我的程式碼嗎？

AssetMapper 沒有這個功能，但您可以在您的專案中安裝 kocal/biome-js-bundle 來檢查和格式化您的前端資源。它比像 Prettier 這樣的替代方案快得多，並且不需要任何配置來處理您的 JavaScript、TypeScript 和 CSS 檔案。

覆寫第三方資源

如果您想覆寫第三方資源，您可以透過在您的 assets/ 目錄中建立一個同名的檔案來做到這一點。例如，如果您想覆寫 pagerfanta.css 檔案，請在 assets/bundles/babdevpagerfanta/css/pagerfanta.css 建立一個檔案。這個檔案將被用來代替原始檔案。

framework.asset_mapper.paths

此配置保存將掃描資源的所有目錄。這可以是一個簡單的列表

1
2
3
4
5

framework:
    asset_mapper:
        paths:
            - assets/
            - vendor/some/package/assets

或者您可以為每個路徑指定一個「命名空間」，該命名空間將在資源地圖中使用

1
2
3
4
5

framework:
    asset_mapper:
        paths:
            assets/: ''
            vendor/some/package/assets/: 'some-package'

在這種情況下，vendor/some/package/assets/ 目錄中所有檔案的「邏輯路徑」將以 some-package 為前綴 - 例如 some-package/foo.js。

framework.asset_mapper.excluded_patterns

這是將從資源地圖中排除的 glob 模式列表

1
2
3
4

framework:
    asset_mapper:
        excluded_patterns:
            - '*/*.scss'

您可以使用 debug:asset-map 命令來仔細檢查您期望的檔案是否包含在資源地圖中。

framework.asset_mapper.exclude_dotfiles

是否從資源映射器中排除任何以 . 開頭的檔案。如果您想避免洩露敏感檔案，例如資源映射器發布的檔案中的 .env 或 .gitignore，這會很有用。

1
2
3

framework:
    asset_mapper:
        exclude_dotfiles: true

預設情況下啟用此選項。

framework.asset_mapper.importmap_polyfill

配置舊瀏覽器的 polyfill。預設情況下，ES module shim 是透過 CDN 載入的（即此設定的預設值為 es-module-shims）

1
2
3
4
5
6
7
8
9

framework:
    asset_mapper:
        # set this option to false to disable the shim entirely
        # (your website/web app won't work in old browsers)
        importmap_polyfill: false

        # you can also use a custom polyfill by adding it to your importmap.php file
        # and setting this option to the key of that file in the importmap.php file
        # importmap_polyfill: 'custom_polyfill'

1

$ php bin/console importmap:require es-module-shims

framework.asset_mapper.importmap_script_attributes

這是將新增到 {{ importmap() }} Twig 函數呈現的 <script> 標籤的屬性列表

1
2
3
4

framework:
    asset_mapper:
        importmap_script_attributes:
            crossorigin: 'anonymous'

內容安全策略與 CSS 檔案

如果您的 importmap 包含 CSS 檔案，AssetMapper 會使用一個技巧，透過將 data:application/javascript 新增到呈現的 importmap 中來載入這些檔案（請參閱 處理 CSS）。

這可能會導致瀏覽器報告 CSP 違規並阻止載入 CSS 檔案。為了防止這種情況，您可以將 strict-dynamic 新增到您的內容安全策略的 script-src 指令中，以告知瀏覽器允許 importmap 載入其他資源。