# @css-inline/css-inline 中文文档

规范地址：https://npmcn.com/package/%40css-inline/css-inline/

版本：0\.23\.2
npm 元数据更新时间：2026-10-27T13:15:49.267Z
中文译文更新时间：2026-11-11T03:21:06.932Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40css-inline/css-inline
原文对照：https://npmcn.com/package/%40css-inline/css-inline/?lang=original
项目主页：https://github.com/Stranger6667/css-inline#readme
源码仓库：https://github.com/Stranger6667/css-inline

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：53.9 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 10
- 运行依赖：0 个
- 首次发布：2023-12-28T21:11:56.756Z
- 最新版本发布：2026-10-27T13:15:48.707Z
- 近 30 天下载量：1644459（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 14 个）

## 中文简介

用于将 CSS 嵌入 HTML “ 样式” 属性的高性能库

## 安装

```sh
npm install @css-inline/css-inline
```

也可以使用：`pnpm add @css-inline/css-inline`、`yarn add @css-inline/css-inline`、`bun add @css-inline/css-inline`

## README

# cs-内线

[![build status](https://img.shields.io/github/actions/workflow/status/Stranger6667/css-inline/build.yml?style=flat-square&labelColor=555555&logo=github)](https://github.com/Stranger6667/css-inline/actions/workflows/build.yml) [![npm](https://img.shields.io/npm/v/@css-inline/css-inline.svg?style=flat-square)](https://www.npmjs.com/package/@css-inline/css-inline) [![codecov.io](https://img.shields.io/codecov/c/gh/Stranger6667/css-inline?logo=codecov&style=flat-square&token=tOzvV4kDY0)](https://app.codecov.io/github/Stranger6667/css-inline) [![gitter](https://img.shields.io/gitter/room/Stranger6667/css-inline?style=flat-square)](https://gitter.im/Stranger6667/css-inline)

`css-inline` 将 CSS 插入 HTML `style` 属性。 使用它来准备HTML电子邮件或将HTML嵌入第三方网页.

它使这个 HTML:

```html
<html><head><style>h1 { color:blue; }</style></head><body><h1>Big Text</h1></body></html>
```

改为:

```html
<html><head></head><body><h1 style="color: blue;">Big Text</h1></body></html>
```

`css-inline` 保留输入时的白空间文本节点,所以缩入的 HTML 保留在输出中缩入.

-   利用Mozilla Servo组件(`html5ever`, (中文(简体) ), `cssparser`, (中文(简体) ), `selectors`(中文(简体) )
-   内置 CSS 从 `style` 财务报告和审定财务报表 `link` 标记
-   删除 `style` 财务报告和审定财务报表 `link` 标记
-   解决外部样式表(包括本地文件)
-   可选缓存外部样式表
-   Linux、Windows、macOS和Android的作品
-   支持 HTML5 & CSS3
-   在节点20和22试验

## 游戏场

尝试 `css-inline` 在WebAssembly驱动的 [游乐场](https://css-inline.org/)。 。 。 .

## 安装

### 节点.js

安装方式 `npm`数字 :

```shell
npm i @css-inline/css-inline
```

货包船类型`index.d.ts`) (中文(简体) ).

npm为您的平台安装了预建的二进制,所以不需要Rust. 预建目标 : `linux-x64-gnu`, (中文(简体) ), `linux-x64-musl`, (中文(简体) ), `linux-arm64-gnu`, (中文(简体) ), `linux-arm64-musl`, (中文(简体) ), `linux-arm-gnueabihf`, (中文(简体) ), `darwin-x64`, (中文(简体) ), `darwin-arm64`, (中文(简体) ), `win32-x64-msvc`, (中文(简体) ), `win32-arm64-msvc`, (中文(简体) ), `android-arm64`, (中文(简体) ), `android-arm-eabi`。 。 。 .

## 使用量

```javascript
import { inline } from "@css-inline/css-inline";
// CommonJS: const { inline } = require("@css-inline/css-inline");

const inlined = inline(
  "<html><head><style>h1 { color:red }</style></head><body><h1>Test</h1></body></html>",
);
// <html><head></head><body><h1 style="color: red;">Test</h1></body></html>
```

`inline` 添加缺失 `html`, (中文(简体) ), `head` 财务报告和审定财务报表 `body` 标记,因此输出是一个完整的 HTML 文档.

`inlineFragment(html, css, options?)` 插入 `css` 字符串为 HTML 片断。 从不说 `<html>`, (中文(简体) ), `<head>` 或者说 `<body>`;如果输入有,则只保留其内容。 使用 `inline` 保持完整的文档结构:

```javascript
import { inlineFragment } from "@css-inline/css-inline";

const inlined = inlineFragment(
  "<main><h1>Hello</h1><section><p>who am i</p></section></main>",
  "p { color: red; } h1 { color: blue; }",
);
// <main><h1 style="color: blue;">Hello</h1><section><p style="color: red;">who am i</p></section></main>
```

### 配置

将选项作为第二个参数传递到 `inline` 第三个改为 `inlineFragment`。 。 。 .

-   `inlineStyleTags`。从 `style` 标签。 默认 : `true`
-   `keepStyleTags`保留 `style` 内嵌后标记。 默认 : `false`
-   `keepLinkTags`保留 `link` 内嵌后标记。 默认 : `false`
-   `keepAtRules`保持规则`@media`, (中文(简体) ), `@font-face`,...) 入内后. 默认 : `false`
-   `minifyCss`删除属性和值之间的分号和空格。 默认 : `false`
-   `baseUrl`。用于解决相对 URL 的基础 URL。 使用 `file://` 从文件系统装入样式表的计划; 结束目录 URL `/` (单位:千美元)`file:///path/to/styles/`),或 `css-inline` 解析相对于父目录。 默认 : `null`
-   `loadRemoteStylesheets`从中装入样式表 `link` 标记,通过网络或从 `file://` 路径. `false` 跳过每个 `link` 标签。 默认 : `true`
-   `cache`。用于外部样式表的 LRU 缓存,由已解析的 URL 键入. `size` 是要保存的样式表的数量,必须大于零,例如. `{ size: 5 }`默认 : `null`
-   `extraCss`额外的CSS到内置。 默认 : `null`
-   `preallocateNodeCapacity`。 。 。 . **高级**。解析时要预先分配的 HTML 节点数。 设定为预期的节点数以避免再分配 。 默认 : `32`
-   `removeInlinedSelectors`删除内嵌到 `<style>` 块。 默认 : `false`
-   `applyWidthAttributes`添加 `width` 来自 CSS 的 HTML 属性 `width` 属性在 `table`, (中文(简体) ), `td`, (中文(简体) ), `th` 财务报告和审定财务报表 `img`默认 : `false`
-   `applyHeightAttributes`添加 `height` 来自 CSS 的 HTML 属性 `height` 属性在 `table`, (中文(简体) ), `td`, (中文(简体) ), `th` 财务报告和审定财务报表 `img`默认 : `false`
-   `resolveCssVariables`替换 `var()` 引用它们所参考的自定义属性的值并删除 `--*` 声明。 默认 : `false`

要跳过内衬标记,请添加 `data-css-inline="ignore"` 属性 :

```html
<html>
<head>
    <style>h1 { color:blue; }</style>
</head>
<body>
    <!-- The tag below won't receive additional styles -->
    <h1 data-css-inline="ignore">Big Text</h1>
</body>
</html>
```

同样的属性在a `link` 或者说 `style` 标记排除其样式 :

```html
<head>
  <!-- Styles below are ignored -->
  <style data-css-inline="ignore">h1 { color:blue; }</style>
</head>
<body>
  <h1>Big Text</h1>
</body>
```

保持一个 `style` 在输出中标记, 添加 `data-css-inline="keep"`。使用它来保存 `@media` 单独查询应答邮件 `style` 标签. `css-inline` 即使当 `keepStyleTags` 实值 `false`。 。 。 .

```html
<head>
  <!-- Styles below are not removed -->
  <style data-css-inline="keep">h1 { color:blue; }</style>
</head>
<body>
  <h1>Big Text</h1>
</body>
```

规则不能内含到 HTML 中, 所以 `css-inline` 默认删除它们. 设定 `keepAtRules: true` 让他们留在 `style` 标记和内入其余样式. `css-inline` 即使在 `keepStyleTags` 实值 `false`。 。 。 .

```html
<head>
  <!-- With keepAtRules: true, "color: blue" goes into <h1> and @media stays in <style> -->
  <style>h1 { color: blue; } @media (max-width: 600px) { h1 { font-size: 18px; } }</style>
</head>
<body>
  <h1>Big Text</h1>
</body>
```

与 `minifyCss: true`, (中文(简体) ), `css-inline` 删除内嵌样式中属性和值之间的分号与空格.

```html
<head>
  <!-- With minifyCss: true, <h1> gets style="color:blue;font-weight:bold" -->
  <style>h1 { color: blue; font-weight: bold; }</style>
</head>
<body>
  <h1>Big Text</h1>
</body>
```

缓存是默认关闭。 启用它以避免在每次呼叫中获取相同的外部样式表 :

```javascript
import { inline } from "@css-inline/css-inline";

const inlined = inline(
  `
  <html>
    <head>
      <link href="http://127.0.0.1:1234/external.css" rel="stylesheet">
      <style>h1 { color:red }</style>
    </head>
    <body>
      <h1>Test</h1>
    </body>
  </html>
  `,
  { cache: { size: 5 } },
);
```

`inline` 财务报告和审定财务报表 `inlineFragment` 是同步的. `css-inline` 获取被阻断的 HTTP 请求的远程样式表, 因此调用会阻断事件循环, 直到获取完成 . `inlineAsync` 财务报告和审定财务报表 `inlineFragmentAsync` 使用相同的参数返回 a `Promise`。它们同时加载所有外部样式表,从事件循环中卸出:

```typescript
import { inlineAsync } from "@css-inline/css-inline";

const inlined = await inlineAsync(html, { baseUrl: "https://example.com/" });
```

设定 `loadRemoteStylesheets: false` 全部跳过 `link` 标签.

### 错误

`inline` 财务报告和审定财务报表 `inlineFragment` 丢出一个 `Error`,以及 `inlineAsync` 财务报告和审定财务报表 `inlineFragmentAsync` 以相同的方式拒绝 `Error`数字 :

-   无效 `baseUrl`数字 : `relative URL without a base: not a url`
-   获取失败 : `error sending request for url (http://127.0.0.1:9/a.css): http://127.0.0.1:9/a.css`
-   缺少本地文件 : `Missing stylesheet file: /path/to/missing.css`
-   `cache: { size: 0 }`数字 : `Cache size must be an integer greater than zero`

## 网络大会

`@css-inline/css-inline-wasm` 运行 `css-inline` 在浏览器中。 它的建造与 `wasm-bindgen`。 。 。 .

```html
<iframe id="output"></iframe>
<script src="https://unpkg.com/@css-inline/css-inline-wasm"></script>
<script>
  // `initWasm` is async: wait for it before calling `inline`
  cssInline.initWasm(fetch('https://unpkg.com/@css-inline/css-inline-wasm/index_bg.wasm')).then(() => {
    const inlinedHtml = cssInline.inline(`<html>
  <head>
    <style>h1 { color:blue; }</style>
  </head>
  <body>
    <h1>Big Text</h1>
  </body>
</html>`);
    document.getElementById('output').srcdoc = inlinedHtml;
  });
</script>
```

**页:1**: WASM 模块只通过 Aync 装入远程样式表 `inlineAsync` 财务报告和审定财务报表 `inlineFragmentAsync`,无法读取文件系统,没有 `cache` 选项。 见 [其读物](https://github.com/Stranger6667/css-inline/blob/master/crates/css-inline-js/wasm/README.md) 用于 npm 安装,节点.js 设置和 `link` 标记处理。 上面的 unpkg URL 装入最新发布的; 标出一个版本(`@css-inline/css-inline-wasm@0.23.2`)与您安装的软件包相匹配.

## 业绩

土著 `css-inline` 运行速度比 `juice` 财务报告和审定财务报表 `inline-css` 关于以下案例。 WASM建筑运行1.50x至1.65x比本土慢.

|  | 大小 | `css-inline` | `css-inline-wasm` | `juice` | `inline-css` |
| --- | --- | --- | --- | --- | --- |
| 基础 | 230个B | 8.14 微克 | 12.23 微克(含:**1.50个**(中文(简体) ) | 40.89 微克(**5.02x (中文(简体) )**(中文(简体) ) | 76.10 微克(含:**9.35个**(中文(简体) ) |
| 现实主义-1 | 8.58 KB (韩语) | 154.56微克 | 255.62 微克(**1.65x (中文(简体) )**(中文(简体) ) | 478.24 微克(含:**3.09x (中文(简体) )**(中文(简体) ) | 1.00毫秒(**6.50x (英语)**(中文(简体) ) |
| 现实主义-2 | 4.30 KB (韩语) | 77.86微克 | 120.31 微克(**1.55x (中文(简体) )**(中文(简体) ) | 571.43 μs (单位:千兆克)**7.34x (中文(简体) )**(中文(简体) ) | 805.15 μs (s)**10.34辆**(中文(简体) ) |
| GitHub 页面 | 1.81 甲基溴 | 20.37分钟 | 30.79毫秒(**1.51x (韩语)**(中文(简体) ) | 309.51 ms (英语:**15.19x (英语)**(中文(简体) ) | 错误 |

`inline-css` gitHub 页面失败, 因为它无法解析其 CSS : `Error: Unexpected } (line 193, char 13771)`。 。 。 .

输入来自 [`benchmarks/benchmarks.json`](https://github.com/Stranger6667/css-inline/blob/master/benchmarks/benchmarks.json):"基本"为: `simple`,"真实主义-1"和"真实主义-2"是 `big_email_1` 财务报告和审定财务报表 `big_email_2`,"GitHub page"为:"GitHub page"是"GitHub Page","GitHub"是"GitHub","GitHub"是"GitHub","GitHub"是"GitHub","GitHub"是"GitHub","GitHub"是"GitHub","GitHub"是"GitHub","GtHub","GtHub"是","GtHub"是" `big_page`。 。 。 . 比率与 `css-inline`。 。 。 .

[`benches/bench.ts`](https://github.com/Stranger6667/css-inline/blob/master/crates/css-inline-js/benches/bench.ts) 运行套房与 `benny` (平均时间; `css-inline 0.23.2`, (中文(简体) ), `juice 11.0.3`, (中文(简体) ), `inline-css 4.0.3`),以稳定方式建造 `rustc 1.99` 关于节点.js `v24.18.0`(原始内容存档于2012-10-10). Ryzen 9 9950X.

## 许可证

凭 [麻省理工学院许可证](https://opensource.org/licenses/MIT)。 。 。 .

## 常见问题

### @css-inline/css-inline 是什么？

用于将 CSS 嵌入 HTML “ 样式” 属性的高性能库

### 如何安装 @css-inline/css-inline？

在项目目录运行 npm install @css-inline/css-inline，或使用 pnpm add / yarn add / bun add。

### @css-inline/css-inline 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @css-inline/css-inline 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @css-inline/css-inline 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 10。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @css-inline/css-inline 可以商用吗？

@css-inline/css-inline 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @css-inline/css-inline 的下载量有多少？

根据 npm 官方下载统计，@css-inline/css-inline 在 2026/10/11 – 2026/11/09 这 30 天内被下载 1,644,459 次，日均约 54,815 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @css-inline/css-inline 还在维护吗？

最新版本 0\.23\.2 发布于 2026/10/27（14 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 14 个；首次发布于 2023/12/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。