> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 浏览器扩展中的 CSS、Sass 与 Less

> 用 CSS、Sass 或 Less 为扩展页面和 content script 设置样式。Extension.js 会按上下文路由样式，并自动处理重载行为。

Extension.js 无需任何配置即可支持纯 CSS 以及 Sass、Less 预处理器。对页面上下文（popup、options、side panel）和 content script 上下文，它会采用不同的样式路由方式。

页面样式会作为关联的资源发布。Extension.js 会把 content script 的样式注入到网页的 document 中，使其作用于当前活动标签页。

## 模板示例

### `content-sass`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/content-sass/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=b7222f4abc0068d1220d00b97477f07b" alt="content-sass template screenshot" width="2400" height="1800" data-path="images/examples/content-sass/screenshot.png" />

带有 Sass 样式的 content script，注入到网页中。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=content-sass
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=content-sass
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=content-sass
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=content-sass
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=content-sass
  ```
</CodeGroup>

仓库：[extension-js/examples/content-sass](https://github.com/extension-js/examples/tree/main/examples/content-sass)

### `content-custom-font`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/content-custom-font/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=8285de22f6f479b4cb07192eefeff548" alt="content-custom-font template screenshot" width="2400" height="1800" data-path="images/examples/content-custom-font/screenshot.png" />

演示通过 CSS 加载自定义字体的 content script。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=content-custom-font
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=content-custom-font
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=content-custom-font
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=content-custom-font
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=content-custom-font
  ```
</CodeGroup>

仓库：[extension-js/examples/content-custom-font](https://github.com/extension-js/examples/tree/main/examples/content-custom-font)

## CSS 能力

| 能力           | 你会得到什么                                  |
| ------------ | --------------------------------------- |
| 多上下文样式       | 对页面和 content script 使用同一种编写模型           |
| Sass/Less 编译 | 当相关依赖存在时编译 Sass/Less                    |
| 上下文感知的输出     | 将页面 CSS 与 content script CSS 分别输出到正确的目标 |
| 开发期更新流程      | 在受支持时通过热模块替换（HMR）/重新挂载应用样式更新            |

## 在哪里引用 CSS

* `manifest.json`（`content_scripts[].css`）
* HTML 文件（`<link rel="stylesheet" href="...">`）
* 脚本导入（`import "./styles.css"`，启用时也包括 Sass/Less）

## CSS 支持

Manifest CSS 入口：

| Manifest 字段           | 期望的文件类型                        |
| --------------------- | ------------------------------ |
| `content_scripts.css` | `.css`、`.scss`、`.sass`、`.less` |

## 示例：`manifest.json` 中的 CSS

```json theme={null}
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "css": ["./styles/content.css"],
      "js": ["./scripts/content.ts"]
    }
  ]
}
```

## 示例：扩展页面脚本中的 CSS

```ts theme={null}
import "./styles/popup.scss";
```

## 按上下文的输出行为

| 上下文            | 输出行为                                                                    |
| -------------- | ----------------------------------------------------------------------- |
| HTML/页面上下文     | Extension.js 将 CSS 与页面入口一起打包（`feature.css`）                             |
| Content script | Extension.js 将 CSS 作为 `content_scripts/[name].[contenthash:8].css` 资源输出 |

Extension.js 会根据哪个入口导入了 CSS 自动拆分上下文。

## 开发期行为

* Content script 的 CSS 导入会参与 content script 的 HMR/重新挂载流程。
* Extension.js 会为只有 CSS 的 content script 入口添加一个开发期辅助脚本，使更新得以传播。
* 页面 CSS 遵循常规的页面 HMR 管线行为。
* 结构性的 manifest/content script 变更仍可能需要扩展完整重载或重启。

## 模块化与预处理器

* CSS 模块在扩展页面上下文中表现最好。
* 当你安装相关依赖时，Extension.js 会启用 Sass/Less 支持。
* 当 Extension.js 检测到项目中存在 PostCSS 配置，或者你显式配置时，会自动运行 PostCSS。

## 最佳实践

* 把 content script 样式有意识地限定作用范围，减少与宿主页面的冲突。
* 对扩展页面 UI，优先使用组件级的模块样式。
* 显式地维护预处理器和 PostCSS 配置，避免随时间发生非预期的构建行为变化。
* 在持续集成（CI）中校验 manifest 字段所引用的 CSS 路径。

## 下一步

* 在 [dev 更新行为](/docs/workflows/dev-update-behavior) 中了解更新结果。
* 进一步了解 [CSS 模块](/docs/languages-and-frameworks/css-modules)。
* 进一步了解 [PostCSS 集成](/docs/integrations/postcss)。