企业官网建设流程全解析

读懂 Crawlee 元包（crawlee）的 CHANGELOG：v3.0.4 到 v3.18.1 的版本演进、发布机制与源码印证

【免费下载链接】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

本篇技术指南以仓库中 packages/crawlee/CHANGELOG.md 为对象，讲解这份由 lerna + Conventional Commits 自动生成的版本日志记录的是什么、如何生成、如何阅读，以及它背后的「crawlee 元包（metapackage）」在 monorepo 中承担的聚合职责。读完本文，你将掌握通过版本日志定位真实变更、结合源码验证条目、判断当前版本状态（v3 维护线与 v4 开发线）的完整方法。

一、这份 CHANGELOG 记录的是哪个包：crawlee 元包

在 npm 生态中，crawlee是一个「元包」：它本身几乎不包含业务实现代码，而是把整个 monorepo 中所有@crawlee/*子包的公开 API 统一聚合到单一入口，让用户只需npm install crawlee即可使用全部功能。这一点在源码中一目了然：

• packages/crawlee/src/index.ts 通过一系列export *重新导出@crawlee/core、@crawlee/utils、@crawlee/basic、@crawlee/browser、@crawlee/http、@crawlee/jsdom、@crawlee/linkedom、@crawlee/cheerio、@crawlee/puppeteer、@crawlee/playwright、@crawlee/browser-pool、@crawlee/fs-storage的全部符号；此外还提供了一个聚合命名空间utils，内含puppeteer、playwright、log、social、sleep、downloadListOfUrls、parseOpenGraph、extractMicrodata等工具。
• packages/crawlee/package.json 的dependencies全部以workspace:*指向@crawlee/basic、@crawlee/browser、@crawlee/browser-pool、@crawlee/cheerio、@crawlee/cli、@crawlee/core、@crawlee/fs-storage、@crawlee/http、@crawlee/impit-client、@crawlee/jsdom、@crawlee/linkedom、@crawlee/playwright、@crawlee/puppeteer、@crawlee/utils等内部包；peerDependencies中playwright与puppeteer均为可选（peerDependenciesMeta标记为optional），意味着用户按需自行安装浏览器自动化依赖即可。
• 该包还承担 CLI 入口："bin": "./src/cli.ts"，packages/crawlee/src/cli.ts 先通过import-local检查本地是否已安装 CLI，否则转发到@crawlee/cli。

因此，packages/crawlee/CHANGELOG.md记录的其实是「聚合包自身」的版本历史：绝大多数版本条目只是版本号递增（Version bump only for package crawlee），真正的内容变更散落在各子包的 CHANGELOG 中（如 packages/core/CHANGELOG.md、packages/browser-pool/CHANGELOG.md 等）。

二、CHANGELOG 从何而来：lerna + Conventional Commits 自动生成

这份文件不是手写的，而是发布流程的产物。仓库根目录的 lerna.json 提供了直接证据：

• "packages": ["packages/*"]：整个仓库是 pnpm workspace + lerna 管理的 monorepo；
• "command": { "version": { "conventionalCommits": true, "createRelease": "github", "message": "chore(release): %s" } }：每次发版时 lerna 依据 Conventional Commits 规范（feat / fix / perf / breaking change 等提交前缀）自动推断版本号、生成/追加 CHANGELOG、打 git tag 并创建 GitHub Release；
• "npmClient": "pnpm"：所有安装、构建、发布命令都经由 pnpm 执行；
• "ignoreChanges": ["**/test/**", "**/*.md"]：测试代码与文档变更不会触发版本号变化——这也是为什么很多 changelog 条目是纯粹的版本递增。

配套的 RELEASE.md 进一步说明发布机制：仓库存在 v3（3.x分支，维护线）与 v4（master分支，当前开发线）两条发布线；每次推送到主分支都会触发 canary 发布（不建 tag），稳定发布则通过 GitHub Actions 工作流手动触发lerna version（conventional-commits changelog、GitHub Release、git tag），并同步推送 Apify Docker 镜像构建。

