apify-actorization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apify Actorization

Apify项目Actor化

Actorization converts existing software into reusable serverless applications compatible with the Apify platform. Actors are programs packaged as Docker images that accept well-defined JSON input, perform an action, and optionally produce structured JSON output.

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

Quick Start

快速开始

Run
```
apify init
```
in project root
Wrap code with SDK lifecycle (see language-specific section below)
Configure
```
.actor/input_schema.json
```
Test with
```
apify run --input '{"key": "value"}'
```
Deploy with
```
apify push
```

在项目根目录运行
```
apify init
```
使用SDK生命周期包装代码（见下方语言特定章节）
配置
```
.actor/input_schema.json
```
使用
```
apify run --input '{"key": "value"}'
```
进行测试
使用
```
apify push
```
部署

When to Use This Skill

适用场景

Converting an existing project to run on Apify platform
Adding Apify SDK integration to a project
Wrapping a CLI tool or script as an Actor
Migrating a Crawlee project to Apify

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

Prerequisites

前置条件

Verify

apify

CLI is installed:

bash

apify --help

If not installed:

bash

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

验证

apify

CLI已安装：

bash

apify --help

若未安装：

bash

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

Or (Mac): brew install apify-cli

或（Mac）：brew install apify-cli

Or (Windows): irm https://apify.com/install-cli.ps1 | iex

或（Windows）：irm https://apify.com/install-cli.ps1 | iex

Or: npm install -g apify-cli

或：npm install -g apify-cli


Verify CLI is logged in:

```bash
apify info  # Should return your username

If not logged in, check if

APIFY_TOKEN

environment variable is defined. If not, ask the user to generate one at https://console.apify.com/settings/integrations, then:

bash

apify login -t $APIFY_TOKEN


验证CLI已登录：

```bash
apify info  # 应返回你的用户名

若未登录，检查是否定义了

APIFY_TOKEN

环境变量。若未定义，请让用户在https://console.apify.com/settings/integrations生成该令牌，然后执行：

bash

apify login -t $APIFY_TOKEN

Actorization Checklist

Actor化检查清单

Copy this checklist to track progress:

Step 1: Analyze project (language, entry point, inputs, outputs)
Step 2: Run
```
apify init
```
to create Actor structure
Step 3: Apply language-specific SDK integration
Step 4: Configure
```
.actor/input_schema.json
```
Step 5: Configure
```
.actor/output_schema.json
```
(if applicable)
Step 6: Update
```
.actor/actor.json
```
metadata
Step 7: Test locally with
```
apify run
```
Step 8: Deploy with
```
apify push
```

复制此清单以跟踪进度：

步骤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
```
部署

Step 1: Analyze the Project

步骤1：分析项目

Before making changes, understand the project:

Identify the language - JavaScript/TypeScript, Python, or other
Find the entry point - The main file that starts execution
Identify inputs - Command-line arguments, environment variables, config files
Identify outputs - Files, console output, API responses
Check for state - Does it need to persist data between runs?

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

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

Step 2: Initialize Actor Structure

步骤2：初始化Actor结构

Run in the project root:

bash

apify init

This creates:

```
.actor/actor.json
```
- Actor configuration and metadata
```
.actor/input_schema.json
```
- Input definition for the Apify Console
```
Dockerfile
```
(if not present) - Container image definition

在项目根目录运行：

bash

apify init

此命令将创建：

```
.actor/actor.json
```
- Actor配置和元数据
```
.actor/input_schema.json
```
- Apify控制台的输入定义
```
Dockerfile
```
（若不存在）- 容器镜像定义

Step 3: Apply Language-Specific Changes

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

Choose based on your project's language:

JavaScript/TypeScript: See js-ts-actorization.md
Python: See python-actorization.md
Other Languages (CLI-based): See cli-actorization.md

根据项目语言选择对应方式：

JavaScript/TypeScript：查看js-ts-actorization.md
Python：查看python-actorization.md
其他语言（基于CLI）：查看cli-actorization.md

Quick Reference

快速参考

Language	Install	Wrap Code
JS/TS	`npm install apify`	`await Actor.init()` ... `await Actor.exit()`
Python	`pip install apify`	`async with Actor:`
Other	Use CLI in wrapper script	`apify actor:get-input` / `apify actor:push-data`

语言	安装方式	代码包装方式
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`

