Crawlee 仓库开发协作指南从 CLAUDE.md 读懂提交规范、构建测试与 Monorepo 架构【免费下载链接】crawleeCrawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.项目地址: https://gitcode.com/GitHub_Trending/cr/crawleeCrawlee 是一个面向 Node.js 的 Web 爬取与浏览器自动化库仓库本身采用 Yarn/Pnpm Workspaces Turbo 的 Monorepo 组织方式包含basic-crawler、core、playwright-crawler、cheerio-crawler等二十余个包。本文以仓库根目录的 .claude/CLAUDE.md 为骨架系统讲解在 Crawlee 仓库中贡献代码时必须遵守的提交规范、构建测试命令、代码编辑红线与包依赖架构并结合 package.json、pnpm-workspace.yaml、turbo.json、vitest.config.mts 等仓库真实配置帮助你快速上手成为合格的贡献者。文档定位这份 CLAUDE.md 是给谁看的.claude/CLAUDE.md 是仓库维护者为Claude Codeclaude.ai/code准备的指导文件用于约束 AI 编码助手在本仓库中工作时的行为方式。它覆盖了从提交信息格式、测试纪律到架构认知的完整开发流程本质上是一份「机器可读的贡献手册」对人工开发者同样适用。全文主要回答六个问题改动边界在哪里、提交信息怎么写、提交前必须做什么、测试应该怎么写、PR 描述怎么组织以及仓库的包结构如何理解。工作总原则改动最小化、边界清晰CLAUDE.md 的第一条规则是所有协作的基调Keep changes minimal and scoped. Do not fix unrelated issues, touch unrelated files, or clean up code outside the scope of the current task unless explicitly asked.即改动保持最小且限定范围。不顺手修复无关问题、不触碰无关文件、不清理任务范围之外的代码除非被明确要求。这条原则与仓库根 package.json 中 lint-staged 的配置仅对{packages,test,docs}/**/*.{js,ts,mjs,mts,cjs,cts}做oxlint --fix与oxfmt --write相互印证——仓库对「哪些文件该被自动格式化」也做了严格的范围限定。Git 提交约定chore / fix / feat 三前缀CLAUDE.md 规定提交信息必须严格区分三类chore:用于非功能性提交配置变更、CI 修复、CHANGELOG 修改fix:仅用于源码中的真实 bug 修复feat:仅用于新功能。仓库在 lerna.json 中开启了conventionalCommits: true意味着 release notes 会从这些规范化的提交信息中自动生成对应message: chore(release): %s的版本提交模板因此提交前缀的规范性直接影响发布流程的可读性。同时根 package.json 的 devDependencies 中引入了commitlint/config-conventional与这套约定保持一致。此外还有一个环境相关的实用提示当 husky/lint-staged 钩子因 PATH 问题失败时推送请使用--no-verify标志跳过钩子而不是花时间调试本机 PATH。提交前的类型检查与代码编辑红线先跑类型检查再提交CLAUDE.md 明确要求提交任何 TypeScript 改动前必须运行yarn tsc-check-tests或项目的类型检查命令永远不要假设类型安全而是要实际验证。在 package.json 中对应脚本为tsc-check-tests: tsc --noEmit --project test/tsconfig.json它使用 test/tsconfig.json 对测试文件做无输出的全量类型检查。仓库 CI 与发布流程pnpm build后接scripts/typescript_fixes.mjs修复同样依赖 TypeScript 严格编译可见类型安全是该仓库的硬性门槛。不删代码原则When reviewing or editing code, do NOT remove code (assertions, type casts, etc.) unless you have verified its safe by running the build/type checker. Never claim code is redundant without evidence.审查或编辑代码时除非已经通过构建/类型检查器验证其安全性否则不得删除断言、类型断言等代码不得在没有证据的情况下声称代码是「冗余的」。这条红线在 oxlint.config.ts 中有侧面体现例如typescript/no-unnecessary-type-assertion、typescript/no-unsafe-type-assertion等「建议删除冗余」类规则被显式关闭off说明仓库宁可保留防御性代码也不鼓励轻率删减。测试纪律先写复现测试再动手修复CLAUDE.md 对测试提出两条硬性要求修复 bug 时先写能复现问题的测试再实现修复在没有失败测试之前不要实施修复Test-Driven Bug Fix。测试文件中不得遗留调试产物console.log、调试模式开关、注释掉的代码提交前必须清理干净。这与 CONTRIBUTING.md 中「Be sure to include appropriate test cases」的指导一脉相承测试既用于证明 PR 修复了什么也防止未来回归。仓库的测试规模庞大根目录 test/ 下按core、e2e、integration、otel、utils、shared等分门别类组织其中 test/e2e/ 还针对真实爬取场景如 cheerio-default、playwright-default做端到端验证。PR 描述规范CLAUDE.md 要求 PR 描述精炼、聚焦「改了什么、为什么改」并给出两个明确禁忌避免套用样板模板或冗长描述完全跳过 Test plan 章节不要陈述显而易见的事实例如测试通过这类 CI 已经可见的信息。这与 commit 前缀规范共同构成「机器可读 人可读」的双重可追溯性。构建与测试命令全景CLAUDE.md 给出了完整命令清单与根 package.json 的 scripts 一一对应# Setup文档记载为 Yarn v4 via Corepack corepack enable yarn install # Build构建所有包Turbo TypeScript yarn build # Test运行全部测试vitest yarn test # 包含困难测试CRAWLEE_DIFFICULT_TESTS1 yarn test:full # 运行单个测试文件 yarn vitest run path/to/test.ts # Code Quality yarn lint # ESLint实际为 oxlint yarn lint:fix yarn format # Biome实际为 oxfmt yarn tsc-check-tests # 类型检查测试文件与仓库实际脚本的对应关系对照根 package.json 可以发现细节差异这正是理解仓库现状的关键CLAUDE.md 记载仓库实际脚本说明yarn buildturbo run build --filter./packages/* node ./scripts/typescript_fixes.mjs经 Turbo 按依赖拓扑构建全部包yarn testvitest run --silent静默模式运行全部单测yarn test:fullcross-env CRAWLEE_DIFFICULT_TESTS1 vitest run --silent通过环境变量纳入困难测试yarn lintoxlint packages test docs --tsconfigtsconfig.json --type-aware仓库已从 ESLint 迁移到 oxlint类型感知模式yarn formatoxfmt packages test docs --write格式化工具为 oxfmttsc-check-teststsc --noEmit --project test/tsconfig.json严格类型检查测试代码另有文档未展开但仓库存在的脚本test:e2enode test/e2e/run.mjs端到端测试、test:integration困难测试的集成套件需要 Docker 启动 browserless 与 httpbin 服务、coveragev8 覆盖率报告等。关于包管理器的版本说明需要特别指出一个文档与仓库现状的差异CLAUDE.md 记载使用Yarn v4Corepack而当前仓库根 package.json 的packageManager字段声明的是pnpm11.22.0且存在 pnpm-workspace.yamlworkspaces 含packages/*、docs、websitelerna.json 的npmClient也为pnpm根脚本大量使用pnpm build、pnpm publish:*。据此可以推断仓库已迁移到 pnpm实际开发时应以 pnpm 为准pnpm install、pnpm build、pnpm testCLAUDE.md 中yarn开头的命令属于历史遗留写法执行时注意替换即可。pnpm-workspace.yaml 还包含几个值得注意的工程细节minimumReleaseAge: 1440依赖发布满 24 小时才允许引入防止被撤回的坏版本污染、对minimatch/lernajs-yaml等的版本覆盖dedupe 修复 lerna 9.x 的 CJS 导出兼容问题、以及 pnpm 11 的allowBuilds白名单playwright/browser-chromium、puppeteer、esbuild等需要构建的依赖显式放行。Monorepo 架构包依赖层次与 Turbo 编排CLAUDE.md 用一张依赖图精确刻画了仓库的包层次这是理解 Crawlee 设计的关键crawlee/types # 共享 TypeScript 接口 crawlee/utils # 共享工具函数 crawlee/memory-storage # 内存存储测试默认 ↓ crawlee/core # Request、RequestQueue、RequestList、Dataset ↓ crawlee/basic # BasicCrawler所有爬虫的基础 ↓ crawlee/http # HttpCrawler ↓ ┌──────┴──────┬─────────────┐ ↓ ↓ ↓ crawlee/cheerio crawlee/jsdom crawlee/linkedom (HTML parsing variants) crawlee/browser-pool # 浏览器实例管理 ↓ crawlee/browser # BrowserCrawler 基类 ↓ ┌──────┴──────┐ ↓ ↓ crawlee/playwright crawlee/puppeteer crawlee # 元包再导出大多数 crawlee/* 包各层职责与源码印证基础层crawlee/types与crawlee/utils不依赖其他 Crawlee 包是依赖图的叶子节点见 packages/types/src/index.ts 与 packages/utils/src/index.ts。核心层crawlee/core承载 Request、RequestQueue、RequestList、Dataset 等存储与调度核心packages/core/src/index.ts。爬虫层crawlee/basic提供BasicCrawler是所有爬虫的基座其 package.json 依赖crawlee/core、crawlee/http-client、crawlee/types、crawlee/utils见 packages/basic-crawler/package.json印证了依赖图的方向。解析变体cheerio、jsdom、linkedom三个包共享 HTTP 层仅替换 HTML 解析引擎。浏览器层crawlee/browser-pool负责浏览器实例的生命周期管理crawlee/browser提供BrowserCrawler基类其上再分化出playwright与puppeteer两套实现以及仓库新增的stagehand-crawler。元包crawlee汇总再导出大部分crawlee/*包用户只需import { PlaywrightCrawler } from crawlee即可见 packages/crawlee/src/index.ts。Turbo 任务编排仓库使用 Turbo 协调包间构建turbo.json 中定义了三个任务{ tasks: { build: { dependsOn: [^build], outputs: [dist/**] }, copy: { dependsOn: [^copy], outputs: [dist/**] }, clean: { cache: false, outputs: [] } } }dependsOn: [^build]表示每个包构建前先构建其依赖包Turbo 据此自动拓扑排序并缓存产物输出目录统一为dist/**这正是 Monorepo 下「一次pnpm build全仓就绪」的机制所在。测试位置约定CLAUDE.md 特别强调测试放在仓库根目录的/test/下而不是各包内部E2E 测试位于/test/e2e/。这与常见 Monorepo 做法不同——浏览 test/ 目录可以看到core、e2e、integration、otel、utils等统一测试目录各包内仅保留少量专属测试与tsconfig.json例如 packages/basic-crawler/test/batch-add-requests.test.ts。根 tsconfig.json 与 test/tsconfig.json 为全仓测试提供统一的类型检查入口。Vitest 测试约定与 Jest 的差异CLAUDE.md 用较大篇幅总结 Vitest 相对 Jest 的差异这些是写测试时必须遵守的硬性规范Mock 按测试文件隔离不再需要在afterAll中 unmockvitest 每个测试文件自动隔离。使用vitest.mock()与vitest.mocked()替代jest.mock/jest.MockedFunction做类型断言。模块 Mock 必须匹配导入方式如果源码用默认导入import os from node:osmock 对象需额外提供default属性若用命名导入import { platform } from node:os则直接 mock 对应字段CONTRIBUTING.md 给出了两种场景的完整示例。Spy 复用同一实例多个vitest.spyOn创建的 spy 是独立实例各自记录调用次数多次操作应复用同一个 spy 并链式mockReturnValueOnce。运行时配置用vitest.setConfig()例如在 Windows 下调整超时调用vitest.setConfig({ testTimeout: 100_000 })。避免从外部包导入const enumtsc 编译时会内联其值而 vitest 不会除非该枚举在运行时真实存在否则会报错。仓库配置层面的印证vitest.config.mts 提供了这些约定的底层支持test.globals: true与setupFiles: [./test/vitest.setup.ts]使describe/it/expect等全局可用restoreMocks: true这正是「无需手动重置 spy」的机制来源testTimeout与hookTimeout均为 60 秒CI 环境下自动限制线程isCI检测到 CI 时threads { minThreads: 1, maxThreads: 1 }串行跑测试避免资源竞争大量 alias 将crawlee、crawlee/*直接映射到packages/*/src源码测试针对工作区源码而非构建产物运行支持vitest.config.local.mts本地覆盖便于开发者自定义。macOS 代理测试环境准备仓库的代理相关测试使用不同的 loopback 地址来验证流量走向。与 Windows/Linux 不同macOS 默认只有一个回环地址127.0.0.1因此每次系统启动后需手动添加别名sudo ifconfig lo0 alias 127.0.0.2 up sudo ifconfig lo0 alias 127.0.0.3 up sudo ifconfig lo0 alias 127.0.0.4 up这些地址服务于 test/ 下的代理相关测试例如 proxy 配置、会话轮换场景。CONTRIBUTING.md 亦收录了同样命令可见这是 macOS 开发者的标准前置步骤Linux 环境则天然支持多个回环地址无需此操作。总结一份可执行的上手清单综合 .claude/CLAUDE.md 与仓库现状贡献者在 Crawlee 仓库的标准化工作流为corepack enable后用 pnpm 安装依赖pnpm install注意当前仓库以 pnpm 为准改动保持最小范围不触碰无关文件修复 bug 前先写复现测试vitest测试放根 test/ 目录提交前运行pnpm tsc-check-tests验证类型pnpm lint与pnpm format保持代码整洁提交信息按chore:/fix:/feat:三前缀规范书写推送遇 husky 钩子因 PATH 失败时使用--no-verifyPR 描述精炼说明改动与动机不写 Test plan 等废话。这份 CLAUDE.md 既是 AI 助手的编码约束也是一份浓缩的仓库工程手册——理解了它就理解了 Crawlee 的协作秩序与 Monorepo 设计哲学。【免费下载链接】crawleeCrawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.项目地址: https://gitcode.com/GitHub_Trending/cr/crawlee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Crawlee 仓库开发协作指南：从 CLAUDE.md 读懂提交规范、构建测试与 Monorepo 架构
Crawlee 仓库开发协作指南从 CLAUDE.md 读懂提交规范、构建测试与 Monorepo 架构【免费下载链接】crawleeCrawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.项目地址: https://gitcode.com/GitHub_Trending/cr/crawleeCrawlee 是一个面向 Node.js 的 Web 爬取与浏览器自动化库仓库本身采用 Yarn/Pnpm Workspaces Turbo 的 Monorepo 组织方式包含basic-crawler、core、playwright-crawler、cheerio-crawler等二十余个包。本文以仓库根目录的 .claude/CLAUDE.md 为骨架系统讲解在 Crawlee 仓库中贡献代码时必须遵守的提交规范、构建测试命令、代码编辑红线与包依赖架构并结合 package.json、pnpm-workspace.yaml、turbo.json、vitest.config.mts 等仓库真实配置帮助你快速上手成为合格的贡献者。文档定位这份 CLAUDE.md 是给谁看的.claude/CLAUDE.md 是仓库维护者为Claude Codeclaude.ai/code准备的指导文件用于约束 AI 编码助手在本仓库中工作时的行为方式。它覆盖了从提交信息格式、测试纪律到架构认知的完整开发流程本质上是一份「机器可读的贡献手册」对人工开发者同样适用。全文主要回答六个问题改动边界在哪里、提交信息怎么写、提交前必须做什么、测试应该怎么写、PR 描述怎么组织以及仓库的包结构如何理解。工作总原则改动最小化、边界清晰CLAUDE.md 的第一条规则是所有协作的基调Keep changes minimal and scoped. Do not fix unrelated issues, touch unrelated files, or clean up code outside the scope of the current task unless explicitly asked.即改动保持最小且限定范围。不顺手修复无关问题、不触碰无关文件、不清理任务范围之外的代码除非被明确要求。这条原则与仓库根 package.json 中 lint-staged 的配置仅对{packages,test,docs}/**/*.{js,ts,mjs,mts,cjs,cts}做oxlint --fix与oxfmt --write相互印证——仓库对「哪些文件该被自动格式化」也做了严格的范围限定。Git 提交约定chore / fix / feat 三前缀CLAUDE.md 规定提交信息必须严格区分三类chore:用于非功能性提交配置变更、CI 修复、CHANGELOG 修改fix:仅用于源码中的真实 bug 修复feat:仅用于新功能。仓库在 lerna.json 中开启了conventionalCommits: true意味着 release notes 会从这些规范化的提交信息中自动生成对应message: chore(release): %s的版本提交模板因此提交前缀的规范性直接影响发布流程的可读性。同时根 package.json 的 devDependencies 中引入了commitlint/config-conventional与这套约定保持一致。此外还有一个环境相关的实用提示当 husky/lint-staged 钩子因 PATH 问题失败时推送请使用--no-verify标志跳过钩子而不是花时间调试本机 PATH。提交前的类型检查与代码编辑红线先跑类型检查再提交CLAUDE.md 明确要求提交任何 TypeScript 改动前必须运行yarn tsc-check-tests或项目的类型检查命令永远不要假设类型安全而是要实际验证。在 package.json 中对应脚本为tsc-check-tests: tsc --noEmit --project test/tsconfig.json它使用 test/tsconfig.json 对测试文件做无输出的全量类型检查。仓库 CI 与发布流程pnpm build后接scripts/typescript_fixes.mjs修复同样依赖 TypeScript 严格编译可见类型安全是该仓库的硬性门槛。不删代码原则When reviewing or editing code, do NOT remove code (assertions, type casts, etc.) unless you have verified its safe by running the build/type checker. Never claim code is redundant without evidence.审查或编辑代码时除非已经通过构建/类型检查器验证其安全性否则不得删除断言、类型断言等代码不得在没有证据的情况下声称代码是「冗余的」。这条红线在 oxlint.config.ts 中有侧面体现例如typescript/no-unnecessary-type-assertion、typescript/no-unsafe-type-assertion等「建议删除冗余」类规则被显式关闭off说明仓库宁可保留防御性代码也不鼓励轻率删减。测试纪律先写复现测试再动手修复CLAUDE.md 对测试提出两条硬性要求修复 bug 时先写能复现问题的测试再实现修复在没有失败测试之前不要实施修复Test-Driven Bug Fix。测试文件中不得遗留调试产物console.log、调试模式开关、注释掉的代码提交前必须清理干净。这与 CONTRIBUTING.md 中「Be sure to include appropriate test cases」的指导一脉相承测试既用于证明 PR 修复了什么也防止未来回归。仓库的测试规模庞大根目录 test/ 下按core、e2e、integration、otel、utils、shared等分门别类组织其中 test/e2e/ 还针对真实爬取场景如 cheerio-default、playwright-default做端到端验证。PR 描述规范CLAUDE.md 要求 PR 描述精炼、聚焦「改了什么、为什么改」并给出两个明确禁忌避免套用样板模板或冗长描述完全跳过 Test plan 章节不要陈述显而易见的事实例如测试通过这类 CI 已经可见的信息。这与 commit 前缀规范共同构成「机器可读 人可读」的双重可追溯性。构建与测试命令全景CLAUDE.md 给出了完整命令清单与根 package.json 的 scripts 一一对应# Setup文档记载为 Yarn v4 via Corepack corepack enable yarn install # Build构建所有包Turbo TypeScript yarn build # Test运行全部测试vitest yarn test # 包含困难测试CRAWLEE_DIFFICULT_TESTS1 yarn test:full # 运行单个测试文件 yarn vitest run path/to/test.ts # Code Quality yarn lint # ESLint实际为 oxlint yarn lint:fix yarn format # Biome实际为 oxfmt yarn tsc-check-tests # 类型检查测试文件与仓库实际脚本的对应关系对照根 package.json 可以发现细节差异这正是理解仓库现状的关键CLAUDE.md 记载仓库实际脚本说明yarn buildturbo run build --filter./packages/* node ./scripts/typescript_fixes.mjs经 Turbo 按依赖拓扑构建全部包yarn testvitest run --silent静默模式运行全部单测yarn test:fullcross-env CRAWLEE_DIFFICULT_TESTS1 vitest run --silent通过环境变量纳入困难测试yarn lintoxlint packages test docs --tsconfigtsconfig.json --type-aware仓库已从 ESLint 迁移到 oxlint类型感知模式yarn formatoxfmt packages test docs --write格式化工具为 oxfmttsc-check-teststsc --noEmit --project test/tsconfig.json严格类型检查测试代码另有文档未展开但仓库存在的脚本test:e2enode test/e2e/run.mjs端到端测试、test:integration困难测试的集成套件需要 Docker 启动 browserless 与 httpbin 服务、coveragev8 覆盖率报告等。关于包管理器的版本说明需要特别指出一个文档与仓库现状的差异CLAUDE.md 记载使用Yarn v4Corepack而当前仓库根 package.json 的packageManager字段声明的是pnpm11.22.0且存在 pnpm-workspace.yamlworkspaces 含packages/*、docs、websitelerna.json 的npmClient也为pnpm根脚本大量使用pnpm build、pnpm publish:*。据此可以推断仓库已迁移到 pnpm实际开发时应以 pnpm 为准pnpm install、pnpm build、pnpm testCLAUDE.md 中yarn开头的命令属于历史遗留写法执行时注意替换即可。pnpm-workspace.yaml 还包含几个值得注意的工程细节minimumReleaseAge: 1440依赖发布满 24 小时才允许引入防止被撤回的坏版本污染、对minimatch/lernajs-yaml等的版本覆盖dedupe 修复 lerna 9.x 的 CJS 导出兼容问题、以及 pnpm 11 的allowBuilds白名单playwright/browser-chromium、puppeteer、esbuild等需要构建的依赖显式放行。Monorepo 架构包依赖层次与 Turbo 编排CLAUDE.md 用一张依赖图精确刻画了仓库的包层次这是理解 Crawlee 设计的关键crawlee/types # 共享 TypeScript 接口 crawlee/utils # 共享工具函数 crawlee/memory-storage # 内存存储测试默认 ↓ crawlee/core # Request、RequestQueue、RequestList、Dataset ↓ crawlee/basic # BasicCrawler所有爬虫的基础 ↓ crawlee/http # HttpCrawler ↓ ┌──────┴──────┬─────────────┐ ↓ ↓ ↓ crawlee/cheerio crawlee/jsdom crawlee/linkedom (HTML parsing variants) crawlee/browser-pool # 浏览器实例管理 ↓ crawlee/browser # BrowserCrawler 基类 ↓ ┌──────┴──────┐ ↓ ↓ crawlee/playwright crawlee/puppeteer crawlee # 元包再导出大多数 crawlee/* 包各层职责与源码印证基础层crawlee/types与crawlee/utils不依赖其他 Crawlee 包是依赖图的叶子节点见 packages/types/src/index.ts 与 packages/utils/src/index.ts。核心层crawlee/core承载 Request、RequestQueue、RequestList、Dataset 等存储与调度核心packages/core/src/index.ts。爬虫层crawlee/basic提供BasicCrawler是所有爬虫的基座其 package.json 依赖crawlee/core、crawlee/http-client、crawlee/types、crawlee/utils见 packages/basic-crawler/package.json印证了依赖图的方向。解析变体cheerio、jsdom、linkedom三个包共享 HTTP 层仅替换 HTML 解析引擎。浏览器层crawlee/browser-pool负责浏览器实例的生命周期管理crawlee/browser提供BrowserCrawler基类其上再分化出playwright与puppeteer两套实现以及仓库新增的stagehand-crawler。元包crawlee汇总再导出大部分crawlee/*包用户只需import { PlaywrightCrawler } from crawlee即可见 packages/crawlee/src/index.ts。Turbo 任务编排仓库使用 Turbo 协调包间构建turbo.json 中定义了三个任务{ tasks: { build: { dependsOn: [^build], outputs: [dist/**] }, copy: { dependsOn: [^copy], outputs: [dist/**] }, clean: { cache: false, outputs: [] } } }dependsOn: [^build]表示每个包构建前先构建其依赖包Turbo 据此自动拓扑排序并缓存产物输出目录统一为dist/**这正是 Monorepo 下「一次pnpm build全仓就绪」的机制所在。测试位置约定CLAUDE.md 特别强调测试放在仓库根目录的/test/下而不是各包内部E2E 测试位于/test/e2e/。这与常见 Monorepo 做法不同——浏览 test/ 目录可以看到core、e2e、integration、otel、utils等统一测试目录各包内仅保留少量专属测试与tsconfig.json例如 packages/basic-crawler/test/batch-add-requests.test.ts。根 tsconfig.json 与 test/tsconfig.json 为全仓测试提供统一的类型检查入口。Vitest 测试约定与 Jest 的差异CLAUDE.md 用较大篇幅总结 Vitest 相对 Jest 的差异这些是写测试时必须遵守的硬性规范Mock 按测试文件隔离不再需要在afterAll中 unmockvitest 每个测试文件自动隔离。使用vitest.mock()与vitest.mocked()替代jest.mock/jest.MockedFunction做类型断言。模块 Mock 必须匹配导入方式如果源码用默认导入import os from node:osmock 对象需额外提供default属性若用命名导入import { platform } from node:os则直接 mock 对应字段CONTRIBUTING.md 给出了两种场景的完整示例。Spy 复用同一实例多个vitest.spyOn创建的 spy 是独立实例各自记录调用次数多次操作应复用同一个 spy 并链式mockReturnValueOnce。运行时配置用vitest.setConfig()例如在 Windows 下调整超时调用vitest.setConfig({ testTimeout: 100_000 })。避免从外部包导入const enumtsc 编译时会内联其值而 vitest 不会除非该枚举在运行时真实存在否则会报错。仓库配置层面的印证vitest.config.mts 提供了这些约定的底层支持test.globals: true与setupFiles: [./test/vitest.setup.ts]使describe/it/expect等全局可用restoreMocks: true这正是「无需手动重置 spy」的机制来源testTimeout与hookTimeout均为 60 秒CI 环境下自动限制线程isCI检测到 CI 时threads { minThreads: 1, maxThreads: 1 }串行跑测试避免资源竞争大量 alias 将crawlee、crawlee/*直接映射到packages/*/src源码测试针对工作区源码而非构建产物运行支持vitest.config.local.mts本地覆盖便于开发者自定义。macOS 代理测试环境准备仓库的代理相关测试使用不同的 loopback 地址来验证流量走向。与 Windows/Linux 不同macOS 默认只有一个回环地址127.0.0.1因此每次系统启动后需手动添加别名sudo ifconfig lo0 alias 127.0.0.2 up sudo ifconfig lo0 alias 127.0.0.3 up sudo ifconfig lo0 alias 127.0.0.4 up这些地址服务于 test/ 下的代理相关测试例如 proxy 配置、会话轮换场景。CONTRIBUTING.md 亦收录了同样命令可见这是 macOS 开发者的标准前置步骤Linux 环境则天然支持多个回环地址无需此操作。总结一份可执行的上手清单综合 .claude/CLAUDE.md 与仓库现状贡献者在 Crawlee 仓库的标准化工作流为corepack enable后用 pnpm 安装依赖pnpm install注意当前仓库以 pnpm 为准改动保持最小范围不触碰无关文件修复 bug 前先写复现测试vitest测试放根 test/ 目录提交前运行pnpm tsc-check-tests验证类型pnpm lint与pnpm format保持代码整洁提交信息按chore:/fix:/feat:三前缀规范书写推送遇 husky 钩子因 PATH 失败时使用--no-verifyPR 描述精炼说明改动与动机不写 Test plan 等废话。这份 CLAUDE.md 既是 AI 助手的编码约束也是一份浓缩的仓库工程手册——理解了它就理解了 Crawlee 的协作秩序与 Monorepo 设计哲学。【免费下载链接】crawleeCrawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.项目地址: https://gitcode.com/GitHub_Trending/cr/crawlee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考