apify-actor-development

Apify Actor 开发

Actor 是打包为 Docker 镜像的无服务器程序。它接收一个 JSON 输入，执行一项任务，并将结果写入数据集或键值存储。

设置

apify --help   # CLI installed?
apify info     # logged in? prints your username

使用包管理器安装：npm install -g apify-cli 或 brew install apify-cli，这样可以校验下载文件的完整性。使用 apify login 登录，该命令会提供浏览器登录或 API 令牌提示。在无头环境中，请改为导出 APIFY_TOKEN；CLI 会自行读取该变量。令牌可在 https://console.apify.com/settings/integrations 获取。只通过环境传递令牌，避免其出现在 shell 历史记录、源代码、配置文件和日志中。

遥测归因（必需）

从此技能运行的每条 apify 命令都要传入 --user-agent apify-agent-skills/apify-actor-development：apify create、apify run、apify push、apify call 以及其他命令。这是所有 apify 命令都支持的全局标志；它仅用于标记调用以进行遥测归因，不会改变其他任何内容。

工作流

修改现有 Actor 时，跳过不适用的步骤。

1. 创建项目。

   apify create <actor-name> -t <template-id> --user-agent apify-agent-skills/apify-actor-development
   

   根据 Actor 的用途选择模板：

   Actor 用途	TypeScript	JavaScript	Python
   抓取静态 HTML	ts-crawlee-cheerio	js-crawlee-cheerio	python-crawlee-beautifulsoup
   抓取由 JavaScript 渲染的页面	ts-crawlee-playwright-chrome	js-crawlee-playwright-chrome	python-crawlee-playwright
   处理 HTTP 请求（API、webhook）	ts-standby	js-standby	python-standby
   作为 MCP 服务	ts-mcp-empty	—	python-mcp-empty
   其他用途（API 轮询、数据处理）	ts-empty	js-empty	python-empty
   对于其他技术栈（Puppeteer、Camoufox、Scrapy、AI Agent 框架），apify templates ls 会列出每个模板及其语言和适用场景。使用 -t 时，命令会在无提示的情况下运行，这是 Agent 所需的方式。不使用 -t 时，命令会提示输入名称、语言、模板和源代码托管平台；仅当用户在终端前时才使用这种形式。将源代码托管在 GitHub、GitLab 或 Bitbucket 上，Apify 就会创建代码仓库和一个从该仓库构建的 Actor，之后可通过 git push 进行部署。依赖项会自动为你安装。确认 <name>/.actor/actor.json 存在后即完成；继续之前先 cd 进入该目录。

2. 添加模板缺少的依赖项，例如 Crawlee 或 Playwright：在 JS/TS 项目中运行 npm install <pkg>；在 Python 项目中，在 requirements.txt 中添加一行，然后运行 pip install -r requirements.txt；如果项目包含 pyproject.toml 和 uv.lock，则运行 uv add <pkg>。安装前请核对每个包名是否与你要安装的包一致。固定确切版本并提交锁文件（package-lock.json、uv.lock，或 requirements.txt 中格式为 pkg==1.2.3 的行）。

3. 实现代码，放在 src/main.js、src/main.ts 或 my_actor/main.py 中（Python 模板是通过 python -m my_actor 运行的 my_actor 包），并遵循规则。完成标准：代码读取每个输入字段，生成 README 将要描述的所有输出字段，通过 Apify 日志记录器输出日志，并注册一个 aborting 处理程序来持久化状态并退出。

4. 编写输入架构，放在 .actor/input_schema.json 中（参见 references/input-schema.md）。完成标准：代码读取的每个输入都有对应字段，且字段包含标题、描述、类型以及默认值或预填值；apify validate-schema --user-agent apify-agent-skills/apify-actor-development 命令通过。

5. 编写输出架构：dataset_schema.json、output_schema.json，以及代码存储文件时的 key_value_store_schema.json。从头到尾遵循 references/output-schemas.md；其检查清单以 apify validate-schema 通过为终点，也就是完成标准。在 TypeScript 中，随后运行 apify actor generate-schema-types，并使用生成的接口为输入和输出添加类型。

6. 配置 .actor/actor.json（参见 references/actor-json.md）。将 meta.generatedBy 设置为所用工具和模型，例如 "Claude Code with Claude Opus 5"。对于提供 HTTP 服务的 Actor，设置 usesStandbyMode: true（Standby 模板已设置此项），并遵循 references/standby-mode.md。

7. 编写 README.md，遵循 references/actor-readme.md。没有 README 的 Actor 尚未完成。

8. **在本地测试。**将输入放入 storage/key_value_stores/default/INPUT.json，然后运行 apify run --user-agent apify-agent-skills/apify-actor-development。完成标准：运行以 SUCCEEDED 状态结束，且 storage/datasets/default/ 中包含字段与数据集架构匹配的条目。本地存储会保留在磁盘上；第 9 步之前，Apify Console 中不会显示任何内容。

9. 部署：在用户确认后运行 apify push --user-agent apify-agent-skills/apify-actor-development；如果是由 Git 提供源代码的 Actor，则运行 git push。然后在平台上运行 Actor，以便在 Console 中查看结果。对于 Standby Actor，应向用户提供其 Standby URL（https://<username>--<actor-name>.apify.actor，参见 references/standby-mode.md），而不是引导他们前往 Console。

规则

