模板示例
content-sass

content-custom-font

CSS 能力
在哪里引用 CSS
manifest.json(content_scripts[].css)- HTML 文件(
<link rel="stylesheet" href="...">) - 脚本导入(
import "./styles.css",启用时也包括 Sass/Less)。在 content script 里,这种导入本身不会给任何东西加上样式。
CSS 支持
Manifest CSS 入口:示例:manifest.json 中的 CSS
示例:扩展页面脚本中的 CSS
content script 中的样式
在 content script 里,单纯的import "./styles.css" 得到的值是一个 data: URL 形式的样式表。它本身不会给任何东西加上样式。Sass 和 Less 的导入也是一样。
Extension.js 只在一种情况下替你放置这份样式表。这条导入必须写在已声明的 content script 的入口文件里,并且脚本必须用 data-extension-root 标记一个宿主元素。样式表随后会进入这个宿主的 shadow root。参见 Shadow DOM。
要给页面本身加样式,请使用下面任意一种方式:
最后一种方式读取导入得到的值,再自己放置它:
scripts/ 文件不会得到任何自动放置。在那里请读取这个值,再把它设到 <link> 上。
从 4.1.39 之后的版本起,如果一条只为副作用而写的样式导入没有被任何东西放置,构建会打印一条警告。
样式策略严格的页面
页面的内容安全策略(CSP)也决定 content script 自己的 DOM 调用能做什么。结果取决于脚本运行在哪个 world。在发送style-src 'self' 的页面上:
这些结果是在 Chrome 151 与 Firefox 160 上测得的,
dev 与生产构建都一样。shadow root 里的 <style> 元素会和文档里的一样被拒绝。
在发送 default-src 'self' 的页面上,fetch(href) 也会被拒绝。在 MAIN world 里两个浏览器都是如此,在 isolated world 里只有 Firefox 如此。
构建看不到脚本将要访问的页面的策略。它不会改动这些调用,也不会打印警告。必须在这种策略下工作的 MAIN world 脚本,可以不发请求,直接从 URL 里读出样式表并采用它:
@import,以及 public/ 里被注入的样式表,见运行时加载的文件。
内容脚本中的网页字体
把界面渲染到 shadow root 的内容脚本,无法只靠 CSS 加载网页字体。有两条平台规则会挡住它,而且都是静默的。 shadow root 内部的@font-face 永远不会生效。 字体(font face)解析的是文档的字体集,而不是 shadow 树,所以 Chrome 会忽略该规则并静默回退。修复前在 content-custom-font 模板上实测:document.fonts 为空,没有发出任何字体请求,用 "Momo Signature", cursive 排版的文本宽度与纯 cursive 完全相同。
注入样式表里的根绝对 url() 会相对宿主页面解析。 注入到 example.com 的样式表中的 url(/fonts/Momo.woff2) 请求的是 https://example.com/fonts/Momo.woff2,而不是扩展自己的那份文件。
改为把字体注册到页面自身的字体集上,URL 指向扩展,并在内容脚本卸载时移除它:
web_accessible_resources 中声明:
document.fonts,shadow 树就可以在普通的 font-family 规则里按名称使用它。可运行的版本见 content-custom-font。
以 URL 导入样式表
从 4.1.41 之后的版本起,在 content script 之外,?url 导入会给出编译后样式表的 URL:
assets/ 下。该样式表中相对的 url() 或 @import 无法跟随它到新位置,一条警告会列出这些地址。把那些文件移到 public/ 中并从根路径引用,或者不带 ?url 导入该样式表。
按上下文的输出行为
Extension.js 会根据哪个入口导入了 CSS 自动拆分上下文。
从 4.1.41 之后的版本起,content script 样式表会带上它导入的每个项目
.css 文件中的规则。导入时的 media、supports 或 layer 条件会被保留。content script 样式表从 data: URL 加载,浏览器在那里不会获取任何相对导入。包导入和远程导入保持原样。项目之外的样式表或私有文件不会被引入,构建会针对该文件发出警告。所有工具运行完之后仍留在样式表中的 @import 会发出警告,说明它的规则不会加载。
从 4.1.41 之后的版本起,Extension.js 用自己的规则编译每个样式表,这些规则优先于你的配置。你的配置为 .css、.scss、.sass 或 .less 文件设置的 type 不会生效。一条警告会说明这一点。请从该规则中移除 type。要得到文件 URL,用 ?url 导入样式表。要得到文本,用 ?raw 导入。
生产构建压缩样式表时,Extension.js 会把结果与压缩前的样式表进行比较。丢失了规则的样式表按原样发布,并附带一条警告,指出被丢掉的内容。从 4.1.41 之后的版本起,只有构建进行压缩时才运行这项检查,所以 dev 会跳过它。从 4.2.0 起,这条警告带有代码 W_CSS_PARSE。
url() 指向项目中任何地方都不存在的文件时,会以 W_CSS_DEAD_REF 警告,样式表的其余部分照常发布。浏览器对那个地址返回 404。设置 EXTENSION_STRICT_REFS=true 可以让构建以 E_CSS_DEAD_REF 失败。
从 4.2.0 之后的版本开始,打包器无法解析的 url(),比如没有扩展名的裸名称,或者未安装的作用域包路径,也会报告同样的 W_CSS_DEAD_REF,并且 EXTENSION_STRICT_REFS=true 会让构建以 E_CSS_DEAD_REF 失败。4.2.0 及之前的版本把它报告为 W_ASSET_MISSING,严格引用模式也不会因此失败。
开发期行为
- Content script 的 CSS 导入会参与 content script 的 HMR/重新挂载流程。
- Extension.js 会为只有 CSS 的 content script 入口添加一个开发期辅助脚本,使更新得以传播。
- 页面 CSS 遵循常规的页面 HMR 管线行为。
- manifest 的修改会重载整个扩展。修改 manifest 中的 content script 入口还会让 dev 会话重启编译器,无需你操作。
模块化与预处理器
- CSS 模块在扩展页面上下文中表现最好。
- 当你安装相关依赖时,Extension.js 会启用 Sass/Less 支持。
- 如果项目引用了
.scss/.less文件但没有安装预处理器,构建不会失败,而是发出警告并把源文件原样拷贝过去(不编译)。浏览器会把这份未编译的源码当作坏掉的 CSS,于是相关界面会完全没有样式,因此请安装预处理器以获得真正的编译。 - 当 Extension.js 检测到项目中存在 PostCSS 配置,或者你显式配置时,会自动运行 PostCSS。
最佳实践
- 把 content script 样式有意识地限定作用范围,减少与宿主页面的冲突。
- 对扩展页面 UI,优先使用组件级的模块样式。
- 显式地维护预处理器和 PostCSS 配置,避免随时间发生非预期的构建行为变化。
- 在持续集成(CI)中校验 manifest 字段所引用的 CSS 路径。
下一步
- 在 dev 更新行为 中了解更新结果。
- 进一步了解 CSS 模块。
- 进一步了解 PostCSS 集成。

