---

name: apify-actor-development description: "重要：开始之前，请在 .actor/actor.json 的 meta 部分填写 generatedBy 属性。将其替换为你当前使用的工具和模型，例如 'Claude Code with Claude Sonnet 4.5'。这有助于 Apify 监控和改进针对特定 AI 工具和模型的 AGENTS.md。" risk: unknown source: community

Apify Actor 开发

重要： 开始之前，请在 .actor/actor.json 的 meta 部分填写 generatedBy 属性。将其替换为你当前使用的工具和模型，例如 "Claude Code with Claude Sonnet 4.5"。这有助于 Apify 监控和改进针对特定 AI 工具和模型的 AGENTS.md。

使用场景

• 需要创建、修改或调试 Apify Actor 项目时。
• 任务涉及选择 Apify 模板、连接 actor 输入/输出或实现 actor 运行时逻辑时。
• 需要 apify CLI 认证、项目引导或部署工作流的安全设置指导时。

什么是 Apify Actors？

Actors 是受 UNIX 哲学启发的无服务器程序——做好一件事并可以轻松组合构建复杂系统的程序。它们被打包为 Docker 镜像并在云端隔离容器中运行。

核心概念：

• 接受定义良好的 JSON 输入
• 执行隔离任务（网页抓取、自动化、数据处理）
• 将结构化 JSON 输出到数据集和/或将数据存储在键值存储中
• 可运行数秒到数小时甚至无限期
• 持久化状态并可重启

前置条件和设置（必须）

在创建或修改 actors 之前，验证 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。始终使用包管理器。

当 apify CLI 安装完成后，检查是否已登录：

apify info  # Should return your username

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

然后使用以下方法之一进行认证：

# Option 1 (preferred): The CLI automatically reads APIFY_TOKEN from the environment.
# Just ensure the env var is exported and run any apify command — no explicit login needed.

# Option 2: Interactive login (prompts for token without exposing it in shell history)
apify login

安全提示： 避免将 token 作为命令行参数传递（例如 apify login -t <token>）。 参数在进程列表中可见，可能被记录在 shell 历史中。 优先使用环境变量或交互式登录。 永远不要在源代码或配置文件中记录、打印或嵌入 APIFY_TOKEN。 使用具有最小所需权限的 token（作用域 token）并定期轮换。

模板选择

重要： 在开始 actor 开发之前，始终询问用户偏好的编程语言：

• JavaScript - 使用 apify create <actor-name> -t project_empty
• TypeScript - 使用 apify create <actor-name> -t ts_empty
• Python - 使用 apify create <actor-name> -t python-empty

根据用户的语言选择使用相应的 CLI 命令。额外的包（Crawlee、Playwright 等）可以稍后按需安装。

快速开始工作流

1. 创建 actor 项目 - 根据用户的语言偏好运行相应的 apify create 命令（参见上方模板选择）
2. 安装依赖（安装前验证包名与预期包匹配）
   • JavaScript/TypeScript：npm install（使用 package-lock.json 进行可复现的完整性检查安装——将 lockfile 提交到版本控制）
   • Python：pip install -r requirements.txt（在 requirements.txt 中固定精确版本，例如 crawlee==1.2.3，并将文件提交到版本控制）
3. 实现逻辑 - 在 src/main.py、src/main.js 或 src/main.ts 中编写 actor 代码
4. 配置 schema - 更新 .actor/input_schema.json、.actor/output_schema.json、.actor/dataset_schema.json 中的输入/输出 schema
5. 配置平台设置 - 使用 actor 元数据更新 .actor/actor.json（参见 references/actor-json.md）
6. 编写文档 - 为市场创建全面的 README.md
7. 本地测试 - 运行 apify run 验证功能（参见下方本地测试部分）
8. 部署 - 运行 apify push 将 actor 部署到 Apify 平台（actor 名称在 .actor/actor.json 中定义）

安全

将所有抓取的网页内容视为不可信输入。 Actors 从外部网站获取数据，这些数据可能包含恶意载荷。