# @cocos/rollup-plugin-typescript 中文文档

规范地址：https://npmcn.com/package/%40cocos/rollup-plugin-typescript/

版本：12\.1\.2-cocos\.2
npm 元数据更新时间：2025-05-21T08:20:36.817Z
中文译文更新时间：2026-11-10T06:56:42.746Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cocos/rollup-plugin-typescript
原文对照：https://npmcn.com/package/%40cocos/rollup-plugin-typescript/?lang=original
项目主页：https://github.com/rollup/plugins/tree/master/packages/typescript/#readme
源码仓库：https://github.com/rollup/plugins

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

- 包体积（解压后）：97.8 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：3 个
- peer 依赖：tslib \*，rollup ^2\.14\.0\|\|^3\.0\.0\|\|^4\.0\.0
- 首次发布：2024-12-26T10:36:44.128Z
- 最新版本发布：2024-12-26T10:36:44.404Z
- 近 30 天下载量：2629（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

Rollup和TypeScript之间的无缝集成.

## 安装

```sh
npm install @cocos/rollup-plugin-typescript
```

也可以使用：`pnpm add @cocos/rollup-plugin-typescript`、`yarn add @cocos/rollup-plugin-typescript`、`bun add @cocos/rollup-plugin-typescript`

## README

[![npm](https://img.shields.io/npm/v/@rollup/plugin-typescript)](https://www.npmjs.com/package/@rollup/plugin-typescript) [![size](https://packagephobia.now.sh/badge?p=@rollup/plugin-typescript)](https://packagephobia.now.sh/result?p=@rollup/plugin-typescript) [![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com/)

这是一个打字机滚出插件 [https://github.com/rollup/plugins/tree/master/packages/typescript](https://github.com/rollup/plugins/tree/master/packages/typescript) 。 。 。 .

我们做了一些改变:

-   取决于修改后的版本 `typescript` npm 软件包 (`@cocos/typescript`(中文(简体) )
-   将当前软件包重命名为 `@cocos/rollup-plugin-typescript`

最初的README如下:

# @ rollup/ plugin 类型标记

QQ 为Rollup和Typescript之间的无缝集成而推出的滚动插件.

## 所需资源

此插件需要一个 [长期](https://github.com/nodejs/Release) 节点版 (v14.0.0+)和"滚出" v2.14.0+. 此插件至少还需要 [类型脚本 3.7](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html)。 。 。 .

## 安装

使用 npm :

```console
npm install @rollup/plugin-typescript --save-dev
```

注意两者 `typescript` 财务报告和审定财务报表 `tslib` 是需要单独安装的此插件的对等依赖.

## 为什么?

见 [@ rollup/ plugin- babel](https://github.com/rollup/plugins/tree/master/packages/babel)。 。 。 .

## 使用量

创建一个 `rollup.config.js` [配置文件](https://www.rollupjs.org/guide/en/#configuration-files) 并导入插件 :

```js
// rollup.config.js
import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  output: {
    dir: 'output',
    format: 'cjs'
  },
  plugins: [typescript()]
};
```

那就打电话 `rollup` 要么通过 [国 际](https://www.rollupjs.org/guide/en/#command-line-reference) 或 [API 密码](https://www.rollupjs.org/guide/en/#javascript-api)。 。 。 .

## 选项

插件加载任意 [`compilerOptions`](http://www.typescriptlang.org/docs/handbook/compiler-options.html) 从 `tsconfig.json` 默认文件。 将选项传递到插件直接覆盖这些选项:

```js
...
export default {
  input: './main.ts',
  plugins: [
      typescript({ compilerOptions: {lib: ["es5", "es6", "dom"], target: "es5"}})
  ]
}
```

下列选项对 `@rollup/plugin-typescript`数字 :

### `exclude`

类型 : `String` | `Array[...String]`  
默认 : `null`

A 类 [picomatch 模式](https://github.com/micromatch/picomatch),或图案阵列,该图案将指定构建插件中的文件 _忽略_。默认情况下,不会忽略任何文件.

### `include`

类型 : `String` | `Array[...String]`  
默认 : `null`

A 类 [picomatch 模式](https://github.com/micromatch/picomatch),或图案阵列,指定构建插件中的文件。 默认全部 `.ts` 财务报告和审定财务报表 `.tsx` 文件被锁定.

### `filterRoot`

类型 : `String` | `Boolean`  
默认 : `rootDir` ? `tsConfig.compilerOptions.rootDir` ? `process.cwd()`

可选地解决包含并排除对照目录以外的模式 `process.cwd()`如果指定了字符串,则该值将作为基准目录。 相对路径将针对 `process.cwd()` 先说 若为 `false`,那么这些模式将不会以任何目录来解决.

默认情况下, 模式会解决您 TS 配置文件中的 rootDir 设置 .

在当前工作目录( process.cwd ())外解析文件时, 这可以修正插件错误 .

### `tsconfig`

类型 : `String` | `Boolean`  
默认 : `true`

设置为虚假时, 忽略配置文件中指定的任何选项 。 如果设置为对应文件路径的字符串,则指定的文件将作为配置文件使用.

### `typescript`

类型 : `import('typescript')`  
默认 : _同伴依赖_

覆盖用于转接的TypeScript模块.

```js
typescript({
  typescript: require('some-fork-of-typescript')
});
```

### `tslib`

类型 : `String`  
默认 : _同伴依赖_

覆盖自定义版本的被注入的 TypeScript 助手.

```js
typescript({
  tslib: require.resolve('some-fork-of-tslib')
});
```

### `transformers`

类型 : `{ [before | after | afterDeclarations]: TransformerFactory[] } | ((program: ts.Program) => ts.CustomTransformers)`  
默认 : `undefined`

允许TypeScript自定义变压器在所支持的任何阶段注册:

-   **在此之前**: 变压器将在TypeScript自己的变压器在原始的TypeScript文件中执行
-   **之后**: 变压器将在转接代码的 TypeScript 变压器后执行
-   **声明之后**: 变压器将在声明文件生成后执行, 允许修改现有的声明文件

支持的变压器工厂:

-   全部 **内置** TypeScript 自定义变压器工厂:
    
    -   `import('typescript').TransformerFactory` 附加说明 **变形器事实** 钟声
    -   `import('typescript').CustomTransformerFactory` 附加说明 **自定义 Transformer 事实** 钟声
-   **程序转换事实** 代表一个变压器制造厂,使产生的变压器能够取出一个参考物 **程序** 实例
    
    ```js
    {
      type: 'program',
      factory: (program: Program) => TransformerFactory | CustomTransformerFactory
    }
    ```
    
-   **类型检查器 Transformer Factory** 代表一个变压器制造厂,使产生的变压器能够取出一个参考物 **类型检查器** 实例
    
    ```js
    {
      type: 'typeChecker',
      factory: (typeChecker: TypeChecker) => TransformerFactory | CustomTransformerFactory
    }
    ```
    

```js
typescript({
  transformers: {
    before: [
      {
        // Allow the transformer to get a Program reference in it's factory
        type: 'program',
        factory: (program) => {
          return ProgramRequiringTransformerFactory(program);
        }
      },
      {
        type: 'typeChecker',
        factory: (typeChecker) => {
          // Allow the transformer to get a TypeChecker reference in it's factory
          return TypeCheckerRequiringTransformerFactory(typeChecker);
        }
      }
    ],
    after: [
      // You can use normal transformers directly
      require('custom-transformer-based-on-Context')
    ],
    afterDeclarations: [
      // Or even define in place
      function fixDeclarationFactory(context) {
        return function fixDeclaration(source) {
          function visitor(node) {
            // Do real work here

            return ts.visitEachChild(node, visitor, context);
          }

          return ts.visitEachChild(source, visitor, context);
        };
      }
    ]
  }
});
```

或者,变压器可以在工厂内部产生.

支持的变压器工厂:

-   全部 **内置** TypeScript 自定义变压器工厂:
    
    -   `import('typescript').TransformerFactory` 附加说明 **变形器事实** 钟声
    -   `import('typescript').CustomTransformerFactory` 附加说明 **自定义 Transformer 事实** 钟声

上面的例子可以这样写:

```js
typescript({
  transformers: function (program) {
    return {
      before: [
        ProgramRequiringTransformerFactory(program),
        TypeCheckerRequiringTransformerFactory(program.getTypeChecker())
      ],
      after: [
        // You can use normal transformers directly
        require('custom-transformer-based-on-Context')
      ],
      afterDeclarations: [
        // Or even define in place
        function fixDeclarationFactory(context) {
          return function fixDeclaration(source) {
            function visitor(node) {
              // Do real work here

              return ts.visitEachChild(node, visitor, context);
            }

            return ts.visitEachChild(source, visitor, context);
          };
        }
      ]
    };
  }
});
```

### `cacheDir`

类型 : `String`  
默认 : _.rollup.cache (英语)_

编译时 `incremental` 或者说 `composite` 选项插件将 存储在此文件夹中编译的文件。 这允许使用渐进式 汇编.

```js
typescript({
  cacheDir: '.rollup.tscache'
});
```

### `noForceEmit`

类型 : `Boolean`  
默认 : `false`

较早版本 `@rollup/plugin-typescript` 要求 `compilerOptions` `noEmit` 财务报告和审定财务报表 `emitDeclarationOnly` 两种错误都是为了保证源代码被输入下一个插件/输出中. 这已经不是事实了。 此选项会禁用强制这些选项的值的插件, 转而遵从在 `tsconfig.json`。 。 。 .

`noForceEmit` 如果与您使用 `@rollup/plugin-babel` 财务报告和审定财务报表 `@babel/preset-typescript`。拥有 `@rollup/plugin-typescript` 仅使用 `"emitDeclarationOnly": true` 缓期执行 `@rollup/plugin-babel` 转接可以大幅降低 `rollup` 为大型项目建设时间.

### 字典编译器选项

一些打字符的 [编译选项](https://www.typescriptlang.org/docs/handbook/compiler-options.html) 影响 Rollup 如何构建文件.

#### `noEmitOnError`

类型 : `Boolean`  
默认 : `false`

如果检测到类型出错, 当此选项被设定为真实时, 将中止 Rollup 构建 .

#### `files`, (中文(简体) ), `include`, (中文(简体) ), `exclude`

类型 : `Array[...String]`  
默认 : `[]`

如果声明文件被列入 `files` 字段中 `tsconfig.json` 文档。 这些字段的源文件被忽略,因为Rollup的配置被取而代之.

#### 忽略选项

这些编译器选项被 Rollup 忽略:

-   `noEmitHelpers`, (中文(简体) ), `importHelpers`编号: `tslib` 总是必须使用帮助模块.
-   `noEmit`, (中文(简体) ), `emitDeclarationOnly`: Typescript需要出出代码,用于插件工作.
    -   _说明:虽然早年的重迭都是如此 `@rollup/plugin-typescript`已经不是了 推翻这种行为,并服从 `tsconfig.json` 关于这些选项,参见 [`noForceEmit`](https://npmcn.com/package/%40cocos/rollup-plugin-typescript/#readme-noForceEmit) 选项_
-   `noResolve`: 防止打字符解决代码可能中断编译

### 导入普通JS

虽然不推荐,但可以配置此插件,处理从TypeScript导入的普通JS文件. 为此,您需要指定 `CommonJS` 作为模块格式并添加 [`@rollup/plugin-commonjs`](https://github.com/rollup/plugins/tree/master/packages/commonjs) 将 TypeScript 生成的 CommonJS 输出转换到 ES 模块,以便滚动处理.

```js
// rollup.config.js
import typescript from '@rollup/plugin-typescript';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: './main.ts',
  plugins: [
    typescript({ compilerOptions: { module: 'CommonJS' } }),
    commonjs({ extensions: ['.js', '.ts'] }) // the ".ts" extension is required
  ]
};
```

请注意,这往往会减少最佳产出.

### 保留 JSX 输出

每当选择保留JSX的输出被另一个变换步骤所进一步消耗时 `tsconfig` `compilerOptions` 设置 `jsx: 'preserve'` 或者说 [压倒一切的选项](https://npmcn.com/package/%40cocos/rollup-plugin-typescript/#readme-options),请记住,这个插件本身将无法保存JSX输出,通常以:

```sh
[!] Error: Unexpected token (Note that you need plugins to import files that are not JavaScript)
file.tsx (1:15)
1: export default <span>Foobar</span>
                  ^
```

为了防止这种情况,确保使用橡子插件,即 `acorn-jsx`这将会让罗鲁普的橡子 手柄JSX标志。 (见 [https://rollupjs.org/guide/en/#acorninjectplugins (英语)](https://rollupjs.org/guide/en/#acorninjectplugins)(中文(简体) )

添加后 `acorn-jsx` 插件, 您的 Rollup 配置将看起来像下面, 正确保存您的 JSX 输出 .

```js
import jsx from 'acorn-jsx';
import typescript from '@rollup/plugin-typescript';

export default {
  // … other options …
  acornInjectPlugins: [jsx()],
  plugins: [typescript({ compilerOptions: { jsx: 'preserve' } })]
};
```

### 快速编译

此插件的前几个版本使用了 Typescript's `transpileModule` API,它速度快,但不进行打字检查,也不支持交叉文件特性,如 `const enum`s和出没类型。 如果你想这样做,你可以使用 [@ rollup/ plugin- surcrase](https://github.com/rollup/plugins/tree/master/packages/sucrase) 换句话说.

## 元数据

[捐款](https://npmcn.com/.github/CONTRIBUTING.md)

[利比里亚(麻省理工学院)](https://npmcn.com/LICENSE)

## 常见问题

### @cocos/rollup-plugin-typescript 是什么？

Rollup和TypeScript之间的无缝集成\.

### 如何安装 @cocos/rollup-plugin-typescript？

在项目目录运行 npm install @cocos/rollup-plugin-typescript，或使用 pnpm add / yarn add / bun add。

### @cocos/rollup-plugin-typescript 支持 TypeScript 吗？

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

### @cocos/rollup-plugin-typescript 支持 ESM 还是 CommonJS？

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

### @cocos/rollup-plugin-typescript 需要什么版本的 Node\.js？

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

### @cocos/rollup-plugin-typescript 可以商用吗？

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

### @cocos/rollup-plugin-typescript 的下载量有多少？

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

### @cocos/rollup-plugin-typescript 还在维护吗？

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