# @cssxio/unplugin 中文文档

规范地址：https://npmcn.com/package/%40cssxio/unplugin/

版本：0\.12\.9
npm 元数据更新时间：2026-11-03T12:46:17.850Z
中文译文更新时间：2026-11-11T06:44:26.560Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cssxio/unplugin
原文对照：https://npmcn.com/package/%40cssxio/unplugin/?lang=original
源码仓库：https://github.com/liberocks/cssx

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

- 包体积（解压后）：767 kB，89 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：esbuild \>=0\.27\.0
- 首次发布：2026-09-03T12:55:46.459Z
- 最新版本发布：2026-11-03T12:46:17.318Z
- 近 30 天下载量：2764（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

CSSX 通用捆绑插件.

## 安装

```sh
npm install @cssxio/unplugin
```

也可以使用：`pnpm add @cssxio/unplugin`、`yarn add @cssxio/unplugin`、`bun add @cssxio/unplugin`

## README

# @ cssxio/ unplugin (英语)

CSSX在这些切入点建立了工具适配器:

```ts
import cssxEsbuild from '@cssxio/unplugin/esbuild';
import cssxRollup from '@cssxio/unplugin/rollup';
import cssxRspack from '@cssxio/unplugin/rspack';
import cssxVite from '@cssxio/unplugin/vite';
import cssxWebpack from '@cssxio/unplugin/webpack';
```

对于Next.js,使用支持的集成. 它准备一个完整的样式表,协调编译器工人,处理App路由器的包含和开发更新,并通过Next的普通样式表管道发送CSS. 浏览器桥会检查页面中已经包含的样式表身份,即使在已变形的JavaScript被 stale时也避免了冗余的初始替换;后来的CSS-只编辑在原子上被应用而无需等待JavaScript HMR.

一体化要求 `app/layout.js`, (中文(简体) ), `app/layout.jsx`, (中文(简体) ), `app/layout.ts`, (中文(简体) ), `app/layout.tsx`,或者在 `src/app`。它报告一个没有 App 路由器根布局的项目的配置错误.

```js
// next.config.mjs
import { withCSSX } from '@cssxio/unplugin/next';

export default withCSSX(
  {},
  {
    theme: '@theme reference { --color-brand: #171717; }',
    debug: true,
  },
);
```

CSSX 默认序列 `s…x` 姓名和持续姓名 `.cssx/classnames.json` 生产 `withCSSX` 建设。 开发使用基于模块身份和CSSX调用顺序的源地址复合名称,因此更改文字或长度会让现有的选择器保持稳定. 开发跳过类名压缩,表写,再用分解计划以及缓存项目元数据,所以一个已存在的源文件只有在变化时才会被再转换. Next.js 16个项目可以选择捆绑器 `next dev --webpack` 编号 : `next build --webpack`,或 `next dev --turbopack` 编号 : `next build --turbopack`。MDX源文件由帮助者汇编;安装 `@mdx-js/mdx` 当项目包含时 `.md` 或者说 `.mdx` 文档。 配置可序列化的语句、 复韵或矩形插件 `mdx`启用 `sourceRoots` 用于项目根外链接的工作空间包.

`withCSSX` next.js 开发与生产模式。 其他适配器推断开发来自 `NODE_ENV=development`,活动Vite服务器,开发编译器模式,或Rollup手表模式. Esbuilt 没有标准模式信号, 所以设置 `mode: 'development'` 当然. `mode: 'production'` 禁用开发行为.

`withCSSX` 由同步编曲 `webpack(config)` 调用。 如果一个已有的回调返回一个承诺, 它会发出一个明显的错误, 因为 Next.js 会同步引用这个钩子 .

### 命名和编译协调

遗产 `stableClassNames: true` 选项选择源地址的复合名称(`d…`)并覆盖预期序列复合输出。 这种行为对于相容性没有变化. 新配置可以选择 `naming: 'serial' | 'hash' | 'source'` 与 `coordination: 'memory' | 'manifest'`。 。 。 . `className` 控制序列或散列原子名称和前缀; `naming: 'source'` 选择源地址复合材料,而原子名称继续使用 `className`。 。 。 .

