src

Baseline 广泛可用 *

此特性已相当成熟，可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来，各浏览器均已提供此特性。

* 此特性的某些部分可能存在不同级别的支持。

@font-face at-rule 规则中的 src CSS 描述符用于指定包含字体数据的资源。它是 @font-face 规则生效所必需的。

语法

css

/* <url> values */
src: url("https://example.com/path/to/font.woff"); /* Absolute URL */
src: url("path/to/font.woff"); /* Relative URL */
src: url("path/to/svgFont.svg#example"); /* Fragment identifying font */

/* <font-face-name> values */
src: local(font); /* Unquoted name */
src: local(some font); /* Name containing space */
src: local("font"); /* Quoted name */
src: local("some font"); /* Quoted name containing a space */

/* <tech(<font-tech>)> values */
src: url("path/to/fontCOLRv1.otf") tech(color-COLRv1);
src: url("path/to/fontCOLR-svg.otf") tech(color-SVG);

/* <format(<font-format>)> values */
src: url("path/to/font.woff") format("woff");
src: url("path/to/font.otf") format("opentype");

/* Multiple resources */
src:
  url("path/to/font.woff") format("woff"),
  url("path/to/font.otf") format("opentype");

/* Multiple resources with font format and technologies */
src:
  url("trickster-COLRv1.otf") format(opentype) tech(color-COLRv1),
  url("trickster-outline.otf") format(opentype);

值

url(): 指定一个外部引用，由一个 <url> 和可选的 format() 与 tech() 组件值提示组成，这些提示指定了 URL 所引用资源的格式和字体技术。format() 和 tech() 组件是由逗号分隔的已知字体格式和技术字符串列表。如果用户代理不支持该字体技术或格式，它会跳过下载该字体资源。如果没有提供格式或技术提示，则该字体资源总是会被下载。
format(): 跟在 url() 值后面的可选声明，为用户代理提供关于字体格式的提示。如果该值不被支持或无效，浏览器可能不会下载该资源，从而可能节省带宽。如果省略，浏览器将下载资源然后检测其格式。如果为了向后兼容而引入的字体源不在已定义关键字列表中，请将格式字符串用引号括起来。可能的值在下面的字体格式部分描述。
tech(): 跟在 url() 值后面的可选声明，为用户代理提供关于字体技术的提示。tech() 的值可以是字体技术中描述的关键字之一。
local(<font-face-name>): 指定当字体在用户设备上可用时应使用的字体名称。将字体名称用引号括起来是可选的。

备注： 对于 OpenType 和 TrueType 字体，<font-face-name> 用于匹配本地可用字体名称表中的 Postscript 名称或完整字体名称。使用哪种类型的名称因平台和字体而异，因此你应该同时包含这两种名称，以确保在不同平台上正确匹配。不得使用给定字体名称的平台替换项。

备注： 本地可用字体可能已预装在用户设备上，也可能是用户主动安装的。

虽然特定设备的所有用户的预装字体集可能相同，但用户安装的字体集则不然。因此，网站可以通过发现用户安装的字体集来为设备构建指纹，帮助网站在网络上跟踪用户。

为防止这种情况，用户代理在使用 local() 时可能会忽略用户安装的字体。
<font-face-name>: 使用 local() 组件值指定本地安装字体的完整名称或 postscript 名称，该名称在一个更大的字体族中唯一标识一个字体。名称可以选用引号括起来。字体名称不区分大小写。

备注： 本地字体访问 API 可用于访问用户本地安装的字体数据——这包括更高级别的细节，如名称、样式和族系，以及底层字体文件的原始字节。

描述

该描述符的值是一个按优先级排序、以逗号分隔的外部引用或本地安装字体名称列表，其中每个资源都使用 url() 或 local() 指定。当需要字体时，用户代理会遍历列出的引用集，使用它能成功激活的第一个。包含无效数据或未找到的本地字体将被忽略，用户代理会加载列表中的下一个字体。

如果设置了多个 src 描述符，则只有最后声明的且能加载资源的规则会被应用。如果最后一个 src 描述符可以加载资源并且不包含 local() 字体，即使设备上有可用的本地版本，浏览器也可能会下载外部字体文件并忽略本地版本。

