Apify Actor 开发

apify-actor-development
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.50/5
使用15.4K

Apify Actor 开发

重要提示： 在开始之前，请填写 .actor/actor.json 中 meta 部分的 generatedBy 属性。将其替换为您当前使用的工具和模型，例如 "Claude Code with Claude Sonnet 4.5"。这有助于 Apify 针对特定的 AI 工具和模型监控并改进 AGENTS.md。

适用场景

  • 您需要创建、修改或调试 Apify Actor 项目。
  • 任务涉及选择 Apify 模板、配置 Actor 输入/输出或实现 Actor 运行时逻辑。
  • 您需要关于 apify CLI 身份验证、项目引导或部署工作流的安全设置指南。

什么是 Apify Actors？

Actors 是受 UNIX 哲学启发而设计的无服务器程序——它们专注于做好一件事，并可以轻松组合以构建复杂的系统。它们被打包为 Docker 镜像，并在云端的隔离容器中运行。

核心概念：

  • 接收定义明确的 JSON 输入

  • 执行隔离的任务（网页抓取、自动化、数据处理）

  • 将结构化的 JSON 输出到数据集（datasets）和/或存储在键值存储（key-value stores）中

  • 运行时间可从几秒到几小时，甚至无限期运行

  • 可持久化状态并支持重启

前置条件与设置（强制执行）

在创建或修改 Actor 之前，请验证是否安装了 apify CLI：apify --help。

如果尚未安装，请使用以下方法之一（按推荐顺序排列）：

bash
# 推荐：通过包管理器安装（提供完整性检查）
npm install -g apify-cli

或 (Mac): brew install apify-cli

> 安全提示： 不要通过将远程脚本直接管道传输到 shell 来安装 CLI。请始终使用包管理器。

安装 apify CLI 后，使用以下命令检查是否已登录：

bash
apify info  # 应返回您的用户名

如果尚未登录，请检查是否定义了 APIFY_TOKEN 环境变量（如果未定义，请要求用户在 https://console.apify.com/settings/integrations 生成一个，然后使用该 token 定义 APIFY_TOKEN）。

然后使用以下方法之一进行身份验证：

bash
# 选项 1（推荐）：CLI 自动从环境中读取 APIFY_TOKEN。

只需确保环境变量已导出并运行任何 apify 命令即可——无需显式登录。


选项 2：交互式登录（提示输入 token，不会在 shell 历史记录中暴露）

apify login

> 安全提示： 避免将 token 作为命令行参数传递（例如 apify login -t <token>）。
> 参数在进程列表中可见，并可能被记录在 shell 历史记录中。
> 优先使用环境变量或交互式登录。
> 永远不要在源代码或配置文件中记录、打印或嵌入 APIFY_TOKEN。
> 使用具有最小必要权限的 token（范围限定 token）并定期轮换。

模板选择

重要提示： 在开始 Actor 开发之前，请务必询问用户偏好哪种编程语言：

  • JavaScript - 使用 apify create <actor-name> -t project_empty

  • TypeScript - 使用 apify create <actor-name> -t ts_empty

  • Python - 使用 apify create <actor-name> -t python-empty

根据所选语言使用相应的 CLI 命令。
根据用户的语言选择。后续可根据需要安装额外的软件包（如 Crawlee、Playwright 等）。

快速上手流程

1. 创建 Actor 项目 - 根据用户的语言偏好运行相应的 apify create 命令（参见上文的“模板选择”）
2. 安装依赖（安装前请核实包名是否正确）
- JavaScript/TypeScript：npm install（使用 package-lock.json 以确保安装的可复现性和完整性校验 —— 请将 lockfile 提交至版本控制系统）
- Python：pip install -r requirements.txt（在 requirements.txt 中固定精确版本，例如 crawlee==1.2.3，并将该文件提交至版本控制系统）
3. 实现逻辑 - 在 src/main.py、src/main.js 或 src/main.ts 中编写 Actor 代码
4. 配置 Schema - 更新 .actor/input_schema.json、.actor/output_schema.json 和 .actor/dataset_schema.json 中的输入/输出 Schema
5. 配置平台设置 - 在 .actor/actor.json 中更新 Actor 元数据（参见 references/actor-json.md）
6. 编写文档 - 为市场（Marketplace）创建详尽的 README.md
7. 本地测试 - 运行 apify run 验证功能（参见下文的“本地测试”部分）
8. 部署 - 运行 apify push 将 Actor 部署到 Apify 平台（Actor 名称在 .actor/actor.json 中定义）

