# @graphox/babel-plugin 中文文档

规范地址：https://npmcn.com/package/%40graphox/babel-plugin/

版本：1\.5\.2
npm 元数据更新时间：2026-11-16T15:03:19.095Z
中文译文更新时间：2026-11-16T22:54:14.348Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：108 kB，24 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-02-26T10:41:38.274Z
- 最新版本发布：2026-11-16T15:03:18.653Z
- 近 30 天下载量：24244（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

Graphox 编码插件 Babel

## 安装

```sh
npm install @graphox/babel-plugin
```

也可以使用：`pnpm add @graphox/babel-plugin`、`yarn add @graphox/babel-plugin`、`bun add @graphox/babel-plugin`

## README

# @ graphox/ babel- 插件

## 概览

确保 GraphQL AST 文件被正确编码,防止它们在初始块中结束 .

## 为什么使用这个插件?

Codegen 已经在编译时间生成 AST 文件 。 问题在于捆绑者的行为:

**没有插件 :**

```
Initial chunk: ALL generated AST files (~50KB+)
Lazy chunks: empty or minimal
```

**带有插件 :**

```
Initial chunk: ~1KB (just imports)
Lazy chunks: each operation in its chunk
```

## 安装

```bash
pnpm add --save-dev @graphox/babel-plugin
```

## 快速启动

### 1\. 配置图解

```yaml
# graphox.yaml
output_dir: "__generated__"
projects:
  - schema: "schema.graphql"
    include: "src/**/*.{ts,tsx}"
```

### 2\. 运行代码源

```bash
pnpm graphox codegen
```

### 3\. 配置贝贝

```javascript
// babel.config.js
const path = require('path');

module.exports = {
  presets: ['@babel/preset-typescript'],
  plugins: [
    ['@graphox/babel-plugin', {
      manifestPath: path.resolve(__dirname, '__generated__/manifest.json'),
      outputDir: path.resolve(__dirname, '__generated__'),
      graphqlImportPaths: ['@/graphql']
    }]
  ]
};
```

## Metro( 反应原生)

地铁在车盖下使用巴别尔变压器. 配置在 `metro.config.js`数字 :

```javascript
// metro.config.js
module.exports = {
  transformer: {
    babelTransformerPath: require.resolve('@graphox/babel-plugin'),
  },
};
```

为了完全兼容,请在 `babel.config.js`。 。 。 .

## 代码分割影响

| 配置 | 初始块 | 超级懒鬼 |
| --- | --- | --- |
| 没有插件 | ~50KB+(全部 AST) 组合键 | ~ 1KB 键 |
| 带有插件 | ~ 1KB 键 | ~ 1KB 键 |

## 多个项目

在一个插件条目中记录每个输出目录的构建解析, 所以 跨越项目边界的导入可以重写 :

```js
['@graphox/babel-plugin', {
  outputs: [
    { outputDir: path.resolve(__dirname, '__generated__') },
    { outputDir: path.resolve(repoRoot, 'packages/catalog/graphql') },
  ],
}]
```

在拥有输出的软件包中,文档是通过相对路径导入的. 跨越包的边界, 导入通过包的公开 相反,因为相对路径会通过它的子路径输出:

```js
// before
import { ProductCardFragmentDoc } from "@example/catalog/graphql";
// after
import { ProductCardFragmentDoc } from "@example/catalog/graphql/catalog.codegen";
```

这需要自有软件包来导出输出目录中的文件 :

```json
{
  "name": "@example/catalog",
  "exports": {
    "./graphql": "./graphql/index.ts",
    "./graphql/*": "./graphql/*"
  }
}
```

从包件中推断出规格 `name` 财务报告和审定财务报表 `exports`,带有警告 指定缺少通配符时要添加的确切条目。 推论只有火 当一个 `exports` 子路径解析到输出目录, 因此设置 `importAlias` 明确用于没有可用的软件包 `exports` 字段.

文件名称和来源可能在产出中重复——决议的范围为: 输入的切入点。 输出目录必须明确且必须 不是窝.

## 配置选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `outputs` | `object[]` | 对\* | 每个项目一个条目;见下文 |
| `emitExtensions` | `string` | 没有 | 生成导入的文件扩展名 : `"none"` (违约), `"ts"`, (中文(简体) ), `"js"`, (中文(简体) ), `"dts"` |

每个条目 `outputs`数字 :

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `outputDir` | `string` | 对 | 包含生成文件的目录 |
| `manifestPath` | `string` | 没有 | 路径 `manifest.json`默认为 `<outputDir>/manifest.json` |
| `manifestData` | `object[]` | 没有 | 内含显示数据, 而不是 `manifestPath` |
| `graphqlImportPaths` | `string[]` | 没有 | 作为 GraphQL 切入点处理的额外导入路径 |
| `importAlias` | `string` | 没有 | 此输出的公开指定符 。 从包裹里引出 `name` 财务报告和审定财务报表 `exports` |
| `packageRoot` | `string` | 没有 | 拥有此输出的软件包的根 。 推断为最近的目录 `package.json` |

\* 单产出形式——这些字段位于顶层而不是内部 `outputs` ——仍被接受并行为为一要素 `outputs`。 。 。 .

### 喷出量

控制所生成导入路径所附加的文件扩展名。 应该符合 `emit_extensions` 设置 `graphox.yaml`数字 :

| 数值 | 结果 |
| --- | --- |
| `"none"` (默认) | `import { X } from "./file.codegen"` |
| `"ts"` | `import { X } from "./file.codegen.ts"` |
| `"js"` | `import { X } from "./file.codegen.js"` |
| `"dts"` | `import { X } from "./file.codegen.d.ts"` |

## 分块文档

何时 `generate_ast_for_fragments: true` 在配置中被启用,片段文档也包含在运算表中,并由插件正确重写.

没有文件的碎片,例如: `@type_only` 一,单从其出处列出于清单. 插件替换其 `graphql()` 调用 `{}`,该值 `graphql.ts` 返回它,所以 `ResultOf<typeof Doc>` 仍然按键.

与 `graphql_tag_fallback: true`, (中文(简体) ), `graphql.ts` 在运行时剖析这样的片段, 插件无法做到这一点 。 碎片则从清单中被忽略出,插件则无法在其上建构 `graphql()` 电话.

## 何时使用

| 构建工具 | 建议插件 |
| --- | --- |
| 原生反应( Metro) | 宝贝 |
| 网络软件包 | 宝贝 |
| 创建反应应用 | 宝贝 |
| 故事书 | 宝贝 |
| 建设 | 使用 SWC 插件 |
| 涡轮包装/下游js | 使用 SWC 插件 |

## 另见

-   [SWC 插件](https://npmcn.com/package/%40graphox/swc/README.md)
-   [图表CLI](https://npmcn.com/package/README.md)
-   [配置指南](https://npmcn.com/package/docs/configurations.md)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40graphox/babel-plugin/LICENSE)。 。 。 .

## 常见问题

### @graphox/babel-plugin 是什么？

Graphox 编码插件 Babel

### 如何安装 @graphox/babel-plugin？

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

### @graphox/babel-plugin 支持 TypeScript 吗？

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

### @graphox/babel-plugin 支持 ESM 还是 CommonJS？

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

### @graphox/babel-plugin 可以商用吗？

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

### @graphox/babel-plugin 的下载量有多少？

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

### @graphox/babel-plugin 还在维护吗？

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