Steps 4-6: Configure Schemas

步骤4-6：配置Schema

See schemas-and-output.md for detailed configuration of:

Input schema (
```
.actor/input_schema.json
```
)
Output schema (
```
.actor/output_schema.json
```
)
Actor configuration (
```
.actor/actor.json
```
)
State management (request queues, key-value stores)

Validate schemas against

@apify/json_schemas

npm package.

查看schemas-and-output.md以获取以下内容的详细配置：

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

使用

@apify/json_schemas

npm包验证Schema。

Step 7: Test Locally

步骤7：本地测试

Run the actor with inline input (for JS/TS and Python actors):

bash

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

Or use an input file:

bash

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

Important: Always use

apify run

, not

npm start

python main.py

. The CLI sets up the proper environment and storage.

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

bash

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

或使用输入文件：

bash

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

重要提示：请始终使用

apify run

，而非

npm start

或

python main.py

。CLI会设置正确的环境和存储。

Step 8: Deploy

步骤8：部署

bash

apify push

This uploads and builds your actor on the Apify platform.

bash

apify push

此命令将你的Actor上传并构建到Apify平台。

Monetization (Optional)

变现（可选）

After deploying, you can monetize your actor in the Apify Store. The recommended model is Pay Per Event (PPE):

Per result/item scraped
Per page processed
Per API call made

Configure PPE in the Apify Console under Actor > Monetization. Charge for events in your code with

await Actor.charge('result')

Other options: Rental (monthly subscription) or Free (open source).

部署完成后，你可以在Apify商店中将你的Actor变现。推荐使用**按事件付费（PPE）**模式：

按抓取的结果/条目付费
按处理的页面数量付费
按调用的API次数付费

在Apify控制台的Actor > 变现页面配置PPE模式。在代码中通过

await Actor.charge('result')

来记录付费事件。

其他可选模式：租赁制（月度订阅）或免费（开源）。

Pre-Deployment Checklist

部署前检查清单

```
.actor/actor.json
```
exists with correct name and description

.actor/actor.json

validates against

@apify/json_schemas

(

actor.schema.json

)

```
.actor/input_schema.json
```
defines all required inputs

.actor/input_schema.json

validates against

@apify/json_schemas

(

input.schema.json

)

```
.actor/output_schema.json
```
defines output structure (if applicable)

.actor/output_schema.json

validates against

@apify/json_schemas

(

output.schema.json

)

```
Dockerfile
```
is present and builds successfully
```
Actor.init()
```
/
```
Actor.exit()
```
wraps main code (JS/TS)
```
async with Actor:
```
wraps main code (Python)
Inputs are read via
```
Actor.getInput()
```
/
```
Actor.get_input()
```
Outputs use
```
Actor.pushData()
```
or key-value store
```
apify run
```
executes successfully with test input
```
generatedBy
```
is set in actor.json meta section

存在
```
.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 Tools

Apify MCP工具

If MCP server is configured, use these tools for documentation:

```
search-apify-docs
```
- Search documentation
```
fetch-apify-docs
```
- Get full doc pages

Otherwise, the MCP Server url:

https://mcp.apify.com/?tools=docs

若已配置MCP服务器，可使用以下工具获取文档：

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

否则，MCP Server地址为：

https://mcp.apify.com/?tools=docs

。

Resources

资源

Actorization Academy - Comprehensive guide
Apify SDK for JavaScript - Full SDK reference
Apify SDK for Python - Full SDK reference
Apify CLI Reference - CLI commands
Actor Specification - Complete specification

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