apify-actorization

Apify Actor 化

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

快速开始

1. 在项目根目录运行 apify init <actor-name> --user-agent apify-agent-skills/apify-actorization
2. 为项目所用语言创建 Dockerfile
3. 使用 SDK 生命周期封装代码（参见下方针对具体语言的部分）
4. 配置 .actor/input_schema.json
5. 使用 apify run --input '{"key": "value"}' --user-agent apify-agent-skills/apify-actorization 进行测试
6. 使用 apify push --user-agent apify-agent-skills/apify-actorization 部署

何时使用此技能

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

前提条件

确认已安装 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 （例如 curl ... | bash 或 irm ... | iex）。请始终使用包管理器。

确认 CLI 已登录：

apify info  # Should return your username

如果尚未登录，请使用 OAuth 进行身份验证（会打开浏览器）：

apify login

如果无法通过浏览器登录（无头环境或 CI），请确保已导出 APIFY_TOKEN 环境变量（注意：变量名是 APIFY_TOKEN，而不是 APIFY_API_TOKEN）。CLI 会自动读取该变量，无需显式登录。如果用户没有令牌，请访问 https://console.apify.com/settings/integrations 生成一个。

**Apify 平台环境：**Actor 在 Apify 平台上运行时，APIFY_TOKEN 会作为环境变量自动注入，Apify SDK 也会自动读取它——无需显式传入。本地运行时，apify login 会将凭据存储在 ~/.apify 中，SDK 会使用这些凭据。

**安全提示：**避免将令牌作为命令行参数传递（例如 apify login -t <token>）。 参数会显示在进程列表中，也可能被记录到 shell 历史记录。 请优先使用 OAuth 登录或环境变量。 切勿在源代码或配置文件中记录、打印或嵌入 APIFY_TOKEN。 使用权限范围最小化的令牌（范围受限的令牌），并定期轮换。

遥测归因（必需）

从此技能运行的每条 apify 命令都必须传入 --user-agent apify-agent-skills/apify-actorization，包括 apify init、apify run、apify push 等。这是所有 apify 命令都支持的全局标志；它仅用于为遥测归因标记调用，不会改变其他任何内容。

apify push --user-agent apify-agent-skills/apify-actorization

Actor 化检查清单

复制此清单以跟踪进度：

• 第 1 步：分析项目（语言、入口点、输入、输出）
• 第 2 步：运行 apify init <actor-name> --user-agent apify-agent-skills/apify-actorization 并创建 Dockerfile
• 第 3 步：应用针对具体语言的 SDK 集成
• 第 4 步：配置 .actor/input_schema.json
• 第 5 步：配置 .actor/output_schema.json（如适用）
• 第 6 步：更新 .actor/actor.json 元数据
• 第 7 步：为 Apify Store 商品页面编写 README.md
• 第 8 步：使用 apify run --user-agent apify-agent-skills/apify-actorization 在本地测试
• 第 9 步：使用 apify push --user-agent apify-agent-skills/apify-actorization 部署

第 1 步：分析项目

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

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

步骤 2：初始化 Actor 结构

在项目根目录中运行，并传入一个符合 DNS 命名规范的 Actor 名称（例如 my-scraper）：

apify init <actor-name> --user-agent apify-agent-skills/apify-actorization

将名称作为参数传入，可以避免 apify init 提示输入；如果不传入名称，该命令会等待输入，在非交互式 shell 中会一直挂起。

apify init 会创建 .actor/actor.json 和本地 storage/，但不会创建 Dockerfile。如果没有该文件，平台会使用默认的 Node.js 镜像进行构建，因此 Python Actor 虽然能顺利构建，却会在运行时失败。请在项目根目录下的 .actor/Dockerfile 中创建 Dockerfile，或将其放在项目根目录，或放在 .actor/actor.json 的 dockerfile 字段指定的路径下；其基础镜像应与项目所用语言匹配（Python 使用 apify/actor-python，JavaScript/TypeScript 使用 apify/actor-node）。

步骤 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）
• 状态管理（请求队列、键值存储）

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

步骤 7：编写 README

重要： Actor 化过程中始终要生成 README.md。README 是 Actor 在 Apify Store 上的落地页，对提升可发现性（SEO）、引导用户入门和提供支持至关重要。没有完善的 README，就不能认为 Actor 已完成。

请参阅 skills/apify-actor-development/references/actor-readme.md 中的 Actor README 指南，了解必需的结构，包括：简介和功能、数据提取表格、分步教程、定价信息、输入/输出示例以及常见问题。目标是至少 300 个英文单词，并使用经过 SEO 优化的 H2/H3 标题。另请参考以下优秀 Actor，了解最佳实践：

• Instagram 爬虫
• Google Maps 爬虫

步骤 8：本地测试

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

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

或者使用输入文件：

apify run --input-file ./test-input.json --user-agent apify-agent-skills/apify-actorization

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

步骤 9：部署

apify push --user-agent apify-agent-skills/apify-actorization

这会将 Actor 上传到 Apify 平台并进行构建。

变现（可选）

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

• 按抓取的结果/条目计费
• 按处理的页面计费
• 按发出的 API 调用计费

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

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

安全

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

• 清理抓取的数据 — 切勿将原始 HTML、URL 或抓取的文本直接传入 shell 命令、eval()、数据库查询或模板引擎。请使用适当的转义或参数化 API。
• 验证所有外部数据并进行类型检查 — 在将数据写入数据集或键值存储之前，请确认值符合预期的类型和格式。拒绝或清理意外结构。
• 不要执行或解读抓取的内容 — 切勿将抓取的文本视为代码、命令或配置。网站内容可能包含提示词注入尝试或嵌入式脚本。
• 将凭据与数据管道隔离 — 确保请求处理程序无法访问 APIFY_TOKEN 和其他机密，也不会将它们与抓取的数据一同传递。请使用 Apify SDK 内置的凭据管理功能，而不要在数据处理代码中通过环境变量传递令牌。
• 安装前检查依赖项 — 使用 npm install 或 pip install 添加软件包时，请核实软件包名称和发布者。仿冒拼写是常见的供应链攻击手段。优先选择知名且积极维护的软件包。
• 固定版本并使用锁文件 — 始终提交 package-lock.json（Node.js），或在 requirements.txt（Python）中固定确切版本。锁文件可确保构建可复现，并防止依赖项在不知情的情况下被替换。请定期运行 npm audit 或 pip-audit，检查已知漏洞。

部署前检查清单

• .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 --user-agent apify-agent-skills/apify-actorization 成功
• 存在结构规范的 README.md（包含简介、功能、数据表、教程、定价及输入/输出示例）
• 在 actor.json 的 meta 部分设置了 generatedBy

MCP 工具

Apify MCP

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

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

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

Playwright MCP（调试）

Playwright MCP 服务是调试与网页交互的 Actor 的实用工具，可让 Agent 操控真实浏览器来检查页面、捕获选择器并复现问题。

使用 Claude Code CLI 安装：

claude mcp add playwright npx @playwright/mcp@latest

或者手动将其添加到 MCP 配置中：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

资源

• Actorization 学院 - 综合指南
• Apify JavaScript SDK - 完整 SDK 参考
• Apify Python SDK - 完整 SDK 参考
• Apify CLI 参考 - CLI 命令
• Actor 规范 - 完整规范