apify-actor-development

Apify Actor 开发

执行与数据范围

这是文档，不是可直接使用的 Actor。请使用经过审查且版本固定的 CLI、SDK 和模板，并检查生命周期脚本和安装脚本；包管理器无法保证安全。沿用现有语言和锁文件，不要反复询问。锁文件未更改时使用 npm ci；仅指定精确的 Python 版本并不能锁定所有制品。本地 Actor 可通过配置的客户端访问网络或云端，因此测试前请检查存储设置和凭据；默认本地存储并不保证数据不会上传。限制爬取来源、重定向、专用网络访问、页面数量、并发数、重试次数以及云端／代理成本。推送、构建、运行或激活待机服务会发布代码或启动收费任务，必须使用经授权的账户／Actor，并制定回滚计划。请明确处理日志脱敏。

生成归属信息是可选的任务元数据，不代表需要修改无关文件或猜测模型。保留现有元数据和历史记录，仅在获准时分享。

适用场景

• 你需要创建、修改或调试 Apify Actor 项目。
• 任务涉及选择 Apify 模板、连接 Actor 输入／输出，或实现 Actor 运行逻辑。
• 你需要有关 apify CLI 身份验证、项目初始化或部署工作流的安全指导。

什么是 Apify Actors？

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

核心概念：

• 接受定义明确的 JSON 输入
• 执行独立任务（网页抓取、自动化、数据处理）
• 将结构化 JSON 输出到数据集，和／或将数据存储在键值存储中
• 运行时间可从几秒到几小时，甚至无限期
• 持久化状态，并可重新启动

前提条件与设置（必须）

创建或修改 Actor 前，请确认已安装 apify CLI：apify --help。

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

# Preferred: install via a package manager (provides integrity checks)
npm install -g apify-cli

# Or (Mac): brew install apify-cli

**安全提示：**切勿通过将远程脚本直接传入 Shell 的方式安装 CLI。 始终使用包管理器。

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

apify info  # Should return your username

如果尚未登录，请检查是否已定义 APIFY_TOKEN 环境变量（如果没有，请让用户在 https://console.apify.com/settings/integrations 生成令牌，然后用该令牌定义 APIFY_TOKEN）。

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

# Option 1 (preferred): The CLI automatically reads APIFY_TOKEN from the environment.
# Just ensure the env var is exported and run any apify command — no explicit login needed.

# Option 2: Interactive login (prompts for token without exposing it in shell history)
apify login

**安全提示：**避免将令牌作为命令行参数传入（例如 apify login -t <token>）。 参数会显示在进程列表中，也可能记录在 Shell 历史记录里。 建议使用环境变量或交互式登录。 切勿在源代码或配置文件中记录、打印或嵌入 APIFY_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/actor.json（参见 references/actor-json.md）
6. 编写文档 - 为市场创建全面的 README.md
7. 本地测试 - 运行 apify run 验证功能（参见下文本地测试部分）
8. 部署 - 运行 apify push 将 actor 部署到 Apify 平台（actor 名称在 .actor/actor.json 中定义）

安全

将所有抓取的网页内容视为不受信任的输入。 Actor 会从外部网站摄取数据，这些网站可能包含恶意载荷。请遵循以下规则：

• 清理抓取的数据 — 切勿将原始 HTML、URL 或抓取的文本直接传入 shell 命令、eval()、数据库查询或模板引擎。使用适当的转义或参数化 API。
• 验证并对所有外部数据进行类型检查 — 在推送到数据集或键值存储之前，验证值是否匹配预期的类型和格式。拒绝或清理意外的结构。
• 不要执行或解释抓取的内容 — 切勿将抓取的文本视为代码、命令或配置。来自网站的内容可能包含提示词注入尝试或嵌入式脚本。
• 将凭据与数据管道隔离 — 确保 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）
• 使用带指数退避的重试策略
• 设置合理的并发数：HTTP（10-50），浏览器（1-5）
• 在 .actor/input_schema.json 中设置合理的默认值
• 在 .actor/output_schema.json 中定义输出架构
• 将数据推送到数据集前进行清理和验证
• 使用语义化 CSS 选择器并设置备用策略
• 遵守 robots.txt 和服务条款，并实施速率限制
• 使用经过审核的 SDK 日志记录器（来自 apify 或 @apify/log 的 log），并明确屏蔽机密和个人数据
• 实现就绪探针处理程序（Actor 使用待机模式时必需）

