# @comfyorg/fbx-exporter-three 中文文档

规范地址：https://npmcn.com/package/%40comfyorg/fbx-exporter-three/

版本：1\.0\.2
npm 元数据更新时间：2026-11-01T18:51:22.649Z
中文译文更新时间：2026-11-10T11:45:23.751Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40comfyorg/fbx-exporter-three
原文对照：https://npmcn.com/package/%40comfyorg/fbx-exporter-three/?lang=original
项目主页：https://comfy.org/
源码仓库：https://github.com/Comfy-Org/fbx-exporter-three

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

- 包体积（解压后）：427 kB，123 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- peer 依赖：three \>=0\.160\.0，@types/three \>=0\.160\.0
- 首次发布：2026-05-19T00:40:04.681Z
- 最新版本发布：2026-09-23T00:45:45.269Z
- 近 30 天下载量：281719（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

FBX出口国为3.js场景——二进制的FBX编剧,配有全裸,动画,形态目标,灯光,相机和纹理嵌入.

## 安装

```sh
npm install @comfyorg/fbx-exporter-three
```

也可以使用：`pnpm add @comfyorg/fbx-exporter-three`、`yarn add @comfyorg/fbx-exporter-three`、`bun add @comfyorg/fbx-exporter-three`

## README

# @comfyorg/fbx-exporter- three (中文(简体) )

FBX 二进制导出 3.js 场景 — Unity / 不真实 / Maya / Blender / 3.js 自己的场景 `FBXLoader` 都干净地消耗了产出.

-   **自成一体**: 类型脚本来源,船舶无害环境管理 `.js` + 键 `.d.ts`。只有运行时间解调器 `fflate` (zlib) (英语).
-   **一发或同步**数字 : `parseSync` 当纹理是 `DataTexture`或缺席; `parseAsync` 当纹理需要基于画布的编码时( name`HTMLImageElement` 编号 : `ImageBitmap` /成为目标).
-   **工具预设**数字 : `threejs`, (中文(简体) ), `unity`, (中文(简体) ), `unreal`, (中文(简体) ), `blender`, (中文(简体) ), `maya` ——为目标选择右轴会战+单位规模.
-   **封面**: meshes,多紫外线层,材料,纹理(PNG-嵌入),剥皮,动画(TRS +形态),形态目标,灯光,相机.

## 安装

```bash
npm install @comfyorg/fbx-exporter-three
```

端点 : `three >= 0.160` (必须), `@types/three >= 0.160` (可选的,只有使用 TypeScript ).

## 类型脚本

来源以 TypeScript; 已发布 `dist/` 船舶无害环境管理 `.js` + 键 `.d.ts`公共类型包括: `FBXExporter`, (中文(简体) ), `FBXExportOptions`, (中文(简体) ), `FBXPreset`, (中文(简体) ), `FBXAxis`, (中文(简体) ), `FBXExporterPlugin`。 。 。 .

## 快速启动

```js
import * as THREE from 'three';
import { FBXExporter } from '@comfyorg/fbx-exporter-three';
import { writeFileSync } from 'node:fs';

const scene = new THREE.Scene();
scene.add(new THREE.Mesh(
  new THREE.BoxGeometry(1, 1, 1),
  new THREE.MeshStandardMaterial({ color: 0x6688ff }),
));

const exporter = new FBXExporter();
const bytes = exporter.parseSync(scene);

writeFileSync('cube.fbx', bytes);
```

结果是二进制 FBX (`Kaydara FBX Binary` 魔法)可以直接掉入Unity,unreal,Blender,Maya,或者装入回放 `FBXLoader`。 。 。 .

## API 密码

### `class FBXExporter`

```js
const exporter = new FBXExporter();
```

#### `parseSync(input, options?) → Uint8Array`

在一个呼叫中构建一个FBX. 用于静态场景,只有 `DataTexture`s,或者当你已经 编码了所有的纹理.

