构建系统与模块导出

本文档描述将 Three.js 源代码转换为各种分发格式的构建流水线，并解释库如何为不同消费模式配置模块导出。构建系统使用 Rollup 将源文件打包为 ESM 和 CommonJS 格式，支持多种渲染后端（WebGL、WebGPU）和各种优化级别。

有关核心库架构的信息，请参阅Three.js 概述。有关渲染器特定实现，请参阅渲染架构。

构建流水线概览

Three.js 构建系统将位于 src/ 中的源文件转换为 build/ 目录中的多种分发格式。该流水线处理着色器代码预处理、许可证头注入和压缩。

100%

Rollup 配置

构建配置定义在 utils/build/rollup.config.js1-202，并导出多个构建目标。该配置使用可根据命令行参数过滤的函数式方法。

构建目标

配置定义了 7 个不同的构建目标，组织成组：

构建目标	输入	输出	格式	压缩
Core + WebGPU 节点	src/Three.Core.js, src/Three.WebGPU.Nodes.js	build/three.core.js, build/three.webgpu.nodes.js	ESM	否
Core + WebGL + WebGPU	src/Three.Core.js, src/Three.js, src/Three.WebGPU.js	build/three.core.js, build/three.module.js, build/three.webgpu.js	ESM	否
TSL	src/Three.TSL.js	build/three.tsl.js	ESM	否
Core + WebGPU 节点（压缩）	src/Three.Core.js, src/Three.WebGPU.Nodes.js	build/three.core.min.js, build/three.webgpu.nodes.min.js	ESM	是
Core + WebGL + WebGPU（压缩）	src/Three.Core.js, src/Three.js, src/Three.WebGPU.js	build/three.core.min.js, build/three.module.min.js, build/three.webgpu.min.js	ESM	是
TSL（压缩）	src/Three.TSL.js	build/three.tsl.min.js	ESM	是
CommonJS	src/Three.js	build/three.cjs	CJS	否

构建系统使用 configOnlyModule 标志可选择地将构建限制为前三个目标 utils/build/rollup.config.js201

构建插件

三个自定义插件在构建期间处理源代码：

1. GLSL 插件

glsl() 插件处理嵌入在具有 .glsl.js 扩展名的 JavaScript 文件中的 GLSL 着色器代码 utils/build/rollup.config.js4-36

处理步骤：

1. 匹配模式为 /\.glsl\.js$/ 的文件
2. 从标记为 /* glsl */ 的模板字面量中提取 GLSL 代码
3. 剥离注释：// 单行注释和 /* */ 多行注释
4. 通过折叠多个连续换行符规范化换行符
5. 将处理后的字符串转换为 JSON 格式

示例转换：

// 转换前
const shader = /* glsl */`
    // 这是注释
    void main() {
        /* 块注释 */
        gl_FragColor = vec4(1.0);
    }
`;

// 转换后（压缩的 JSON 字符串）
"void main() {n    gl_FragColor = vec4(1.0);n}"

2. 头部插件

header() 插件在所有输出块前添加许可证头 utils/build/rollup.config.js38-61：

/**
 * @license
 * Copyright 2010-2026 Three.js Authors
 * SPDX-License-Identifier: MIT
 */

3. Terser 插件

@rollup/plugin-terser 插件为生产构建压缩代码 utils/build/rollup.config.js1 utils/build/rollup.config.js132

源入口点

构建系统处理定义库模块结构的四个主要入口点：

100%

入口点描述：

• src/Three.Core.js：包含基础类（Vector3、Matrix4、Object3D、BufferGeometry、Material），无渲染器实现
• src/Three.js：使用 WebGLRenderer 和相关子系统扩展核心
• src/Three.WebGPU.js：使用现代 GPU API 的 WebGPURenderer 扩展核心
• src/Three.WebGPU.Nodes.js：包含用于 WebGPU 的基于节点的材质系统
• src/Three.TSL.js：提供 TSL (Three.js Shading Language) 辅助函数，将 three/webgpu 作为外部依赖

分发格式

Three.js 以支持不同消费模式的多种格式分发：

ESM (ES 模块)

现代 JavaScript 环境的主要分发格式。所有 ESM 文件都以 format: 'esm' 构建，并使用 .js 扩展名。

核心变体：

文件	描述	重新导出核心
build/three.core.js	仅核心库（无渲染器）	N/A
build/three.module.js	核心 + WebGLRenderer	是（从 ./three.core.js 导入）
build/three.webgpu.js	核心 + WebGPURenderer	是（从 ./three.core.js 导入）
build/three.webgpu.nodes.js	核心 + WebGPU + 节点系统	是（从 ./three.core.js 导入）
build/three.tsl.js	TSL 辅助函数	外部依赖：three/webgpu

ESM 构建使用共享核心以避免重复。例如，build/three.module.js6 从 ./three.core.js 导入并重新导出：

import { Matrix3, Vector2, Color, /* ... */ } from './three.core.js';
export { /* ... 所有核心导出 ... */ } from './three.core.js';

CommonJS

用于 Node.js 兼容性的单一 CommonJS 包：

• build/three.cjs：包含 WebGLRenderer 的完整库的 CommonJS 格式

CJS 构建配置为 format: 'cjs' 和 name: 'THREE' utils/build/rollup.config.js190-196

来源：utils/build/rollup.config.js184-198 build/three.cjs1-6

压缩变体

为所有 ESM 输出生成带有 .min.js 后缀的压缩版本。这些使用相同的输入源但包含 terser 插件：

• build/three.core.min.js
• build/three.module.min.js
• build/three.webgpu.min.js
• build/three.webgpu.nodes.min.js
• build/three.tsl.min.js

包导出配置

package.json 定义如何通过 Node.js 模块解析来消费库。该配置使用条件导出，根据导入样式提供不同的入口点。

100%

导出映射结构

package.json8-20 中的 exports 字段定义以下映射：

导出路径	条件	解析文件
"."	import	./build/three.module.js
"."	require	./build/three.cjs
"./examples/fonts/*"	-	./examples/fonts/*
"./examples/jsm/*"	-	./examples/jsm/*
"./addons"	-	./examples/jsm/Addons.js
"./addons/*"	-	./examples/jsm/*
"./src/*"	-	./src/*
"./webgpu"	-	./build/three.webgpu.js
"./tsl"	-	./build/three.tsl.js

传统入口点

为向后兼容，还定义了顶级字段：

• "main": "./build/three.cjs" - 默认 Node.js 入口（CommonJS）package.json6
• "module": "./build/three.module.js" - ESM 感知打包器入口 package.json7
• "type": "module" - 指示包在内部使用 ESM package.json5

构建命令

构建过程通过 package.json45-52 中定义的 npm 脚本调用：

命令	脚本	描述
npm run build	rollup -c utils/build/rollup.config.js	构建所有目标
npm run build-module	rollup -c utils/build/rollup.config.js --configOnlyModule	仅构建非压缩 ESM 目标

--configOnlyModule 标志过滤构建配置以仅产生前三个构建目标（未压缩 ESM 输出）utils/build/rollup.config.js201

模块结构

源文件、构建输出和包导出之间的关系创建了分层模块系统：

100%

此架构实现：

1. 代码共享：多个构建输出从 three.core.js 导入以避免重复
2. 选择性导入：消费者可以仅导入 WebGL 或 WebGPU 渲染器
3. 摇树优化：ESM 格式允许打包器消除未使用的代码
4. 向后兼容：CommonJS 和传统模块字段支持较旧的工具