Apify Actor 化

将现有软件转换为与 Apify 平台兼容的可复用无服务器应用程序，即 Actor。Actor 是打包为 Docker 镜像的程序，它接受定义良好的 JSON 输入，执行一个操作，并可选择性地生成结构化的 JSON 输出。

快速开始

1. 在项目根目录运行 apify init
2. 使用 SDK 生命周期包装代码（参见下面的特定语言部分）
3. 配置 .actor/input_schema.json
4. 使用 apify run --input '{"key": "value"}' 进行测试
5. 使用 apify push 进行部署

何时使用此技能

• 将现有项目转换为在 Apify 平台上运行
• 向项目添加 Apify SDK 集成
• 将 CLI 工具或脚本包装为 Actor
• 将 Crawlee 项目迁移到 Apify

前提条件

验证 apify CLI 是否已安装：

apify --help

如果未安装：

curl -fsSL https://apify.com/install-cli.sh | bash

# 或者 (Mac): brew install apify-cli
# 或者 (Windows): irm https://apify.com/install-cli.ps1 | iex
# 或者: npm install -g apify-cli

验证 CLI 是否已登录：

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

如果未登录，检查 APIFY_TOKEN 环境变量是否已定义。如果未定义，请让用户在 https://console.apify.com/settings/integrations 生成一个，然后：

apify login -t $APIFY_TOKEN

Actor 化检查清单

复制此清单以跟踪进度：

• 步骤 1：分析项目（语言、入口点、输入、输出）
• 步骤 2：运行 apify init 创建 Actor 结构
• 步骤 3：应用特定语言的 SDK 集成
• 步骤 4：配置 .actor/input_schema.json
• 步骤 5：配置 .actor/output_schema.json（如适用）
• 步骤 6：更新 .actor/actor.json 元数据
• 步骤 7：使用 apify run 进行本地测试
• 步骤 8：使用 apify push 进行部署

步骤 1：分析项目

在进行更改之前，了解项目：

1. 识别语言 – JavaScript/TypeScript, Python 或其他
2. 找到入口点 – 启动执行的主文件
3. 识别输入 – 命令行参数、环境变量、配置文件
4. 识别输出 – 文件、控制台输出、API 响应
5. 检查状态 – 是否需要在运行之间持久化数据？

步骤 2：初始化 Actor 结构

在项目根目录运行：

apify init

这将创建：

• .actor/actor.json – Actor 配置和元数据
• .actor/input_schema.json – Apify Console 的输入定义
• Dockerfile（如果不存在） – 容器镜像定义

步骤 3：应用特定语言的更改

根据项目的语言选择：

• JavaScript/TypeScript: 参见 js-ts-actorization.md
• Python: 参见 python-actorization.md
• 其他语言（基于 CLI）: 参见 cli-actorization.md

快速参考

步骤 4-6：配置模式

有关以下内容的详细配置，请参阅 schemas-and-output.md：

• 输入模式 (.actor/input_schema.json)
• 输出模式 (.actor/output_schema.json)
• Actor 配置 (.actor/actor.json)
• 状态管理（请求队列、键值存储）

使用 @apify/json_schemas npm 包验证模式。

步骤 7：本地测试

使用内联输入运行 actor（适用于 JS/TS 和 Python actors）：

apify run --input '{"startUrl": "https://example.com", "maxItems": 10}'

或使用输入文件：

apify run --input-file ./test-input.json

重要提示： 始终使用 apify run，而不是 npm start 或 python main.py。CLI 会设置正确的环境和存储。

步骤 8：部署

apify push

这会将您的 actor 上传到 Apify 平台并构建它。

货币化（可选）

部署后，您可以在 Apify Store 中为您的 actor 启用货币化。推荐的模式是 按事件付费 (PPE)：

• 每个抓取的结果/项目
• 每个处理的页面
• 每次发出的 API 调用

在 Apify Console 中的 Actor > 货币化 下配置 PPE。在您的代码中使用 await Actor.charge('result') 对事件进行计费。

其他选项：租用（月度订阅）或 免费（开源）。

部署前检查清单

• .actor/actor.json 存在且名称和描述正确
• .actor/actor.json 通过 @apify/json_schemas (actor.schema.json) 验证
• .actor/input_schema.json 定义了所有必需的输入
• .actor/input_schema.json 通过 @apify/json_schemas (input.schema.json) 验证
• .actor/output_schema.json 定义了输出结构（如适用）
• .actor/output_schema.json 通过 @apify/json_schemas (output.schema.json) 验证
• Dockerfile 存在且构建成功
• Actor.init() / Actor.exit() 包装了主代码 (JS/TS)
• async with Actor: 包装了主代码 (Python)
• 通过 Actor.getInput() / Actor.get_input() 读取输入
• 输出使用 Actor.pushData() 或键值存储
• apify run 使用测试输入成功执行
• 在 actor.json 的 meta 部分中设置了 generatedBy

Apify MCP 工具

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

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

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

资源

• Actor 化学堂 – 综合指南
• 适用于 JavaScript 的 Apify SDK – 完整的 SDK 参考
• 适用于 Python 的 Apify SDK – 完整的 SDK 参考
• Apify CLI 参考 – CLI 命令
• Actor 规范 – 完整规范