理解了这套机制，「Version bump only」条目的成因就清楚了：当一次发版只涉及子包（例如某个修复只改了@crawlee/core）时，元包本身没有代码变动，但为了保持依赖版本与子包一致，lerna 仍会对元包做一次版本号递增，于是在 changelog 中留下一条无内容的「版本号递增」记录。

三、完整版本时间线：v3.0.4（2022-08-22）到 v3.18.1（2026-08-12）

该文件以时间倒序记录发布历史，最早可追溯到 v3 重构（monorepo 拆分出@crawlee/*子包）之后的 v3.0.4。以下按年代列出全部条目，其中「—」表示该版本为Version bump only（元包无自身变更）：

从表中可以清晰看到：约 70 个版本中，只有 7 个版本带有元包自身的真实变更，其余全部是依赖驱动的版本号递增——这正是元包 changelog 的典型形态。

四、少数带真实变更的条目：逐条深度解读

1. 3.18.0（2026-08-04）：declare missing dependencies

该版本修复了「缺失依赖未声明」的问题。对照 packages/crawlee/package.json 可以看到，元包的dependencies声明了全部@crawlee/*子包以及import-local、tslib。这类修复对元包至关重要：元包存在的意义就是「一处安装、全部可用」，任何子包依赖若未在dependencies中声明，都可能在使用 pnpm 严格依赖隔离时出现「幽灵依赖」缺失，导致安装后运行时找不到模块。

2. 3.16.0（2026-02-06）：droptsbuildinfofrom published packages

一项面向包体积与发布整洁度的性能改进：发布到 npm 的产物不再包含 TypeScript 增量编译生成的.tsbuildinfo文件。元包本身几乎无源码，这一改进主要惠及所有@crawlee/*子包的发布产物。

3. 3.15.2（2025-10-23）：Re-export MemoryStorage

从 crawlee 元包重新导出MemoryStorage。这是元包最典型的「透传」修复：底层存储实现（v3 时代位于内存存储实现中，v4 起并入@crawlee/core并更名MemoryStorageBackend，详见 docs/upgrading/upgrading_v4.md 的 rename cheat sheet）发生了变化，但元包作为统一导入面必须保证import { MemoryStorage } from 'crawlee'依然可用，因此需要补上对应的 re-export。

4. 3.5.5（2023-10-02）：allow to use any version of puppeteer or playwright

将puppeteer/playwright的 peer 依赖从「限定版本」放宽为「任意版本」。这直接呼应了 packages/crawlee/package.json 中当前的写法："peerDependencies": { "playwright": "*", "puppeteer": "*" }，且两者均为可选。对用户而言，这意味着你可以自由选择自己项目中的 Playwright / Puppeteer 版本，而不必与 Crawlee 内部锁定的版本保持一致。

5. 3.5.3 / 3.5.2（2023-08）：pin 内部依赖版本

连续两次修复都是「固定版本」：3.5.2 固定 crawlee 元包中@crawlee/*各包的依赖版本，3.5.3 将范围扩大到所有内部依赖。原因在于 monorepo 中workspace:*协议在发布时若不显式固定为具体版本号，用户安装到的元包可能引用到互相不匹配的子包版本。此后发布的元包都会把内部依赖钉死为与自身同步发布的精确版本。

6. 3.2.0（2023-02-07）：tslib 与 Playwright 1.29.2

两个修复：一是声明缺失的tslib依赖（tslib是 TypeScript 编译产物所需的运行时辅助库，缺失会导致运行时Cannot find module 'tslib'，对应 issue #1747）；二是将 Playwright 升级到 1.29.2 并放宽其 peer 依赖约束。当前 packages/crawlee/package.json 中仍保留"tslib": "^2.8.1"的显式声明，可以看作这一修复的延续。

7. 3.0.4（2022-08-22）：changelog 的起点

文件中最旧的条目。v3 是 Crawlee 大规模重构的版本：整个仓库被拆分为@crawlee/*多包 monorepo，crawlee聚合包由此诞生，这份 changelog 也从那时开始记录。

五、如何顺着「Version bump only」找到真实变更

元包 changelog 中大量条目没有细节，但这不意味着版本没有实质变化。真实变更在两个地方可以查到：

1. 根目录 CHANGELOG.md：它是所有子包 changelog 的合并视图。以 3.18.1（2026-08-12）为例，元包条目只是版本号递增，而根 changelog 中同期记录了：
   • core：不再清除正在使用中的存储（对应 issue #3156）；
   • playwright：更新handleCloudflareChallenge以适配新的 Cloudflare 验证页面结构（对应 issue #3717）；
   • 尊重JSDOM/LinkeDOM上下文enqueueLinks中的maxCrawlDepth（对应 issue #3927）。
2. 各子包的 packages/*/CHANGELOG.md：定位具体模块（core、browser-pool、playwright、utils 等）的变更细节，精确到对应的修复、特性与性能改进条目。

