# @douyinfe/semi-vite-plugin 中文文档

规范地址：https://npmcn.com/package/%40douyinfe/semi-vite-plugin/

版本：2\.105\.0
npm 元数据更新时间：2026-11-12T09:39:20.907Z
中文译文更新时间：2026-11-12T23:30:32.800Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40douyinfe/semi-vite-plugin
原文对照：https://npmcn.com/package/%40douyinfe/semi-vite-plugin/?lang=original

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

- 包体积（解压后）：37.5 kB，15 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vite \>=3\.0\.0
- 首次发布：2026-05-20T08:13:01.903Z
- 最新版本发布：2026-11-12T09:39:20.639Z
- 近 30 天下载量：3059（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

用于Semi Design自定义主题,替换前缀等的vite插件.

## 安装

```sh
npm install @douyinfe/semi-vite-plugin
```

也可以使用：`pnpm add @douyinfe/semi-vite-plugin`、`yarn add @douyinfe/semi-vite-plugin`、`bun add @douyinfe/semi-vite-plugin`

## README

> 用于Semi Design自定义主题,替换前缀等的vite插件.

## 导言

该插件为带有Vite的"半设计"所设计,提供两个主要能力:

-   自定义主题
-   替换 CSS 选择器的前缀

> 注:插件通过软件包路径检测出半相关依赖性. 它支持两者 `@douyinfe/semi-ui` 和版本后缀软件包 `@douyinfe/semi-ui-19` (亦为 `semi-icons`) (中文(简体) ).

## 使用量

### 安装

安装 `@douyinfe/semi-vite-plugin` 作为一种发展依赖:

```shell
npm install --save-dev @douyinfe/semi-vite-plugin
# or
yarn add --dev @douyinfe/semi-vite-plugin
# or
pnpm add -D @douyinfe/semi-vite-plugin
```

### 自定义主题

Semi Design使用Scs变量来取出上千个 Design Tokens. 您可以替换 通过此插件实现主题定制的这些符号 . [更多信息](https://semi.design/dsm/)

您可以通过三种方式自定义主题:

-   由 Semi DSM 生成 npm 包
-   您工程中的本地 Scs 文件
-   将密钥值对参数传递到插件

优先从低到高.

#### 通过 npm 软件包

完成定制后 [半设计系统](https://semi.design/dsm/),半DSM 将生成 npm 软件包,然后像这样使用:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            theme: '@semi-bot/semi-theme-yours',
        }),
    ],
});
```

#### 通过本地 Scs 文件

您可以检查您在 [半网站](https://semi.design/en-US/basic/tokens)。 。 。 .

步骤1: 添加本地文件

```scss
// local.scss
$font-size-small: 16px;
```

第2步: 配置 vite

```ts
// vite.config.ts
import path from 'path';
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            include: path.resolve(__dirname, 'local.scss'),
        }),
    ],
});
```

#### 通过参数

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            variables: {
                '$font-size-small': '16px',
            },
        }),
    ],
});
```

### 替换 CSS 选择器的前缀

Semi Design所使用的 CSS 选择器的前缀为 `semi` 默认 (例如:. `.semi-button`) (中文(简体) ). 您可以通过此插件替换前缀 :

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            prefixCls: 'custom',
        }),
    ],
});
```

然后获得替换的CSS选择器(例如. `.custom-button`) (中文(简体) ).

### 用 CSS 层环绕输出样式

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            cssLayer: true,
        }),
    ],
});
```

## API 密码

### 半主题( 选项)

| 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `theme` | `string | { name?: string }` | \- 说吧 | 由 Semi DSM 生成的自定义主题包名 . |
| `prefixCls` | `string` | `semi` | CSS类名的前缀. |
| `variables` | `Record<string, string | number>` | `{}` | Scs变量的键值对. |
| `include` | `string` | \- 说吧 | 用于在主题变量后注入 Scs 文件的绝对路径 . |
| `cssLayer` | `boolean` | `false` | 何时 `true`,将最后编译的 CSS 包成 `@layer semi { ... }`。 。 。 . |
| `omitCss` | `boolean` | `false` | 评论 `.css` 在半包内导入。 当集成框架无法从中导入全球CSS时有用 `node_modules` 直接说. |

## 如何运作

1.  **CSS → SCSS 重写**: 拦截请求 `@douyinfe/semi-(ui|icons|foundation)/lib/**/*.css`,将后缀切换为 `.scss` 并读取原始 Sass 源.
2.  **主题注入**: 插入主题 `index.scss` 编号 : `global.scss` 编号 : `animation.scss` 编号 : `local.scss` / 用户提供的变量和 `include` 文档,加 `$prefix` 和(可选) `@layer semi { ... }` 包装.
3.  **Sass 汇编**: 用 `sass.compileString`,解决 `~package/...` 按节点导入 原始树 `.scss` 文档.
4.  **前缀补丁**: 对于匹配的文件 `@douyinfe/semi-*/.../env.js`,重写 `BASE_CLASS_PREFIX` 常数到配置 `prefixCls`实现同样的目标 替换 Vite 的 dev-mode dep 预捆绑的工作 (`.vite/deps`页:1 esbuild 插件通过 `optimizeDeps.esbuildOptions.plugins` 改为 在预捆绑时间也重写嵌入模块.
5.  **删除Cs**: 发表可选评论 `.css` 半包内导入 他们没找到绑匪.

## 财务问题

### 为什么班名还保留下来 `semi-*` 内 `vite dev`? 吗?

虚拟预捆绑 `node_modules` 软件包输入 `.vite/deps` 使用建设 (或以Vite 8+为倒数. 何时 `prefixCls` 设置,此插件插入一个 新建重写相关插件 `env.js` 预捆绑内的文件. 如果你之前开始 `vite` 一次没有插件( 或者有不同的插件) `prefixCls`),你可能有一个 stale `.vite/deps` 缓存。 停止 dev 服务器 运行 `rm -rf node_modules/.vite` 迫使一个干净的再捆绑.

### Vite 8 打印出一个关于 `optimizeDeps.esbuildOptions`

Vite 8 切换到 Rolldown 进行分解预拆, 现在更喜欢 `optimizeDeps.rolldownOptions`。该插件仍然使用 `optimizeDeps.esbuildOptions` 用于与 Vite 3 的广泛兼容性; 滚动 所以警告是无害的 并且前缀 重写仍然正确 .

## 相关

-   [半设计](https://semi.design/)
-   [`@douyinfe/semi-webpack-plugin`](https://www.npmjs.com/package/@douyinfe/semi-webpack-plugin)
-   [`@douyinfe/semi-rspack-plugin`](https://www.npmjs.com/package/@douyinfe/semi-rspack-plugin)

## 常见问题

### @douyinfe/semi-vite-plugin 是什么？

用于Semi Design自定义主题,替换前缀等的vite插件\.

### 如何安装 @douyinfe/semi-vite-plugin？

在项目目录运行 npm install @douyinfe/semi-vite-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（\>=3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @douyinfe/semi-vite-plugin 支持 TypeScript 吗？

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

### @douyinfe/semi-vite-plugin 支持 ESM 还是 CommonJS？

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

### @douyinfe/semi-vite-plugin 可以商用吗？

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

### @douyinfe/semi-vite-plugin 的下载量有多少？

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

### @douyinfe/semi-vite-plugin 还在维护吗？

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