明显的协调将身份分配和序列计数器储存在锁下,然后在解剖上取代JSON文件. 将列表保存在建构之间,以保留系列任务。 新的列表可以指定不同的序列值. 习惯 `classNameAllocator` 仅是程序内,不能与明显的协调相结合,或 `withCSSX`。 。 。 .

对于Webpack和Rspack, `className` 配置 CSSX 内置的分集器,当汇编器实例有相同的项目根和插件选项时,它们共享. 习惯 `classNameAllocator` 替换内置分配器,且必须不使用 `className`;它只控制当前进程内的分配。 当编译程序必须共享序列任务时,使用显示协调.

`debug: true` 打印有效的命名模式、选择器覆盖和编译器绘图状态. `debug: { reportFile: 'path/to/report.json' }` 撰写JSON报告,内容包括公用事业、源址、生成的班级、选择者检查、明显的协调状况以及相互冲突的公用事业制图. `serverClientMappings.status` 实值 `manifest-shared` 当一个清单被配置和收集模块时, `mismatch` 当一个工具映射到不同的类,或 `consistent-in-process` 当收集的模块在一个进程分配器下达成一致时.

将选中的通用适配器添加到您的构建工具 `plugins` 设置 :

```ts
// vite.config.ts
import cssx from '@cssxio/unplugin/vite';

export default { plugins: [cssx()] };
```

### 带有 Vite 的 Vue 3

在 Vite 插件列表中将 CSSX 置于 Vue 之前 。 CSSX 变换 `create` 财务报告和审定财务报表 `sx` 电话 `<script>`, (中文(简体) ), `<script setup>`,以及 `:class="sx(...)"` 模板 装订。 静态平原 `class="..."` 属性被故意留下.

```ts
import cssx from '@cssxio/unplugin/vite';
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [cssx(), vue()] });
```

```js
// rollup.config.js
import cssx from '@cssxio/unplugin/rollup';

export default { plugins: [cssx({ cssFileName: 'assets/cssx.css' })] };
```

```js
// webpack.config.js
import cssx from '@cssxio/unplugin/webpack';

export default { plugins: [cssx()] };
```

```js
// rspack.config.js
import cssx from '@cssxio/unplugin/rspack';

export default { plugins: [cssx()] };
```

```js
// build.mjs
import cssx from '@cssxio/unplugin/esbuild';
import { build } from 'esbuild';

await build({ entryPoints: ['src/main.ts'], bundle: true, plugins: [cssx()] });
```

## 程序化 API

主要入口出口低层 `unpluginFactory`, 普遍性 `unplugin` 适配器的例子, 并命名可调用工厂 Vite, Rollup, webpack, Rspack, 和建设。 大多数应用程序应导入上述一个平台入口.

```ts
import { transformCssxModule, compileCssxStylesheet } from '@cssxio/unplugin';

const transformed = await transformCssxModule(source, 'src/button.tsx');
const stylesheet = await compileCssxStylesheet([
  {
    id: 'src/button.tsx',
    candidates: transformed?.candidates ?? {},
    origins: transformed?.origins,
    composites: transformed?.composites,
    atomicClasses: transformed?.atomicClasses,
  },
]);
```

`transformCssxModule` 返回时 `null` 除非源模块导入已配置的 CSSX 运行时间 。 否则它返回已转换的JavaScript,候选元数据,复合到原子选择器元数据,源位置,以及当变换创建一个时的JavaScript源图. 通过一个较早相容的版本3源地图作为它的第四个参数来延续该地图.

`compileCssxStylesheet` 将模块元数据与稳定模块和公用顺序相结合,去掉重复的公用功能,将每个取胜的原子规则别名给使用它的复合类,并返回生成的CSS. 当收集的元数据包括源位置时,它也会返回 CSS 源地图. `CssxPluginOptions`, (中文(简体) ), `TransformResult`, (中文(简体) ), `IncomingSourceMap`, (中文(简体) ), `CssxSourceModule`,样式表源图类型则从主入口导出.

## 选项