阅读建议：把元包 changelog 当作「版本清单」，把根 changelog 与子包 changelog 当作「变更明细」，两者配合使用。

六、用元包源码印证 changelog 条目

changelog 中反复出现的「透传 / 依赖声明」类修复，都能在当前源码中找到对应物：

• 透传职责：packages/crawlee/src/index.ts 中export * from '@crawlee/fs-storage'、export * from '@crawlee/core'等语句，正是 3.15.2「Re-export MemoryStorage」这类修复的落点；
• 依赖声明：3.18.0 / 3.5.3 / 3.5.2 对应的成果即 packages/crawlee/package.json 中完整的dependencies列表与固定的tslib版本；
• 可选 peer 依赖：3.5.5「允许任意版本 puppeteer/playwright」对应的正是peerDependencies中的"*"通配与peerDependenciesMeta中的optional: true；
• 发布约束：lerna.json 中"ignoreChanges": ["**/test/**", "**/*.md"]解释了为什么大量版本只有版本号变化而没有内容变化。

七、当前工作树与 v4 迁移状态

一个值得注意的细节：截至本仓库当前工作树，packages/crawlee/package.json 中的版本号已是4.0.0，engines要求node >= 22.0.0，且采用原生 ESM（"type": "module"）；而 packages/crawlee/CHANGELOG.md 记录的最后一个已发布版本仍是 3.18.1（2026-08-12）。

结合 RELEASE.md 的说明可以推断：仓库master分支正处于 v4 开发线，4.0.0的发布条目尚未写入该 changelog。v4 的破坏性变更集中在 docs/upgrading/upgrading_v4.md，包括但不限于：handleRequestFunction更名为requestHandler、StorageClient重塑为StorageBackend、参数校验从ow迁移到 zod（错误类型变为ArgumentValidationError）、原生 ESM 化、要求 Node.js 22+ 与 TypeScript 5.8+、Cheerio 升级到 v1 稳定版等。更早版本（v1～v3）的迁移说明见 docs/upgrading/upgrading_v1.md、docs/upgrading/upgrading_v2.md、docs/upgrading/upgrading_v3.md。

八、小结：把这份 CHANGELOG 用起来

• 当版本日志：按 packages/crawlee/CHANGELOG.md 中的版本号 + 日期，确认你当前使用的crawlee版本与升级路径；
• 当变更索引：遇到「Version bump only」条目时，跳转到根 CHANGELOG.md 或对应子包 changelog 查看真实变更；
• 当发布机制说明：通过 lerna.json 与 RELEASE.md 理解 canary / rc / stable 三种发布形态及其 dist-tag 策略；
• 当源码对照表：用 packages/crawlee/src/index.ts 与 packages/crawlee/package.json 验证每个「透传 / 依赖」类条目是否已落实。

安装使用时，直接npm install crawlee（或使用 pnpm / yarn），并根据需要额外安装playwright或puppeteer——元包的 peer 依赖设计保证了浏览器自动化库的版本选择权始终在你手中。

【免费下载链接】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