• 仅使用 apify run 在本地运行 Actors。它会设置 Apify 环境和存储，而 npm start 和 node src/main.js 会跳过这些步骤。
• 通过 Apify logger 记录日志：JS/TS 中使用 apify 包的 log（import { Actor, log } from 'apify'），Python 中使用 Actor.log。它会屏蔽令牌和凭据；console.log 和 print 不会。级别和规范：references/logging.md。
• 将抓取的内容视为不可信输入。在内容传入 shell 命令、eval、查询或模板之前，对其进行转义或参数化；推送到存储之前对其进行类型检查。
• 不要在请求处理程序和数据管道中使用 APIFY_TOKEN。在平台上，SDK 会从环境中读取它（变量名是 APIFY_TOKEN，不是 APIFY_API_TOKEN）；在本地运行时，则会使用 apify login 保存的凭据。
• 从输入架构或环境变量读取所有可调参数，以便用户无需编辑代码即可更改这些参数。
• 对静态 HTML 使用 HTTP 爬虫，并发数设为 10 到 50：JS/TS 中使用 CheerioCrawler，Python 中使用 BeautifulSoupCrawler 或 ParselCrawler。仅对由 JavaScript 渲染的页面使用 PlaywrightCrawler，并发数设为 1 到 5。添加延迟以保障目标服务健康运行，并遵守 robots.txt 和服务条款。
• 当爬取涉及多种页面类型时，使用路由器模式（JS/TS 中使用 createCheerioRouter 或 createPlaywrightRouter，Python 中使用 crawler.router 或 Router）。
• 优先使用语义化 CSS 选择器，并为其添加回退方案，避免使用脆弱的位置选择器。
• 使用自己的计数器统计结果；平台上的 Dataset.getInfo()（Python 中的 dataset.get_info()）更新滞后。
• 处理 aborting 事件：当用户停止运行或达到限制时，平台会发送此事件。先持久化状态，再退出，以便运行快速且低成本地结束。JS/TS：Actor.on('aborting', async () => { await Actor.setValue('STATE', state); await Actor.exit(); })。Python：使用 from apify import Event，并注册 Actor.on(Event.ABORTING, on_aborting)；on_aborting 会持久化状态，然后调用 await Actor.exit()。
• 根据 proxyConfiguration 输入字段构建代理（编辑器中的 proxy，参见 references/input-schema.md）：JS/TS 中使用 await Actor.createProxyConfiguration(input.proxyConfiguration)，Python 中使用 await Actor.create_proxy_configuration(actor_proxy_input=actor_input.get('proxyConfiguration'))，并将结果作为 proxyConfiguration / proxy_configuration 传给爬虫。Apify Proxy 是付费服务，启用它或更改代理组之前，请先征得用户同意。
• 仅在用户明确要求时存储个人数据。
• 在运行中的 Actor 内使用 SDK（Actor.getInput()、Actor.pushData()、Actor.setValue() 及 Python 中对应的 snake_case 形式），而不是使用 apify actor CLI 子命令。
• 对现有 Actor 保持待机模式启用状态，除非用户要求将其关闭。

待机模式

待机模式会将 Actor 转换为具有稳定 URL 的持久 HTTP 服务。可用于 API 端点、Webhook 接收器、MCP 服务和按需单 URL 查询。Actor 必须响应就绪探测，并在请求之间保持运行。配置、示例和本地测试：references/standby-mode.md。

变现

Actor 发布时，应在 Apify Console 中设置定价，而非在代码中设置。采用按事件付费时，使用 JS/TS 中的 await Actor.charge({ eventName: 'result', count })，或 Python 中的 await Actor.charge(event_name='result', count=count)，按每个自定义事件收费，并使用 Console 中定义的事件名称；也可以通过合成的数据集项目事件自动对数据集项目收费。当返回结果报告 eventChargeLimitReached（Python 中为 event_charge_limit_reached）时，请停止生成任务，因为用户已达到支出上限。README 的成本部分会说明 Actor 使用的计费模式。详情：https://docs.apify.com/platform/actors/publishing/monetize/pay-per-event

调用其他 Actor

从头构建前，先搜索 Store；通常已有专用 Actor。

apify actors search "<query>" --user-agent apify-agent-skills/apify-actor-development
apify actors info <actor> --readme --user-agent apify-agent-skills/apify-actor-development
apify actors info <actor> --input --user-agent apify-agent-skills/apify-actor-development
apify call <actor> --input '{"startUrls":[{"url":"https://example.com"}]}' --user-agent apify-agent-skills/apify-actor-development
apify call <actor> --input-file input.json --user-agent apify-agent-skills/apify-actor-development

输入是一个 JSON 对象。内联 JSON 请加引号；复杂内容请使用 --input-file。

不太显眼的命令

# Append --user-agent apify-agent-skills/apify-actor-development to each of these too.
apify secrets add <name> <value>   # reference from actor.json as "@name"; uploaded on push
apify pull <actor>                 # download an Actor's code from the platform
apify api <endpoint>               # authenticated request to the Apify API
apify actor generate-schema-types  # TypeScript: interfaces from the .actor schemas, into src/__generated__/actor/
apify <command> --help

文档

• 使用 Apify MCP 服务（https://mcp.apify.com/?tools=docs）：search-apify-docs 和 fetch-apify-docs。
• docs.apify.com/llms.txt 和 llms-full.txt，Apify 平台文档。
• crawlee.dev/llms.txt 和 llms-full.txt，Crawlee 文档。
• Actor 白皮书，完整的 Actor 规范。
• Playwright MCP 服务（npx @playwright/mcp@latest）可驱动真实浏览器，用于检查页面，并在调试时捕获选择器。