| 选项 | 默认 | 它会做什么 |
| --- | --- | --- |
| `importSource` | `@cssxio/cssx` | 模块描述符,用于识别要转换的源文件. 源文件必须包含此文本并具有JavaScript或TypeScript扩展名. |
| `mode` | 推断 | 选择 `development` 或者说 `production` 行为 建设需要明确的开发模式. |
| `cssFileName` | `cssx.css` | 相对 CSS 输出路径 。 一定不是空的,结束 `.css`,并保留在捆绑输出目录中. `[hash]` 被生成的 CSS 的稳定散列所取代. |
| `naming` | `serial` | 选择生成的复合命名 : `serial`, (中文(简体) ), `hash`,或源地址 `source`独立于编译器的协调. |
| `coordination` | `memory` | 在一个适配实例中协调任务(`memory`或通过一种顽固的表象(`manifest`) (中文(简体) ). |
| `manifestPath` | —— 说 | JSON 文件使用时 `coordination: 'manifest'`独立编译人员必须共享这一路径. |
| `className` | 序列 `s…x` | 控制原子命名格式,前缀,后缀,和散列长度. 由每个适配器使用的编译器分配器所尊重. |
| `classNameAllocator` | —— 说 | 自定义的进程集成分配器 。 奥米 `className` 在提供时; 明显的协调使用 CSSX 的持续分配器. |
| `stableClassNames` | `false` | 折旧的相容性别名 `naming: 'source'`; 发送源地址 `d…` 复合材料并取代了序列复合产品. |
| `stableClassNameStrategy` | `source-location` | 为源地址复合材料选择源位置身份或模块顺序身份. 选择开发适配器 `module-order`。 。 。 . |
| `debug` | `false` | 打印简明的产出摘要或写出类/源/选取JSON诊断报告. |
| `sourceRoots` | 项目根 | 包含在项目元数据扫描中的其他源目录,如链接的工作空间包. |
| `sourceMap` | `true` | 是否生成单独的 CSS 源图 。 开发默认为 `false` 使温暖更新更轻; 设定 `sourceMap: true` 包括开发CSS地图. |
| `layer` | —— 说 | 包裹生成 CSS 的 CSS 层名 。 它必须是单一的有效层标识符,例如 `cssx`。 。 。 . |
| `theme` | —— 说 | 内置 CSSX `@theme` 转换和编译 CSS 时使用的源 。 主题被编译为生成的规则;它不添加全局样式表. |
| `themeFile` | —— 说 | 路径, 相对于当前工作目录, 到 CSSX `@theme` 文档。 生成 CSS 时重读; 滚动相容适配器将其注册为被监视的依赖. 别用它 `theme`。 。 。 . |
| `darkMode` | `media` | 激活 `dark:` 系统彩色化学媒体查询的公用设施(`media`, (中文(简体) ), `[data-theme=dark]` (单位:千美元)`selector`),或 a `.dark` 祖先(`class`) (中文(简体) ). 使用匹配您主题控制器的选择器 . |
| `preflight` | `true` | 在公用设施之前添加 Tailwind 兼容浏览器基线规则 。 准备吧 `false` 只有在应用程序有意拥有不同的全局重置时. |

通用适配器在创建时验证选项. `theme` 财务报告和审定财务报表 `themeFile` 无法一起使用 。 无效的 CSS 路径和图层名称在 CSS 发布前失败构建 .

CSSX 默认释放 Tailwind 兼容浏览器基线, 所以实用性 移徙保留了框大小、继承的打字法、联系处理和本地 形式控制正常化。 设定 `preflight: false` 仅在已有应用程序时 样式表有意拥有不同的全局元素样式.

## 提取的 CSS

每个生产适配器从最终构建所使用的源文件收集CSS. 当没有被使用的文件有 CSSX 工具时, 它不会创建 CSS 文件 。 默认文件是 `cssx.css`设置 `cssFileName` 用另一个相对路径。 CSSX为每个静态样式组成在加分中发出一个复合类,同时在样式表中共享复合选择器之间的声明.

为了遗产 `stableClassNames: true` cSSX在发布其公共样式表前扫描项目源树。 Next.js集成拥有源编译通道,不要求消费者添加扫描仪,资产重装,样式表链接,或插件钩.

与 Rollup相容的适配器保留已转换的模块元数据,直到 `generateBundle`,然后将CSS及其地图作为建设资产。 网页软件包和Rspack适配器保留了本地模块的元数据,并在添加阶段释放资产 `processAssets`。直接 esbuilt 适配器可启用元文件,删除其缺失的源文件的数据,并在其中生成 CSS `onEnd`。 。 。 .

何时 `sourceMap` 已启用,有源地址,生成 CSS 有单独的 `.css.map` 文件和源图注释。 每个映射都指向创建规则的静态公用字符串的源模块位置. `transformCssxModule` 可以接受并返回JavaScript源图,用于提供相容输入图的构建工具.

在开发过程中,所有适配器都使用缓存的源协调器,并独立于JavaScript捆绑完成而将样式表修改推给只开发的事件流. Vite 服务于它所配置的基础路径下的活动流; Next.js, Webpack, Rspack, Rollup watch, 并明确允许 Esbuild 开发 构建使用回路传输 。 被注入的浏览器桥会自动替换样式表,保留页面状态并避免手动刷新. 在初始文档中保留生成的样式表, 因此 CSS 在第一次更新前就已存在 。 开发监视器和浏览器运输在生产建设中被省略.

CSS源图在开发过程中默认关闭,以减少样式表编译时间和内存使用. 设定 `sourceMap: true` 当您需要调试生成 CSS 映射时; 制作会保留默认的源地图行为 .

资源使用是在开发期间确定的。 共享项目扫描器在一个过程中最多打开了64个正在运行的所有CSSX项目的目录监视器. Vite and esbuild使用一个本地快道,封顶在另外8个目录监视器上;它们监视目录而不是单个文件,如果本地监视器失败或达到封顶,则会倒回捆绑器监视器. 虚拟组合重复通知和样式表编译,最多同时转换四个已更改的模块,并封顶256个飞行路径。 滚动编制现有仅更新 CSS `watchChange` 在通过一个队列将重建和序列化的时间排出之前,最多256个待修改模块。 扫描机封顶在256个待取路径上,将相接的相接部分排入一个对齐,并依次更改模块。 被停止的协调员释放其元数据缓存;最多保留了8个不活动的项目快照. 固定大小的文摘避免为编辑检查保留完整的源文本. Vite最多保存了64个已准备好的文摘; 卷起并建造每个封顶,准备64个条目的变换; 估计留存的变换数据的16个MIB. Next.js样式表流每个应用程序最多接受64个浏览器客户端,并且只保留一个慢客户端的最新更新队列.

如果一个Vite-power-SSR框架跳过Vite的HTML变换钩子,CSSX会在被制成的响应中注入它的桥. 倒置缓冲器每次响应最多为1个米B和4,096个块,最多一次有8个响应缓冲;过量或过量响应不注射而通过.

100 ms 的入球测量一个温和的现有风格的保存,直到下一个动画框之后的已改变的计算样式可见为止. 它不包括冷启动,新引入的调用站点,JavaScript编辑,全主题变化,或组成-结构变化. 运行 `pnpm benchmark:dev-hmr` 用于缓存编译器基准和 `pnpm test:hmr` 用于浏览器保存到可见的基准 横跨 Esbuild, Rollup, Webpack, 和 Rspack. Vite和Next.js浏览器的基准运行在视觉测试矩阵中. 单是编译器计时就不是一个浏览器保存到可见的测量.

随着重建, `outdir` 将 CSS 置于目录下方. `outfile` 将其放在输出文件旁边。 没有两种选择,它都放在工作目录下。 与 `write: false`, CSS 及其地图附在 Esbuilt 的记忆中 `outputFiles`;否则它们会被写入磁盘. 后期的 Esbuild 架构删除 CSSX 在没有公用设施存在时所写的 CSS 文件 .

见 [工作空间读取](https://npmcn.com/package/README.md) 用于CSSX语法、支持的公用事业和当前排除.

## 常见问题

### @cssxio/unplugin 是什么？

CSSX 通用捆绑插件\.

### 如何安装 @cssxio/unplugin？

在项目目录运行 npm install @cssxio/unplugin，或使用 pnpm add / yarn add / bun add。

### @cssxio/unplugin 支持 TypeScript 吗？

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

### @cssxio/unplugin 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cssxio/unplugin 可以商用吗？

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

### @cssxio/unplugin 的下载量有多少？

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

### @cssxio/unplugin 还在维护吗？

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