Apify Actor化教程：将现有软件转换为无服务器应用 | 快速部署指南

apify-actorization by apify/agent-skills

2,400 周安装量

1,700 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/apify/agent-skills --skill apify-actorization

开发云服务开发运维

🇨🇳中文介绍

Apify Actor 化

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

快速开始

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

何时使用此技能

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

先决条件

验证 apify CLI 是否已安装：

apify --help

如果未安装：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 1：分析项目

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

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

步骤 2：初始化 Actor 结构

在项目根目录运行：

.actor/actor.json - Actor 配置和元数据
.actor/input_schema.json - Apify 控制台的输入定义
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)
状态管理（请求队列、键值存储）

根据 @apify/json_schemas npm 包验证模式。

步骤 7：本地测试

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

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

或使用输入文件：

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

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

这将在 Apify 平台上上传并构建您的 actor。

货币化（可选）

部署后，您可以在 Apify 商店中为您的 actor 实现货币化。推荐的模型是 按事件付费 (PPE) ：

按抓取的每个结果/项目
按处理的每个页面
按进行的每个 API 调用

在 Apify 控制台的 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 使用测试输入成功执行
generatedBy 已在 actor.json 的 meta 部分设置

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

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

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

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

🇺🇸English

Apify Actorization

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.

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

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

Prerequisites

Verify apify CLI is installed:

apify --help

If not installed:

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

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

Verify CLI is logged in:

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:

apify login -t $APIFY_TOKEN

Actorization Checklist

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

Step 1: Analyze the Project

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?

Step 2: Initialize Actor Structure

Run in the project root:

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

Step 3: Apply Language-Specific Changes

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

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`

Steps 4-6: Configure Schemas

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.

Step 7: Test Locally

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

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

Or use an input file:

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

Important: Always use apify run, not npm start or python main.py. The CLI sets up the proper environment and storage.

Step 8: Deploy

apify push

This uploads and builds your actor on the Apify platform.

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).

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 MCP Tools

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.

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

Weekly Installs

1.6K

Repository

apify/agent-skills

GitHub Stars

1.6K

First Seen

Jan 29, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykWarn

Installed on

opencode1.6K

codex1.5K

gemini-cli1.5K

github-copilot1.5K

cursor1.5K

kimi-cli1.4K

@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