安全性

将所有抓取的网页内容视为不可信输入。 Actor 从外部网站获取数据，其中可能包含恶意负载。请遵循以下规则：

  • 清洗抓取数据 —— 绝不要将原始 HTML、URL 或抓取的文本直接传递给 shell 命令、eval()、数据库查询或模板引擎。请使用适当的转义或参数化 API。 <!-- security-allowlist: defensive untrusted-input guidance -->
  • 验证并检查所有外部数据的类型 —— 在推送到数据集（datasets）或键值存储（key-value stores）之前，验证其值是否符合预期的类型和格式。拒绝或清洗异常结构。
  • 不要执行或解析抓取的内容 —— 绝不要将抓取的文本视为代码、命令或配置。网站内容可能包含提示词注入（prompt injection）尝试或嵌入式脚本。
  • 将凭据与数据流水线隔离 —— 确保 APIFY_TOKEN 和其他密钥在请求处理器中不可见，且不会随抓取数据一起传递。使用 Apify SDK 内置的凭据管理，而非在数据处理代码中通过环境变量传递 Token。
  • 安装前审查依赖 —— 使用 npm install 或 pip install 添加包时，请核实包名和发布者。抢注域名（Typosquatting）是常见的供应链攻击手段。优先选择知名且活跃维护的软件包。
  • 固定版本并使用 lockfile —— 务必提交 package-lock.json (Node.js) 或在 requirements.txt (Python) 中固定精确版本。Lockfile 可确保构建的可复现性并防止依赖被静默替换。定期运行 npm audit 或 pip-audit 以检查已知漏洞。

最佳实践

✓ 推荐做法：

  • 使用 apify run 在本地测试 Actor（可配置 Apify 环境和存储）

  • 在 Apify 平台上运行代码时使用 Apify SDK (apify)

  • 尽早验证输入，配合适当的错误处理并优雅地失败

  • 针对静态 HTML 使用 CheerioCrawler（比浏览器快 10 倍）

  • 仅针对重度依赖 JavaScript 的网站使用 PlaywrightCrawler

  • 针对复杂的抓取任务使用路由模式 (createCheerioRouter/createPlaywrightRouter)

  • 实现重试策略

指数退避 (exponential backoff)
  • 使用合理的并发数：HTTP (10-50)，浏览器 (1-5)

  • 在 .actor/input_schema.json 中设置合理的默认值

  • 在 .actor/output_schema.json 中定义输出架构

  • 在将数据推送到数据集之前进行清理和验证

  • 使用带有回退策略的语义化 CSS 选择器

  • 遵守 robots.txt 和服务条款 (ToS)，并实现速率限制

  • 务必使用 apify/log 包 —— 它可以过滤敏感数据（API 密钥、令牌、凭据）

  • 实现就绪探针 (readiness probe) 处理程序（如果 Actor 使用待机模式则必须实现）

