开发指南

本文档概述了参与 Turf.js 开发的 workflow、工具链和流程。涵盖了本地环境搭建、质量工具、测试基础设施、文档生成以及持续集成/部署流水线。

有关贡献代码和提交 pull requests 的详细信息，请参阅 Contributing。有关构建系统和编译过程的详细信息，请参阅 Build System。有关完整的发布 workflow 和版本管理流程，请参阅 Release Process。

开发 Workflow 概述

Turf.js 的开发 workflow 遵循标准的 fork-and-pull-request 模型，包含自动化质量检查和持续集成。workflow 从本地开发开始，经过自动化测试，最终发布。

100%

本地环境搭建

前置条件

需求	版本/详情
Node.js	Active 或 Maintenance LTS (18.x, 20.x, 或 22.x)
包管理器	pnpm (通过 corepack 或全局安装)
Git	最新稳定版本

安装步骤

本地搭建过程很简单：

1. 启用 pnpm (Node 16+)：

   corepack enable pnpm

   或者全局安装：npm install -g pnpm

2. 克隆并安装：

   git clone https://github.com/Turfjs/turf.git
   cd turf
   pnpm install

3. 验证设置：

   pnpm test

pnpm install 命令会安装所有依赖并运行 prepare 脚本，该脚本执行 husky && lerna run build 来设置 git hooks 并构建所有包。

质量工具架构

Turf.js 采用一套全面的自动化质量工具，以确保 100+ 个包之间的代码一致性、正确性和可维护性。

100%

质量工具详情

|工具 | 用途 | 配置 | 执行 | ||--------------|-------------------------------|---------------------------------------------------------|-----------------------------------------------| |ESLint | JavaScript/TypeScript linting | @eslint/js, typescript-eslint | pnpm lint:eslint 或 pre-commit | |Prettier | 代码格式化 | .prettierrc | prettier --write 在暂存文件上 | |TypeScript | 类型检查 | tsconfig.json 每个包 | 在构建和类型测试期间 | |Monorepolint | 包一致性 | .monorepolint.config.mjs | mrl check 在 CI 中 | |Husky | Git hooks | .husky/pre-commit | 在 git commit 时自动 | |lint-staged | 暂存文件处理 | package.json:18-29 | 通过 Husky hook |

lint-staged 配置在提交前自动处理文件：

• 在 package.json 文件上运行 mrl check --paths
• 在所有 *.js 和 *.ts 文件上运行 eslint --fix
• 为修改的 index.{js,ts} 文件重新生成文档
• 使用 prettier --write --ignore-unknown 格式化所有文件

测试基础设施

Turf.js 使用多层测试策略来验证所有包的功能、类型和性能。

测试类型和执行

100%

测试组织

每个包遵循标准测试结构：

• 单元测试：位于 test.ts 文件中，使用 tape 测试框架
• 类型测试：位于 types.ts 文件中，由具有严格设置的 TypeScript 编译器验证
• 性能测试：位于 bench.ts 文件中，使用 benchmark 库
• Fixture 测试：GeoJSON 输入文件在 test/in/ 目录中，预期输出在 test/out/ 中

包级别测试脚本使用 npm-run-all 并行执行所有 test:* 脚本，通常包括 test:tape 和可选的 test:types。

文档生成

Turf.js 文档从源代码中的 JSDoc 注释自动生成，确保 API 文档与实现保持同步。

100%

文档 Workflow

文档生成过程由 generate-readmes.ts 脚本管理：

执行上下文	命令	范围
单个包	pnpm run docs (在包目录中)	仅当前包
所有包	pnpm run docs (在根目录)	所有包
自动	git commit	仅修改的包

该脚本从 index.ts 或 index.js 文件中提取 JSDoc 注释并生成 markdown README 文件。这些 README 文件绝不应手动编辑 - 所有更改必须对源文件中的 JSDoc 注释进行。

lint-staged 配置确保当包的 index.{js,ts} 文件被修改并暂存时，README 会在提交前自动重新生成。

持续集成流水线

Turf.js 使用 GitHub Actions 来自动化测试、构建和发布，跨越多个 Node.js 版本和部署场景。

CI/CD Workflows

100%

Workflow 详情

构建 Workflow (turf.yml)

• 触发器：推送到 master 或 support/6.x 分支或 pull request
• 矩阵：在 Node.js 18.x、20.x 和 22.x 上测试
• 步骤：检出 → 设置 pnpm → 设置带缓存的 Node → 安装依赖 → 验证无更改 → 运行测试
• 用途：验证所有更改在支持的 Node 版本上正常工作

预发布 Workflow (prerelease.yml)

• 触发器：推送到 master 分支（默认禁用）
• 环境：Node 18.x，最新 Ubuntu
• 命令：lerna publish minor --canary --include-merged-tags --force-publish --dist-tag prerelease --ignore-scripts true --yes
• 输出：以格式 7.x.x-alpha.N 发布 alpha 版本到 npm，其中 N 是自上次发布以来的提交数
• 用途：支持在真实环境中测试未发布的更改

发布 Workflow (release.yml)

• 触发器：推送匹配 v*.*.* 模式的版本标签
• 环境：Node 18.x，最新 Ubuntu
• 命令：lerna publish from-package --ignore-scripts true --yes
• 产物：发布到 npm registry 并使用自动生成的说明创建草稿 GitHub release
• 用途：从版本标签自动化官方发布

包管理器和 Monorepo 管理

Turf.js 使用 pnpm 作为其包管理器，使用 lerna 进行 monorepo 编排，并通过 monorepolint 进行严格强制执行。

工具配置

工具	版本/配置	用途
pnpm	10.10.0 (通过 packageManager 字段)	工作区依赖管理
lerna	^8.2.2	包版本管理和发布
monorepolint	0.5.0	Package.json 一致性强制执行

preinstall 脚本强制执行 pnpm 使用：

"preinstall": "npx only-allow pnpm"

prepare 脚本确保包在安装后构建：

"prepare": "husky && lerna run build"

Monorepolint 规则

.monorepolint.config.mjs 配置在所有包中强制执行一致性：

• 包字段顺序：package.json 文件中字段的标准化排序
• 字母顺序排序：依赖项和脚本按字母顺序排序
• 必需条目：确保所有包具有正确的 type、main、module、types、exports 字段
• 脚本模板：强制执行标准脚本如 build、test、docs、bench
• 依赖要求：强制 TypeScript 包的特定 dev 依赖（tape、tsup、tsx）

配置通过扫描 packages/turf-* 目录动态发现包，并根据文件存在情况（.ts 与 .js 文件、测试文件、基准测试文件）对其进行分类。