| 选项 | 类型 | 默认 | 页:1 |
| --- | --- | --- | --- |
| `preset` | `'threejs' | 'unity' | 'unreal' | 'blender' | 'maya'` | `'threejs'` | 选择轴+单位默认值. |
| `axisUp` | `'X' | 'Y' | 'Z' | '-X' | '-Y' | '-Z'` | 预设 | 覆盖预设 . |
| `axisForward` | 不变 | 预设 | 覆盖预设 . |
| `unitScale` | `number` | 预设 | 写入 `GlobalSettings.UnitScaleFactor`。 。 。 . |
| `bakeSpaceTransform` | `boolean` | `false` | 前相乘轴矩阵为几何. 见下文限制说明. |
| `version` | `number` | `7400` | FBX版本(支持7400/7500). |
| `fps` | `number` | `24` | 动画帧率. |
| `embedTextures` | `boolean` | `true` | 何时 `false`,纹理通过文件路径而不是嵌入来引用. |
| `animations` | `AnimationClip[]` | 自动 | 如果省略,我们从 `input.animations` (《公约》 `GLTFLoader` 编号 : `FBXLoader`) (中文(简体) ). |
| `includeAnimations` | `boolean` | `true` | 设定 `false` 只导出一个静态 T-pose (skips AnimStack/ Curve 节点). |
| `onlyVisible` | `boolean` | `false` | 跳过对象3D `.visible` 实值 `false`。 。 。 . |
| `objectFilter` | `(o: Object3D) => boolean` | —— 说 | 通用上游-返回 `false` 以跳过对象。 编为 `onlyVisible`。 。 。 . |
| `customProperties` | `boolean` | `false` | 发送每个对象3D `userData` 作为用户定义的属性70条目。 地图布林斯- `p_bool`整数 + `p_integer`,浮点 − `p_double`,字符串 —— `p_string`,长度 - 数字数组 `p_vector_3d`其他联署材料的价值观使JSON弦化为 `p_string`。 。 。 . |
| `creator` | `string` | `@comfyorg/fbx-exporter-three - <ver>` | 自定义字符串写入 FBX `Creator` 元数据. |

#### `parseAsync(input, options?) → Promise<Uint8Array>`

与 `parseSync` 但等待着同步纹理编码路径—— `HTMLImageElement`, (中文(简体) ), `ImageBitmap`,画布/投放目标纹理均需 `canvas.toBlob()` 这是同步。 当您的材料引用纹理时使用此功能 `TextureLoader` (任何带有帆布 API 的环境).

```js
const bytes = await new FBXExporter().parseAsync(scene);
```

#### `register(callback)` 编号 : `unregister(callback)`

3的样式插件钩子 。 Js's (英语) `GLTFExporter`复选 `sceneData` (所收集的场景计划)在采集和纹理编码之后,在序列化之前:

```js
exporter.register((sceneData) => {
  // e.g. swap pre-encoded PNG bytes into texture entries
  for (const [tex, entry] of sceneData.textures.textures) {
    if (tex.userData.preEncodedPng) entry.imageBytes = tex.userData.preEncodedPng;
  }
});
```

### 方便出口

```js
import {
  FBXExporter,
  PRESETS,            // tool preset table
  resolvePreset,      // merge user options onto a preset
  encodeRGBA8PNG,     // pure-JS PNG encoder used internally
} from '@comfyorg/fbx-exporter-three';
```

## 特征覆盖

| 三.js 输入 | FBX 输出 |
| --- | --- |
| `Mesh` + 键 `BufferGeometry` (位置/ 常态/ 顶点颜色) | `Geometry` + 键 `LayerElementNormal` 编号 : `LayerElementColor` 编号 : `LayerElementMaterial` |
| 多个紫外线装置—— `attributes.uv` 编号 : `uv1` 编号 : `uv2` 编号 : `uv3` (用于光映射/AO) | 多个 `LayerElementUV` 不同节点 `TypedIndex` + 每组 `Layer` 条目 |
| `MeshStandardMaterial` 编号 : `MeshPhongMaterial` 编号 : `MeshBasicMaterial` | `Material` 与 `FbxSurfacePhong` 阴影模型 |
| `Texture` (数据图、HTML图像、画布) | `Texture` + 键 `Video` 有嵌入式 PNG 字节 |
| `Group`, (中文(简体) ), `Object3D` | `Model` (诺尔) |
| `SkinnedMesh` + 键 `Skeleton` + 键 `Bone` | `Deformer` (皮肤)+ `Deformer` (组分)每根骨头+ `Pose` (BindPose) + (英语) `Model` 每根骨头 |
| `AnimationClip` (位置/旋转/比例轨道) | `AnimationStack` + 键 `AnimationLayer` + 键 `AnimationCurveNode` + 键 `AnimationCurve` |
| 溶液目标(`morphAttributes.position`(中文(简体) ) | `Geometry` (形状)每平方圆+ `Deformer` (蓝发)+ `Deformer` (Blend ShapeChannel) (英语) |
| 墨迹动画( 组合) `morphTargetInfluences` 音轨) | 每道 `AnimationCurveNode` 驾驶 `DeformPercent` |
| `PointLight` 编号 : `DirectionalLight` 编号 : `SpotLight` | `NodeAttribute` (灯光) - `light.target.position` 往返 `LookAtProperty` |
| `PerspectiveCamera` 编号 : `OrthographicCamera` | `NodeAttribute` (卡梅拉语) |
| 轴/单位转换 | `GlobalSettings.UpAxis` 编号 : `FrontAxis` 编号 : `UnitScaleFactor` |

## 工具预设