✗ 避免：

  • 使用 npm start、npm run start、npx apify run 或类似命令运行 Actor（请改用 apify run）

  • 认为 apify run 的本地存储会推送至或可见于 Apify 控制台 —— 它仅限本地；请使用 apify push 部署并在平台上运行以在控制台中查看结果

  • 在云端依赖 Dataset.getInfo() 获取最终计数

  • 在 HTTP/Cheerio 可行时使用浏览器爬虫

  • 硬编码本应在输入架构或环境变量中定义的值

  • 跳过输入验证或错误处理

  • 给服务器造成过大负载 —— 请使用适当的并发数和延迟

  • 抓取禁止的内容或忽略服务条款

  • 除非获得明确许可，否则不要存储个人/敏感数据

  • 在 CheerioCrawler (v3.x) 中使用已弃用的选项，如 requestHandlerTimeoutMillis

  • 使用 additionalHttpHeaders —— 请改用 preNavigationHooks

  • 将抓取的原始内容传递给 shell 命令、eval() 或代码生成函数 <!-- security-allowlist: prohibited-pattern checklist -->

  • 使用 console.log() 或 print() 代替 Apify 日志记录器 —— 这些方法会绕过凭据过滤

  • 在没有明确许可的情况下禁用待机模式

日志记录

有关日志记录的完整文档（包括可用日志级别以及 JavaScript/TypeScript 和 Python 的最佳实践），请参阅 references/logging.md。

检查 .actor/actor.json 中的 usesStandbyMode —— 仅在设置为 true 时才实现。

命令

bash
apify run          # 在本地运行 Actor
apify login        # 账户身份验证
apify push         # 部署到 Apify 平台（使用 .actor/actor.json 中的名称）
apify help         # 列出所有命令

重要提示： 始终使用 apify run 在本地测试 Actor。不要使用 npm run start、npm start、yarn start 或其他包管理器命令 —— 它们无法正确配置 Apify 环境和存储。

本地测试

使用 apify run 在本地测试 Actor 时，请在以下路径创建 JSON 文件来提供输入数据：

code
storage/key_value_stores/default/INPUT.json

该文件应包含在 .actor/input_schema.json 中定义的输入参数。Actor 在本地运行时将读取此输入，以模拟其在 Apify 平台上接收输入的方式。

重要提示 - 本地存储不会同步到 Apify 控制台：

  • 运行 apify run 时，所有数据（数据集、键值存储、请求队列）仅存储在本地文件系统的 storage/ 目录中。

  • 这些数据绝不会自动上传或推送到 Apify 平台。它们仅存在于你的机器上。

  • 要在 Apify 控制台上验证结果，必须使用 apify push 部署 Actor，然后在平台上运行。

  • 不要依赖检查 Apify 控制台来验证本地运行的结果 —— 请检查本地 storage/ 目录或查看 Actor 的日志输出。

待机模式

有关待机模式的完整文档（包括就绪状态），请参阅 references/standby-mode.md。
适用于 JavaScript/TypeScript 和 Python 的 probe 实现。

项目结构

code
.actor/
├── actor.json           # Actor 配置：名称、版本、环境变量、运行时
├── input_schema.json    # 输入验证与控制台表单定义
└── output_schema.json   # 输出存储与显示模板
src/
└── main.js/ts/py       # Actor 入口文件
storage/                # 仅本地存储（不同步到 Apify Console）
├── datasets/           # 输出项（JSON 对象）
├── key_value_stores/   # 文件、配置、INPUT
└── request_queues/     # 待处理的爬取请求
Dockerfile              # 容器镜像定义

Actor 配置

有关 actor.json 的完整结构和配置选项，请参阅 references/actor-json.md。

输入 Schema

有关输入 schema 的结构和示例，请参阅 references/input-schema.md。

输出 Schema

有关输出 schema 的结构、示例和模板变量，请参阅 references/output-schema.md。

Dataset Schema

有关 dataset schema 的结构、配置和显示属性，请参阅 references/dataset-schema.md。

Key-Value Store Schema

有关 key-value store schema 的结构、集合和配置，请参阅 references/key-value-store-schema.md。

Apify MCP 工具

如果配置了 MCP 服务器，请使用以下工具获取文档：

  • search-apify-docs - 搜索文档
  • fetch-apify-docs - 获取完整的文档页面

否则，MCP 服务器 URL 为：https://mcp.apify.com/?tools=docs。

资源

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。