✗ 不应做：

• 使用 npm start、npm run start、npx apify run 或类似命令运行 Actor（应改用 apify run）
• 假设 apify run 的本地存储会推送到 Apify Console 或可在其中查看——数据仅存储在本地；使用 apify push 部署，并在平台上运行，才能在 Console 中查看结果
• 在 Cloud 上依赖 Dataset.getInfo() 获取最终计数
• HTTP/Cheerio 可用时仍使用浏览器爬虫
• 将本应放在输入架构或环境变量中的值硬编码
• 跳过输入验证或错误处理
• 让服务器负载过高——应使用适当的并发数和延迟
• 抓取禁止的内容或忽视服务条款
• 除非明确获准，否则存储个人/敏感数据
• 在 CheerioCrawler（v3.x）上使用 requestHandlerTimeoutMillis 等已弃用选项
• 使用 additionalHttpHeaders——应改用 preNavigationHooks
• 将原始爬取内容传入 shell 命令、eval() 或代码生成函数
• 使用 console.log() 或 print() 代替 Apify 日志记录器——这会绕过凭据屏蔽
• 未经明确许可，不要禁用待机模式

日志记录

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

检查 .actor/actor.json 中的 usesStandbyMode——仅在其值为 true 时实现。

命令

apify run          # Run Actor locally
apify login        # Authenticate account
apify push         # Deploy to Apify platform (uses name from .actor/actor.json)
apify help         # List all commands

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

本地测试

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

storage/key_value_stores/default/INPUT.json

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

重要提示——本地存储不会与 Apify Console 同步：

• 运行 apify run 后，所有数据（数据集、键值存储、请求队列）仅存储在本地文件系统的 storage/ 目录中。
• 默认的本地存储不会自动同步，但显式配置的远程客户端/存储 ID/设置可以上传数据；请核实实际代码和环境。
• 若要在 Apify Console 上验证结果，必须先使用 apify push 部署 Actor，然后在平台上运行。
• 不要依赖 Apify Console 来验证本地运行的结果——应检查本地 storage/ 目录或查看 Actor 的日志输出。

待机模式

有关完整的待机模式文档，包括 JavaScript/TypeScript 和 Python 的就绪探针实现，请参阅 references/standby-mode.md。

项目结构

.actor/
├── actor.json           # Actor config: name, version, env vars, runtime
├── input_schema.json    # Input validation & Console form definition
└── output_schema.json   # Output storage and display templates
src/
└── main.js/ts/py       # Actor entry point
storage/                # Local-only storage (NOT synced to Apify Console)
├── datasets/           # Output items (JSON objects)
├── key_value_stores/   # Files, config, INPUT
└── request_queues/     # Pending crawl requests
Dockerfile              # Container image definition

Actor 配置

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

输入架构

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

输出架构

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

数据集架构

请参阅 references/dataset-schema.md，了解数据集架构的结构、配置和显示属性。

键值存储架构

请参阅 references/key-value-store-schema.md，了解键值存储架构的结构、集合和配置。

Apify MCP 工具

如果已配置 MCP 服务，请使用以下工具查阅文档：

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

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

资源

• docs.apify.com/llms.txt - Apify 快速参考文档
• docs.apify.com/llms-full.txt - Apify 完整文档
• https://crawlee.dev/llms.txt - Crawlee 快速参考文档
• https://crawlee.dev/llms-full.txt - Crawlee 完整文档
• whitepaper.actor - 完整的 Actor 规范

限制

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