ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Crawlee CLI 实战指南:create、run 与 install-playwright-browsers 命令详解及版本演进

Crawlee CLI 实战指南:create、run 与 install-playwright-browsers 命令详解及版本演进 Crawlee CLI 实战指南create、run 与 install-playwright-browsers 命令详解及版本演进【免费下载链接】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/cli是 Crawlee 官方提供的命令行工具用于在 Node.js 环境中一键初始化、运行爬虫项目并管理 Playwright 浏览器依赖。本文以 packages/cli/CHANGELOG.md 的版本演进为骨架结合 packages/cli/src 的源码实现系统讲解crawlee create、crawlee run、crawlee install-playwright-browsers三个子命令的完整用法、参数语义与底层工作原理帮助读者从会敲命令进阶到理解 CLI 内部机制。认识 crawlee/cliCrawlee 官方命令行工具Crawlee 是一个面向 Node.js 的网络爬取与浏览器自动化库官方文档将 CLI 定位为创建新项目最快、最好的方式见 docs/introduction/01-setting-up.mdx 与 docs/quick-start/index.mdx。CLI 以独立包crawlee/cli发布其二进制入口crawlee直接指向 packages/cli/src/index.ts。快速上手无需全局安装直接通过npx调用即可npx crawlee create my-crawler根据 packages/cli/package.json该包要求 Node.js 22.0.0历史文档如 docs/quick-start/index.mdx 中的最低要求为 Node.js 16实际以当前仓库声明的引擎版本为准。包的bin字段将crawlee命令映射到./src/index.ts因此npx crawlee与本地crawlee等价。命令入口的实现结构入口文件 packages/cli/src/index.ts 基于 yargs 构建命令行解析器关键配置如下scriptName(crawlee)所有帮助与错误信息中以crawlee作为命令名.version(getCLIVersion())-v/--version输出版本号版本号通过require(../package.json)读取开发期有src目录或require(./package.json)生产构建获取-h/--help、recommendCommands()、showHelpOnFail(true)、strict()提供命令推荐、失败时显示帮助、严格参数校验demandCommand(1, )强制要求至少输入一个子命令未输入时打印帮助。CLI 目前注册了三个子命令分别由三个类实现子命令实现类源码文件create [project-name]CreateProjectCommandpackages/cli/src/commands/CreateProjectCommand.tsrunRunProjectCommandpackages/cli/src/commands/RunProjectCommand.tsinstall-playwright-browsersInstallPlaywrightBrowsersCommandpackages/cli/src/commands/InstallPlaywrightBrowsersCommand.tscrawlee create一键初始化爬虫项目create是 CLI 中使用频率最高的命令负责从远程模板清单中选择脚手架模板下载文件、改写项目名并自动安装依赖。命令用法与参数npx crawlee create [project-name] [--template 模板名]参数类型说明project-name位置参数string新项目目录名。未提供时进入交互式输入提示-t, --template选项string指定模板名枚举值来自远程清单。未提供时进入交互式选择列表两个参数均来自 CreateProjectCommand.ts 的builder定义project-name为位置参数template的合法值choices在命令执行前通过fetchManifest()从远程获取。交互式流程当参数缺失时命令会借助inquirer/prompts提供交互提示输入项目名input提示 Name of the new project folder:并通过validateProjectName校验——当前实现只要求项目名不能为空字符串validateProjectName中name.length 0时抛出错误选择模板select提示 Please select the template for your new Crawlee project每个选项显示为模板描述文本默认选中第一项。模板清单与项目结构模板信息由 packages/templates/src/index.ts 的fetchManifest()从远程 manifest 获取仓库内对应的模板清单样本见 packages/templates/manifest.json。manifest 中的每个模板都声明了若干文件例如getting-started-ts包含src/main.ts、.dockerignore、.gitignore、Dockerfile、package.json、README.md、tsconfig.json。从仓库内模板清单可以看到当前支持的全部模板模板名说明语言getting-started-ts/getting-started-js入门示例TypeScript / JavaScriptempty-ts/empty-js空项目TypeScript / JavaScriptcheerio-ts/cheerio-jsCheerioCrawler 模板TypeScript / JavaScriptplaywright-ts/playwright-jsPlaywrightCrawler 模板TypeScript / JavaScriptcamoufox-ts基于 Camoufox 的 PlaywrightCrawler 模板TypeScriptpuppeteer-ts/puppeteer-jsPuppeteerCrawler 模板TypeScript / JavaScript模板文件的实际样例可在 packages/templates/templates 目录下按模板名查看如 packages/templates/templates/playwright-ts。文件下载与项目生成机制下载与生成逻辑在 CreateProjectCommand.ts 中实现创建目录mkdirSync(projectDir)创建process.cwd() projectName目录若目录已存在EEXIST错误直接报错并终止并行下载downloadTemplateFilesToDisk遍历模板的每个文件通过 Node.jshttps模块下载downloadFile按file.path在目标目录中重建目录结构并写入失败重试每个文件下载使用withRetries(func, 3, ...)包装最多重试 3 次重试间隔为2500 2500 * attempt毫秒且全部文件并行执行后统一等待Promise.all改写项目名rewrite()读取生成的package.json用正则name: [\w-]将name字段替换为用户输入的项目名安装依赖根据平台选择 npm 可执行文件Windows 下为npm.cmd执行npm installstdio: inherit透传输出输出结果成功后打印绿色提示Project name was created. To run it, run cd name and npm start.。值得留意的是 manifest 本身也带重试withRetries(fetchManifest, 5, Template Manifest)即远程清单获取失败会重试最多 5 次以提升网络不稳定场景下的健壮性。实战创建并运行入门项目# 1. 创建项目交互式选择模板推荐选 getting-started 入门示例 npx crawlee create my-crawler # 2. 进入项目并启动爬虫 cd my-crawler npm start创建成功后CLI 已经代为完成依赖安装npm start即可直接运行示例爬虫。官方部署指南也基于这一命令展开例如 docs/deployment/aws-cheerio.md 与 docs/deployment/gcp-cheerio.md 都以npx crawlee create作为部署流程的起点docs/deployment/gcp-browsers.md 则指出初始化脚本会同时准备好 Dockerfile。crawlee run运行爬虫项目run子命令用于在当前工作目录下运行爬虫项目本质是对 npm 脚本的封装。命令用法与参数crawlee run [--no-purge] [--script npm脚本名]参数定义见 RunProjectCommand.ts参数类型默认值说明-t, --purgebooleantrue是否在启动时自动清理默认存储。使用--no-purge关闭-s, --scriptstringstart指定要运行的 npm 脚本例如--scriptstart:prodpurge 机制的底层实现handler中的实现非常简洁RunProjectCommand.tsconst env { ...process.env }; if (!args.purge) { env.CRAWLEE_PURGE_ON_START 0; } execSync(npm run ${args.script}, { stdio: inherit, env });即当用户传入--no-purge时CLI 向子进程注入环境变量CRAWLEE_PURGE_ON_START0从而禁用 Crawlee 启动时对默认存储dataset、key-value store、request queue的自动清理。CLI 入口的帮助示例中也有对应说明crawlee run --no-purge—— Runs the project in current working directory and disables automatic purging of default storages见 packages/cli/src/index.ts。这一能力在版本演进中经历过一次平台修复3.7.0版本修复了--no-purge在 Windows 上的兼容性问题详见下文版本演进章节。crawlee install-playwright-browsers安装 Playwright 浏览器对于使用 Playwright 的项目浏览器二进制文件需要单独安装。该子命令将这一操作封装为一条命令。命令用法与参数crawlee install-playwright-browsers [--force]参数类型默认值说明-f, --forcebooleanfalse即使环境已标记为已安装浏览器也强制重新安装实现见 InstallPlaywrightBrowsersCommand.tsif (process.env[envVariable]) { if (!args.force) { console.log(colors.green(Browsers are already installed!)); return; } // 强制安装打印警告后继续 } else { console.log(colors.green(Installing Playwright browsers...)); } execSync(npx playwright install, { stdio: inherit });环境变量 CRAWLEE_SKIP_BROWSER_INSTALL命令读取环境变量CRAWLEE_SKIP_BROWSER_INSTALL常量envVariable作为已安装标记若该变量存在且未加--force命令直接提示 Browsers are already installed! 并跳过安装若加--force则打印黄色警告在已安装浏览器的环境中重新安装 Playwright 浏览器……后继续执行。最终安装动作委托给npx playwright install。这一设计与模板的生命周期相关联3.5.5版本曾为 Playwright 模板加入 postinstall 钩子自动安装浏览器详见下文因此CRAWLEE_SKIP_BROWSER_INSTALL常用于 CI/CD 等预装环境避免重复下载。版本演进从 3.0.4 到 3.18.1 的关键变更packages/cli/CHANGELOG.md 完整记录了crawlee/cli自 2022 年 8 月至 2026 年 8 月共 75 个版本的变更遵循 Conventional Commits 规范生成。绝大多数版本标注为 Version bump only for package crawlee/cli——即该次发布仅随 Crawlee 整体版本号递增、CLI 自身无独立变更真正影响 CLI 的变更集中在以下 6 处实际变更一览版本日期类型变更内容3.2.02023-02-07Bug Fixes声明缺失的tslib依赖修复因传递依赖缺失导致的运行时问题3.5.32023-08-31Bug Fixes固定pin所有内部依赖版本保证发布一致性3.5.52023-10-02Bug Fixes模板为 Playwright 模板增加 postinstall 自动安装浏览器3.7.02023-12-21Bug Fixes修复--no-purge在 Windows 上的兼容性3.15.32025-11-10Bug Fixes支持创建以数字开头的项目名3.16.02026-02-06Performance Improvements从发布包中移除tsbuildinfo文件减小包体积其中两点可在当前源码中找到直接对应3.15.3数字开头的项目名当前 CreateProjectCommand.ts 的validateProjectName仅校验非空而改写package.json的正则name: [\w-]中的\w本身可匹配数字——可推断该修复主要保证了数字开头名称在 npm 命名校验与依赖安装链路中的完整支持3.16.0移除 tsbuildinfo从发布产物中剔除 TypeScript 增量编译缓存文件对应更小的安装体积与更快的冷安装体验。完整版本时间线版本日期备注3.0.42022-08-22版本同步3.1.02022-10-13版本同步3.1.12022-11-07版本同步3.1.22022-11-15版本同步3.2.02023-02-07声明缺失的tslib依赖3.2.12023-02-07版本同步3.2.22023-02-08版本同步3.3.02023-03-09版本同步3.3.12023-04-11版本同步3.3.22023-05-11版本同步3.3.32023-05-31版本同步3.4.02023-06-12版本同步3.4.12023-07-13版本同步3.4.22023-07-19版本同步3.5.02023-07-31版本同步3.5.12023-08-16版本同步3.5.22023-08-21版本同步3.5.32023-08-31固定所有内部依赖版本3.5.42023-09-11版本同步3.5.52023-10-02Playwright 模板 postinstall 安装浏览器3.5.62023-10-04版本同步3.5.72023-10-05版本同步3.5.82023-10-17版本同步3.6.02023-11-15版本同步3.6.12023-11-15版本同步3.6.22023-11-26版本同步3.7.02023-12-21修复 Windows 下--no-purge3.7.12024-01-02版本同步3.7.22024-01-09版本同步3.7.32024-01-30版本同步3.8.02024-02-21版本同步3.8.12024-02-22版本同步3.8.22024-03-21版本同步3.9.02024-04-10版本同步3.9.12024-04-11版本同步3.9.22024-04-17版本同步3.10.02024-05-16版本同步3.10.12024-05-23版本同步3.10.22024-06-03版本同步3.10.32024-06-07版本同步3.10.42024-06-11版本同步3.10.52024-06-12版本同步3.11.02024-07-09版本同步3.11.12024-07-24版本同步3.11.22024-08-28版本同步3.11.32024-09-03版本同步3.11.42024-09-23版本同步3.11.52024-10-04版本同步3.12.02024-11-04版本同步3.12.12024-12-04版本同步3.12.22025-01-27版本同步3.13.02025-03-04版本同步3.13.12025-04-07版本同步3.13.22025-04-08版本同步3.13.32025-05-05版本同步3.13.42025-05-14版本同步3.13.52025-05-20版本同步3.13.62025-06-05版本同步3.13.72025-06-06版本同步3.13.82025-06-16版本同步3.13.92025-06-27版本同步3.13.102025-07-09版本同步3.14.02025-07-25版本同步3.14.12025-08-05版本同步3.15.02025-09-17版本同步3.15.12025-09-26版本同步3.15.22025-10-23版本同步3.15.32025-11-10支持数字开头的项目名3.16.02026-02-06发布包移除tsbuildinfo3.17.02026-06-04版本同步3.18.02026-08-04版本同步3.18.12026-08-12版本同步需要说明的是当前仓库中 packages/cli/package.json 记录的版本为 4.0.0而 CHANGELOG 的最新条目停留在 3.18.1——即该变更日志覆盖的是 3.x 系列当前工作区已进入 4.x 主版本线CHANGELOG 会在后续发布中同步更新。小结crawlee/cli以极简的三命令设计覆盖了爬虫项目创建 → 运行 → 环境准备的完整生命周期crawlee create基于远程模板清单完成脚手架下载、项目名改写与依赖安装内置 3 次文件下载重试与 5 次 manifest 获取重试crawlee run通过--no-purge映射到CRAWLEE_PURGE_ON_START环境变量控制存储清理行为--script灵活切换 npm 脚本crawlee install-playwright-browsers以CRAWLEE_SKIP_BROWSER_INSTALL--force的组合适配预装环境与强制重装两种场景。其版本历史packages/cli/CHANGELOG.md显示 CLI 自身高度稳定——75 个版本中仅 6 次携带实质变更且全部为依赖修复、平台兼容与包体积优化其余均为版本同步。对于开发者和 CI 使用者而言掌握这三个命令及配套环境变量即可在不同平台与部署场景本地开发、AWS、GCP 等下顺畅完成 Crawlee 项目的初始化与运行。【免费下载链接】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),仅供参考
返回列表