apify-actorization

Apify Actor 化

Actor 化会将现有软件转换为与 Apify 平台兼容、可重复使用的无服务器应用程序。Actor 是打包为 Docker 镜像的程序，接受定义明确的 JSON 输入、执行操作，并可选择生成结构化 JSON 输出。

初始化、安装或部署前，请检查现有文件并保留其状态。确认目标账户/Actor、源代码许可证、要上传的文件/密钥、网络目标以及支出/收费限额。授权本地转换不代表授权上传到云端、发布到 Store 或进行货币化。请固定经过审核的 SDK/CLI/基础镜像版本，并根据该版本验证架构。

快速入门

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

如果尚未安装：

brew install apify-cli

# Or: npm install -g apify-cli
# Or install from an official release package that your OS package manager verifies

确认 CLI 已登录：

apify info  # Should return your username

如果尚未登录，请检查是否定义了 APIFY_TOKEN 环境变量。如果没有，请让用户前往 https://console.apify.com/settings/integrations 生成令牌，并将其添加到 shell 或密钥管理器中，避免将令牌原文写入命令历史，然后运行：

apify login

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

快速参考

语言	安装	封装代码
JS/TS	npm install apify	await Actor.init() ... await Actor.exit()
Python	pip install apify	async with Actor:
其他	在封装脚本中使用 CLI	apify actor:get-input / apify actor:push-data

步骤 4–6：配置架构

有关以下项目的详细配置，请参见 schemas-and-output.md：

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

请根据 npm 软件包 @apify/json_schemas 验证架构。

第 7 步：本地测试

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

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

或者使用输入文件：

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

使用所选语言文档中介绍的本地 CLI 流程；检查存储清除默认设置，并保留无关的本地数据。直接通过 SDK/测试执行也可能合适。本地执行仍可能发起网络请求，或在配置后使用云存储；请使用合成测试数据和测试账号。

第 8 步：部署

apify push

这会在 Apify 平台上上传并构建你的 Actor。

变现（可选）

部署后，你可以在 Apify Store 中通过 Actor 变现。推荐的模式是 按事件付费（PPE）：

• 按抓取的结果/项目收费
• 按处理的页面收费
• 按发起的 API 调用收费

在 Apify Console 的 Actor > Monetization 下配置 PPE。在代码中使用 await Actor.charge('result') 对事件收费。

其他选项：其他当前受支持的 Store 模式，或免费执行。免费 Actor 并不自动意味着开源；许可证和源代码是否可用是两个独立的问题。

部署前检查清单

• .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 Server URL 为：https://mcp.apify.com/?tools=docs。

资源

• Actorization Academy - 综合指南
• Apify SDK for JavaScript - 完整 SDK 参考
• Apify SDK for Python - 完整 SDK 参考
• Apify CLI Reference - CLI 命令
• Actor Specification - 完整规范

限制

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