glTF-Transform项目开发环境搭建与贡献指南

glTF-Transform项目开发环境搭建与贡献指南

glTF-Transform glTF 2.0 SDK for JavaScript and TypeScript, on Web and Node.js. 项目地址: https://gitcode.com/gh_mirrors/gl/glTF-Transform

glTF-Transform是一个用于处理glTF 3D模型格式的TypeScript工具库，它提供了丰富的功能来创建、修改和优化glTF资产。本文将详细介绍如何搭建开发环境、运行测试以及为项目贡献代码的最佳实践。

开发环境配置

前置条件

项目采用现代化的JavaScript工具链，需要以下基础环境：

1. Node.js环境（建议使用LTS版本）
2. Yarn包管理器（v2+版本）
3. TypeScript支持

初始化项目

首次设置开发环境时，需要启用Corepack（Yarn v2+的包管理器工具）：

corepack enable

然后安装项目依赖：

yarn install

项目采用Lerna进行多包管理，所有代码（除Node.js测试外）均使用TypeScript编写。建议使用VSCode作为开发工具，它能提供优秀的TypeScript支持和实时linting功能。

项目结构与构建

多包管理

glTF-Transform采用monorepo结构，包含多个相互关联的NPM包。这种结构通过Yarn workspaces和Lerna实现：

• 公共依赖安装在根目录
• 各包特有依赖安装在相应子目录
• 构建和测试命令可以针对整个项目或特定子包执行

常用命令

构建整个项目：

yarn build

构建特定子包（忽略其他包）：

yarn run build --ignore "@gltf-transform/view"

执行测试：

yarn test

开发时建议使用watch模式自动重建代码：

yarn run build:watch

开发工作流

本地测试CLI

要在本地测试命令行工具：

1. 进入packages/cli目录
2. 执行npm link（注意不是yarn link）
3. 全局gltf-transform -h命令将使用本地代码

跨包命令执行

要在所有包中执行任意命令：

yarn lerna exec -- <command>

测试策略

项目使用Ava测试框架，提供多种测试模式：

运行所有测试：

yarn test

运行单个测试文件：

yarn test packages/functions/test/palette.test.ts

使用watch模式自动重跑测试：

yarn test --watch

调试测试

要使用Chrome DevTools调试测试：

1. 在测试代码中添加debugger语句
2. 运行：

yarn test:debug packages/functions/test/palette.test.ts --break

代码贡献规范

功能建议流程

在实现新功能前，建议先提出issue讨论。某些功能可能不符合项目当前范围或维护能力。即使功能未被采纳，也可以通过外部扩展实现。

跨平台兼容性

新功能应兼容Node.js和Web环境。平台特定资源（如HTMLCanvasElement）应由用户传入，而非API内部创建。

依赖管理

• 运行时依赖：仅安装在需要的子包中
• 开发依赖：安装在项目根目录
• 提交PR时应排除dist/*和yarn.lock变更

文档规范

项目文档采用JSDoc注释生成，使用greendoc工具处理。重要标签说明：

• @internal：隐藏文档和TS定义，仅限包内使用
• @hidden：隐藏文档但保留TS定义，限monorepo内使用
• @experimental：标记不稳定API

功能扩展方向

glTF扩展支持

• 核心支持：完整的glTF 2.0核心格式
• 官方扩展(KHR_)：逐步实现，欢迎贡献
• 多厂商扩展(EXT_)：视情况采纳
• 单厂商扩展：通常不直接包含，但提供外部实现API

功能模块建议

欢迎贡献新的功能模块(Functions)实现。

发布流程

项目维护者执行发布操作：

标准发布：

yarn lerna publish [ patch | minor | major ] --force-publish "*"

Alpha发布：

yarn lerna publish prerelease --dist-tag next --force-publish "*"

新包首次发布需添加-- --access public参数。

通过本文介绍，开发者可以全面了解glTF-Transform项目的开发环境搭建、测试策略和贡献规范，为参与项目开发做好准备。项目鼓励符合其设计理念的贡献，特别是对glTF官方扩展的支持和新功能模块的实现。

glTF-Transform glTF 2.0 SDK for JavaScript and TypeScript, on Web and Node.js. 项目地址: https://gitcode.com/gh_mirrors/gl/glTF-Transform