备注： 浏览器认为无效的描述符中的值将被忽略。某些浏览器如果任何一项无效，就会忽略整个描述符，即使只有一个项无效。这可能会影响回退方案的设计。更多信息请参阅浏览器兼容性。

与 CSS 中的其他 URL 一样，该 URL 可以是相对的，此时它会相对于包含 @font-face 规则的样式表的位置进行解析。对于 SVG 字体，URL 指向包含 SVG 字体定义的文档中的一个元素。如果省略元素引用，则默认为引用第一个定义的字体。类似地，可以包含多个字体的字体容器格式，对于给定的 @font-face 规则只加载其中一个字体。片段标识符用于指示要加载哪个字体。如果容器格式缺少已定义的片段标识符方案，则使用基于 1 的索引方案（例如，“font-collection#1”代表第一个字体，“font-collection#2”代表第二个字体，依此类推）。

如果字体文件是多个字体的容器，则会包含一个片段标识符以指示应使用的子字体，如下所示

css

/* WhichFont is the PostScript name of a font in the font file */
src: url("collection.otc#WhichFont");
/* WhichFont is the element id of a font in the SVG Font file */
src: url("fonts.svg#WhichFont");

字体格式

下表显示了有效的字体关键字及其对应的字体格式。要检查浏览器在 CSS 中是否支持某种字体格式，请使用 @supports 规则。

关键字	字体格式	常见扩展名
`collection`	OpenType 集合	.otc, .ttc
`embedded-opentype`	嵌入式 OpenType	.eot
`opentype`	OpenType	.otf, .ttf
`svg`	SVG 字体（已弃用）	.svg, .svgz
`truetype`	TrueType	.ttf
`woff`	WOFF 1.0	.woff
`woff2`	WOFF 2.0	.woff2

备注

format(svg) 代表 SVG 字体，而 tech(color-SVG) 代表带有 SVG 表的 OpenType 字体（也称为 OpenType-SVG 彩色字体），两者完全不同。
无论字体文件是使用三次贝塞尔曲线（在 CFF/CFF2 表内）还是二次贝塞尔曲线（在字形表内），opentype 和 truetype 的值都是等效的。

较旧的非规范化 format() 值具有以下等效语法；为了向后兼容，以引号括起来的字符串形式提供

旧语法	等效语法
`format("woff2-variations")`	`format(woff2) tech(variations)`
`format("woff-variations")`	`format(woff) tech(variations)`
`format("opentype-variations")`	`format(opentype) tech(variations)`
`format("truetype-variations")`	`format(truetype) tech(variations)`

字体技术

下表显示了 tech() 描述符的有效值及其对应的字体技术。要检查浏览器在 CSS 中是否支持某种字体技术，请使用 @supports at-rule。

关键字	描述
`color-cbdt`	彩色位图数据表
`color-colrv0`	通过 COLR 版本 0 表实现的多色字形
`color-colrv1`	通过 COLR 版本 1 表实现的多色字形
`color-sbix`	标准位图图形表
`color-svg`	SVG 多色表
`features-aat`	TrueType `morx` 和 `kerx` 表
`features-graphite`	Graphite 特性，即 `Silf`、`Glat`、`Gloc`、`Feat` 和 `Sill` 表
`features-opentype`	OpenType `GSUB` 和 `GPOS` 表
`incremental`	增量字体加载
`palettes`	通过 `font-palette` 实现的字体调色板，用于在字体中选择多个调色板之一
`variations`	TrueType 和 OpenType 字体中的字体变体，用于控制字体轴、字重、字形等

正式定义

相关的 at-rule	`@font-face`
初始值	`n/a（必需）`
计算值	同指定值

正式语法

src = 
  <font-src-list>