| 预设 | 上轴 | 前轴 | 单位比例 | 贝克 | 当.. |
| --- | --- | --- | --- | --- | --- |
| `threejs` (默认) | Y | 页:1 | 1个 | 关 | 绕行 `FBXLoader`。 。 。 . |
| `unity` | Y | 页:1 | 1个 | 关 | 导入到 Unity( 它尊重文件轴) . |
| `unreal` | 页:1 | 页:1 | 1个 | 关 | 导入到不真实编辑器 。 Unreal 的导入者在 GlobalSettings 宣布时处理轴转换 . |
| `blender` | Y | 页:1 | 100个 | 关 | Blender 的文件 。 单位比例=100,因为 Blender 存储仪表,但 FBX 犬形单元为公分. |
| `maya` | Y | 页:1 | 100个 | 关 | 和Blender一样. |

```js
// Use a preset:
exporter.parseSync(scene, { preset: 'unreal' });

// Or set axes directly:
exporter.parseSync(scene, { axisUp: 'Z', axisForward: 'X' });

// Mix: preset defaults + selective override:
exporter.parseSync(scene, { preset: 'unity', unitScale: 100 });
```

## 实例

### 皮肤+动画字符

```js
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { FBXExporter } from '@comfyorg/fbx-exporter-three';

const gltf = await new GLTFLoader().loadAsync('character.glb');
const scene = gltf.scene;
scene.animations = gltf.animations;  // wire so the exporter finds them

const bytes = await new FBXExporter().parseAsync(scene);
```

### 磁盘的纹理( 节点)

```js
const tex = new THREE.DataTexture(rgbaPixels, w, h, THREE.RGBAFormat);
tex.needsUpdate = true;
material.map = tex;

const bytes = new FBXExporter().parseSync(scene);  // embeds PNG-encoded RGBA
```

### 保存到文件

```js
import { writeFileSync } from 'node:fs';
writeFileSync('out.fbx', bytes);
```

### 在浏览器中保存

```js
const blob = new Blob([bytes], { type: 'application/octet-stream' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'out.fbx';
a.click();
URL.revokeObjectURL(url);
```

## 已知的限制

-   **`bakeSpaceTransform: true`** 只预乘轴矩阵 **顶点位置+常态**对象 `Lcl` 变相,集群矩阵,动画曲线,和光相/相机变相都不被烘焙. 国旗只适合单一的原生场景; 离开它 `false` - 现代进口商(团结、不真实、Blender、玛雅)荣誉 `GlobalSettings.UpAxis` 因此,在导入时会发生轴转换.
-   **`light.target.position`** 页:1 `DirectionalLight` 编号 : `SpotLight` 通过合成的回转 `LookAtProperty` 型号+OP连接.
-   **输出总是二进制 FBX** (单位:千美元)`Kaydara FBX Binary` 魔术). ASCII FBX没有执行.

## 如何运作(简要)

```
┌───────────────────┐   ┌──────────────┐   ┌──────────────┐
│ three.js Scene    │ → │ SceneCollect │ → │ FBXElem tree │ → encodeBinaryFBX → Uint8Array
└───────────────────┘   └──────────────┘   └──────────────┘
                              │                    │
                  builds UIDs, dedupes      one writer per FBX
                  geometries / mats /       record kind (Geometry,
                  textures, plans OO/OP     Material, Skin Deformer,
                  connection graph         AnimStack, …)
```

## 测试

```bash
npm test
```

446个单元测试覆盖了二进制地层,场景采集,每一种对象类型(Mesh / Material / Texture / Skin / Animation / Morph / Light /相机),轴/单元转换,公选表.

活性资产E2E测试(`test/e2e-*.test.mjs`没有参与 `npm test` - 他们读取了来自 `test/_assets/` 它被赋予了尊严。 将您自己的资产丢入该文件夹并单独运行 :

```bash
node --import tsx test/e2e-1-obj.test.mjs           # raw .obj round-trip
node --import tsx test/e2e-2-xbot.test.mjs          # Mixamo skinned + animated character
node --import tsx test/e2e-3-testTexture.test.mjs   # OBJ + MTL + PNG textures
node --import tsx test/e2e-4-threejs-models.test.mjs  # 7 three.js example glTFs
```

`test/m5-bindpose-recovery.test.mjs` 编号 `npm test` 但优雅地跳过当 `test/_assets/Xbot.glb` - 掉入任何被剥光的GLTF来启用它.

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40comfyorg/fbx-exporter-three/LICENSE)。 。 。 .

原载 [@comfyorg (英语)](https://www.npmjs.com/org/comfyorg)。 。 。 .

## 常见问题

### @comfyorg/fbx-exporter-three 是什么？

FBX出口国为3\.js场景——二进制的FBX编剧,配有全裸,动画,形态目标,灯光,相机和纹理嵌入\.

### 如何安装 @comfyorg/fbx-exporter-three？

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

### @comfyorg/fbx-exporter-three 支持 TypeScript 吗？

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

### @comfyorg/fbx-exporter-three 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @comfyorg/fbx-exporter-three 需要什么版本的 Node\.js？

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

### @comfyorg/fbx-exporter-three 可以商用吗？

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

### @comfyorg/fbx-exporter-three 的下载量有多少？

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

### @comfyorg/fbx-exporter-three 还在维护吗？

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