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.cn/npm/[email protected]/+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 配方会为你将其添加到 .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 maps 是一种原生浏览器功能。当你从 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，以便 旧浏览器 理解 importmaps（请参阅 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 并将你需要的确切路径传递给它。这也展示了如何一次性 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();

你甚至可以从内联脚本标签执行此操作

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 文件。

你可以像 require JavaScript 文件一样 require 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

要将 Tailwind CSS 框架与 AssetMapper 组件一起使用，请查看 symfonycasts/tailwind-bundle。

使用 Sass

要将 Sass 与 AssetMapper 组件一起使用，请查看 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 "../".

或

指定符 “bootstrap” 是一个裸指定符，但未被重映射到任何内容。相对模块指定符必须以 “./”、“../” 或 “/” 开头。

这意味着，在你的 JavaScript 代码中的某个地方，你正在导入一个第三方包 - 例如 import 'bootstrap'。浏览器尝试在你的 importmap 文件中找到这个包，但它不在那里。

几乎所有的修复方法都是将其添加到你的 importmap 中

1

$ php bin/console importmap:require bootstrap

JavaScript、CSS 或图像文件 404 未找到

有时，你正在导入的 JavaScript 文件（例如 import './duck.js'），或者你正在引用的 CSS/图像文件将无法找到，你将在浏览器的控制台中看到 404 错误。你还会注意到，404 URL 中缺少文件名中的版本哈希（例如，指向 /assets/duck.js 的 404 错误，而不是像 /assets/duck-1b7a64b3.js 这样的路径）。

这通常是因为路径错误。如果你直接在 Twig 模板中引用该文件

1

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

那么你传递给 asset() 的路径应该是文件的“逻辑路径”。使用 debug:asset-map 命令查看你的应用程序中所有有效的逻辑路径。

更可能的情况是，你正在从 CSS 文件（例如 @import url('other.css')）或 JavaScript 文件中导入失败的 asset

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 中。这不会造成任何危害，但可能会令人惊讶。

如果找不到导入的路径，你将在构建该 asset 时看到警告日志，你可以忽略它。

性能：理解预加载

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 组件会合并资源吗？

不！但这因为这不再是必要的了！

过去，通常会合并 assets 以减少发出的 HTTP 请求数量。由于 HTTP/2 等 Web 服务器的进步，通常保持 assets 分开并让浏览器并行下载它们不是问题。实际上，通过保持它们分开，当你更新一个 asset 时，浏览器可以继续使用所有其他 assets 的缓存版本。

有关更多详细信息，请参见 优化。

AssetMapper 组件会压缩资源吗？

不！在大多数情况下，这完全可以。Web 服务器在发送 assets 之前执行的 Web asset 压缩通常就足够了。但是，如果你认为你可以从缩小 assets（除了稍后压缩它们之外）中受益，则可以使用 SensioLabs Minify Bundle。

此 bundle 与 AssetMapper 无缝集成，并在运行 asset-map:compile 命令时自动缩小所有 Web assets（如 在生产环境中提供 assets 部分中所述）。

有关更多详细信息，请参见 优化。

AssetMapper 组件是否已准备好用于生产环境？性能如何？

是的！非常棒！AssetMapper 组件利用了浏览器技术（如 importmaps 和原生 import 支持）和 Web 服务器（如 HTTP/2，它允许并行下载 assets）的进步。有关最小化和组合以及 优化 的其他问题，请参见其他问题。

https://ux.symfony.ac.cn 站点在 AssetMapper 组件上运行，并且 Google Lighthouse 得分为 99％。

AssetMapper 组件是否适用于所有浏览器？

是的！所有现代浏览器都支持诸如 importmaps 和 import 语句之类的功能，但是 AssetMapper 组件附带了一个 ES 模块 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 文档。

我可以 Lint 和格式化我的代码吗？

不能使用 AssetMapper，但是你可以在你的项目中安装 kocal/biome-js-bundle 来 lint 和格式化你的前端 assets。它比 Prettier 等替代方案快得多，并且无需配置即可处理你的 JavaScript，TypeScript 和 CSS 文件。

覆盖第三方资源

如果要覆盖第三方 asset，可以通过在你的 assets/ 目录中创建一个同名文件来做到这一点。例如，如果你要覆盖 pagerfanta.css 文件，请在 assets/bundles/babdevpagerfanta/css/pagerfanta.css 中创建一个文件。将使用此文件代替原始文件。

framework.asset_mapper.paths

此配置包含将扫描 assets 的所有目录。这可以是一个简单的列表

1
2
3
4
5

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

或者你可以为每个路径指定一个“命名空间”，该命名空间将在 asset map 中使用

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

这是将从 asset map 中排除的 glob 模式列表

1
2
3
4

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

你可以使用 debug:asset-map 命令来仔细检查你期望的文件是否包含在 asset map 中。

framework.asset_mapper.exclude_dotfiles

是否从 asset mapper 中排除任何以 . 开头的文件。如果你想避免在 asset mapper 发布的文件中泄漏敏感文件（如 .env 或 .gitignore），这将很有用。

1
2
3

framework:
    asset_mapper:
        exclude_dotfiles: true

默认情况下启用此选项。

framework.asset_mapper.importmap_polyfill

为旧浏览器配置 polyfill。默认情况下，ES 模块 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 加载其他资源。