<font-src> = 
  <url> [ format( <font-format> ) ]? [ tech( <font-tech># ) ]?  |
  local( <family-name> )                              

<font-format> = 
  <string>           |
  collection         |
  embedded-opentype  |
  opentype           |
  svg                |
  truetype           |
  woff               |
  woff2              

<font-tech> = 
  <font-features-tech>  |
  <color-font-tech>     |
  variations            |
  palettes              |
  incremental           

<family-name> = 
  <string>         |
  <custom-ident>+  

<font-features-tech> = 
  features-opentype  |
  features-aat       |
  features-graphite  

<color-font-tech> = 
  color-COLRv0  |
  color-COLRv1  |
  color-SVG     |
  color-sbix    |
  color-CBDT

示例

使用 url() 和 local() 指定字体资源

下面的示例展示了如何为同一个字体族定义两个字体。font-family 命名为 MainText。第一个字体是常规字体，第二个是同一字体族的粗体版本。

css

/* Defining a regular font face */
@font-face {
  font-family: "MainText";
  src:
    local("Futura-Medium"),
    url("FuturaMedium.woff") format("woff"),
    url("FuturaMedium.otf") format("opentype");
}

/* Defining a different bold font face for the same family */
@font-face {
  font-family: "MainText";
  src:
    local("Gill Sans Bold") /* full font name */,
    local("GillSans-Bold") /* postscript name */,
    url("GillSansBold.woff") format("woff"),
    url("GillSansBold.otf") format("opentype"),
    url("GillSansBold.svg#MyFontBold"); /* Referencing an SVG font fragment by id */
  font-weight: bold;
}

/* Using the regular font face */
p {
  font-family: "MainText", sans-serif;
}

/* Font-family is inherited, but bold fonts are used */
p.bold {
  font-weight: bold;
}

使用 tech() 和 format() 值指定字体资源

以下示例展示了如何使用 tech() 和 format() 值来指定字体资源。使用 tech() 和 format() 值指定了一个使用 color-colrv1 技术和 opentype 格式的字体。如果用户代理支持彩色字体，则会激活它，并提供一个 opentype 非彩色字体作为回退。

css

@font-face {
  font-family: "Trickster";
  src:
    url("trickster-COLRv1.otf") format(opentype) tech(color-COLRv1),
    url("trickster-outline.otf") format(opentype);
}

/* Using the font face */
p {
  font-family: "Trickster", fantasy;
}

为旧版浏览器指定回退

浏览器应使用带有一个 src 描述符的 @font-face，其中列出了字体可能的来源。由于浏览器将使用它能够加载的第一个资源，因此应按你希望它们被使用的优先顺序列出各项。

通常这意味着本地文件应出现在远程文件之前，带有 format() 或 tech() 约束的资源应出现在没有这些约束的资源之前（否则总是会选择约束较少的版本）。例如：

css

@font-face {
  font-family: "MgOpenModernaBold";
  src:
    url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental),
    url("MgOpenModernaBold.otf") format(opentype);
}

不支持上述 tech() 的浏览器应忽略第一项并尝试加载第二个资源。

一些浏览器尚未忽略无效项，如果任何值无效，它们会使整个 src 描述符失效。如果使用这些浏览器，你可以指定多个 src 描述符作为回退。请注意，多个 src 描述符会按相反顺序尝试，所以在最后我们有包含所有项的正常描述符。

css

@font-face {
  font-family: "MgOpenModernaBold";
  src: url("MgOpenModernaBold.otf") format(opentype);
  src: url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental);
  src:
    url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental),
    url("MgOpenModernaBold.otf") format(opentype);
}

检查用户代理是否支持某种字体

以下示例展示了如何使用 @supports 规则检查用户代理是否支持某种字体技术。如果用户代理支持 color-COLRv1 技术，则 @supports 内部的 CSS 块将被应用。

css

@supports font-tech(color-COLRv1) {
  @font-face {
    font-family: "Trickster";
    src: url("trickster-COLRv1.otf") format(opentype) tech(color-COLRv1);
  }

  .colored_text {
    font-family: "Trickster", fantasy;
  }
}

规范

规范
CSS 字体模块第 4 级 # src-desc

浏览器兼容性

另见

帮助改进 MDN

了解如何贡献

此页面最后修改于 ⁨2025 年 10 月 13 日⁩，由 MDN 贡献者们撰写。

在 GitHub 上查看此页面 • 报告此内容的问题