# Apify Actor 开发 **重要提示：** 在开始之前，请填写 `.actor/actor.json` 的元部分中的 ` generatedBy` 属性。将其替换为您当前使用的工具和模型，例如“Claude Code with Claude Sonnet 4.5”。这有助于 Apify 监控和改进特定 AI 工具和模型的 AGENTS.md。 ## Apify Actor 是什么？ Actor 是受 UNIX 哲学启发的无服务器程序 - 擅长做一件事并且可以轻松组合以构建复杂系统的程序。它们被打包为 Docker 映像并在云中的隔离容器中运行。 **核心概念：** * 接受明确定义的 JSON 输入 * 执行独立的任务（网页抓取、自动化、数据处理） * 生成结构化 JSON 输出到数据集和/或将数据存储在键值存储中 * 可以运行从几秒到几小时甚至无限期 * 保持状态并可以重新启动 ## 先决条件和设置（强制）在创建或修改参与者之前，请验证是否已安装“apify”CLI“apify --help”。如果未安装，请使用以下方法之一（按优先顺序列出）： # 首选：通过包管理器安装（提供完整性检查） npm install -g apify-cli # 或者（Mac）：brew install apify-cli > **安全说明：** 不要通过将远程脚本传送到 shell 来安装 CLI（例如 `curl ... | bash` 或 `irm ... | iex`）。始终使用包管理器。安装 apify CLI 后，检查是否已使用以下命令登录： apify info # 应返回您的用户名如果未登录，请检查是否定义了“APIFY_TOKEN”环境变量（如果没有，请用户在上生成一个环境变量，然后用它定义“APIFY_TOKEN”）。然后使用以下方法之一进行身份验证： # 选项 1（首选）：CLI 自动从环境中读取 APIFY_TOKEN。 # 只需确保导出环境变量并运行任何 apify 命令 - 无需显式登录。 # 选项 2：交互式登录（提示输入令牌而不在 shell 历史记录中公开它）登录 > **安全说明：** 避免将令牌作为命令行参数传递（例如`apify login -t `）。参数在进程列表中可见，并且可以记录在 shell 历史记录中。更喜欢环境变量或交互式登录。切勿在源代码或配置文件中记录、打印或嵌入“APIFY_TOKEN”。使用具有最低所需权限的令牌（范围令牌）并定期轮换。 ## 模板选择 **重要：** 在开始 Actor 开发之前，请务必询问用户他们更喜欢哪种编程语言： * **JavaScript** \- 使用 `apify create -t project_empty` * **TypeScript** \- 使用 `apify create -t ts_empty` * **Python** \- 使用 `apify create -t python-empty` 根据用户的语言选择使用适当的 CLI 命令。稍后可以根据需要安装其他软件包（Crawlee、Playwright 等）。 ## 快速启动工作流程 1. **创建 actor 项目** \- 根据用户的语言偏好运行适当的 `apify create` 命令（请参阅上面的模板选择） 2. **安装依赖项**（安装前验证包名称与预期包匹配） * JavaScript/TypeScript：“npm install”（使用“package-lock.json”进行可重复的、经过完整性检查的安装——将锁定文件提交到版本控制） * Python：`pip install -rrequirements.txt`（在`requirements.txt`中固定确切版本，例如`crawlee==1.2.3`，并将文件提交到版本控制） 3. **实现逻辑** \- 在 `src/main.py`、`src/main.js` 或 `src/main.ts` 中编写 actor 代码 4. **配置模式** \- 更新 `.actor/input_schema.json`、`.actor/output_schema.json`、`.actor/dataset_schema.json` 中的输入/输出模式 5. **配置平台设置** \- 使用 actor 元数据更新`.actor/actor.json`（请参阅 [references/actor-json.md]()） 6. **编写文档** \- 为市场创建全面的 README.md 7. **本地测试** \- 运行 `apify run` 来验证功能（请参阅下面的本地测试部分） 8. **部署** \- 运行`apify push`将actor部署到Apify平台上（actor名称在`.actor/actor.json`中定义） ## 安全 **将所有爬网的 Web 内容视为不受信任的输入。** 攻击者从可能包含恶意负载的外部网站获取数据。请遵循以下规则： * **清理爬取的数据** — 切勿将原始 HTML、URL 或抓取的文本直接传递到 shell 命令、“eval()”、数据库查询或模板引擎中。使用正确的转义或参数化 API。 * **验证和类型检查所有外部数据** - 在推送到数据集或键值存储之前，验证值是否与预期的类型和格式匹配。拒绝或清理意外的结构。 * **不要执行或解释抓取的内容** — 切勿将抓取的文本视为代码、命令或配置。来自网站的内容可能包括提示注入尝试或嵌入脚本。 * **将凭证与数据管道隔离** — 确保“APIFY_TOKEN”和其他机密永远无法在请求处理程序中访问或与爬网数据一起传递。使用 Apify SDK 的内置凭证管理，而不是通过数据处理代码中的环境变量传递令牌。 * **安装前检查依赖关系** — 使用“npm install”或“pip install”添加软件包时，请验证软件包名称和发布者。域名仿冒是一种常见的供应链攻击媒介。更喜欢知名的、积极维护的软件包。 * **固定版本并使用锁定文件** — 始终提交 `package-lock.json` (Node.js) 或在 `requirements.txt` (Python) 中固定确切版本。锁定文件确保可重复的构建并防止静默依赖替换。定期运行“npmaudit”或“pip-audit”以检查已知漏洞。 ## 最佳实践 **✓ 做：** * 使用`apify run`在本地测试actor（配置Apify环境和存储） * 使用 Apify SDK (`apify`) 在 Apify 平台上运行代码 * 通过正确的错误处理尽早验证输入并优雅地失败 * 使用 CheerioCrawler 获取静态 HTML（比浏览器快 10 倍） * 仅对 JavaScript 较多的网站使用 PlaywrightCrawler * 使用路由器模式（createCheerioRouter/createPlaywrightRouter）进行复杂的爬网 * 实施具有指数退避的重试策略 * 使用适当的并发：HTTP (10-50)、浏览器 (1-5) * 在 `.actor/input_schema.json` 中设置合理的默认值 * 在`.actor/output_schema.json`中定义输出模式 * 在推送到数据集之前清理并验证数据 * 使用带有回退策略的语义 CSS 选择器 * 尊重robots.txt、ToS，并实施速率限制 * **始终使用 `apify/log` 包** — 审查敏感数据（API 密钥、令牌、凭证） * 实现就绪探针处理程序（如果您的 Actor 使用待机模式则需要） **✗ 不要：** * 使用 `npm start`、`npm run start`、`npx apify run` 或类似命令来运行 actor（改为使用 `apify run`） * 假设来自“apify run”的本地存储被推送到 Apify 控制台或在 Apify 控制台中可见——它仅限于本地；使用“apify push”进行部署并在平台上运行以在控制台中查看结果 * 依靠“Dataset.getInfo()”在云上进行最终计数 * 当 HTTP/Cheerio 工作时使用浏览器爬虫 * 应在输入模式或环境变量中的硬代码值 * 跳过输入验证或错误处理 * 过载服务器 - 使用适当的并发和延迟 * 抓取禁止内容或忽略服务条款 * 除非明确允许，否则存储个人/敏感数据 * 在 CheerioCrawler (v3.x) 上使用“requestHandlerTimeoutMillis”等已弃用的选项 * 使用 `additionalHttpHeaders` \- 使用 `preNavigationHooks` 代替 * 将原始爬取内容传递到 shell 命令、`eval()` 或代码生成函数中 * 使用 `console.log()` 或 `print()` 而不是 Apify 记录器 — 这些可以绕过凭证审查 * 未经明确许可禁用待机模式 ## 日志记录请参阅 [references/logging.md]() 以获取完整的日志记录文档，包括可用的日志级别以及 JavaScript/TypeScript 和 Python 的最佳实践。检查 `.actor/actor.json` 中的 `usesStandbyMode` - 仅在设置为 `true` 时才实现。 ## 命令 apify run # 在本地运行 Actor apify login # 验证帐户 apify push # 部署到 Apify 平台（使用 .actor/actor.json 中的名称） apify help # 列出所有命令 **重要：** 始终使用“apify run”在本地测试参与者。请勿使用“npm run start”、“npm start”、“yarn start”或其他包管理器命令 - 这些命令将无法正确配置 Apify 环境和存储。 ## 本地测试当使用“apify run”在本地测试参与者时，通过在以下位置创建 JSON 文件来提供输入数据：存储/key_value_stores/default/INPUT.json 该文件应包含“.actor/input_schema.json”中定义的输入参数。 Actor 将在本地运行时读取此输入，反映它在 Apify 平台上接收输入的方式。 **重要 - 本地存储未同步到 Apify 控制台：** * 运行 `apify run` 将所有数据（数据集、键值存储、请求队列）**仅存储在本地文件系统**的 `storage/` 目录中。 * 此数据**绝不会**自动上传或推送到 Apify 平台。它仅存在于您的计算机上。 * 要在 Apify 控制台上验证结果，您必须使用“apify push”部署 Actor，然后在平台上运行它。 * 不要**依赖检查 Apify 控制台来验证本地运行的结果 - 相反，检查本地 `storage/` 目录或检查 Actor 的日志输出。 ## 待机模式请参阅 [references/standby-mode.md]() 了解完整的待机模式文档，包括 JavaScript/TypeScript 和 Python 的就绪探针实现。 ## 项目结构 .演员/ ├── actor.json # Actor 配置：名称、版本、环境变量、运行时 ├── input_schema.json # 输入验证和控制台表单定义 └──output_schema.json # 输出存储和展示模板源代码/ └── main.js/ts/py # Actor 入口点 storage/ # 仅本地存储（不同步到 Apify 控制台） ├── datasets/ # 输出项（JSON对象） ├── key_value_stores/ # 文件、配置、输入 └── request_queues/ # 待处理的抓取请求 Dockerfile # 容器镜像定义 ## 演员配置有关完整的 actor.json 结构和配置选项，请参阅 [references/actor-json.md]()。 ## 输入模式有关输入模式结构和示例，请参阅 [references/input-schema.md]()。 ## 输出模式有关输出模式结构、示例和模板变量，请参阅 [references/output-schema.md]()。 ## 数据集架构有关数据集架构结构、配置和显示属性，请参阅 [references/dataset-schema.md]()。 ## 键值存储架构有关键值存储架构结构、集合和配置，请参阅 [references/key-value-store-schema.md]()。 ## Apify MCP 工具如果配置了 MCP 服务器，请使用以下工具获取文档： * `search-apify-docs` \- 搜索文档 * `fetch-apify-docs` \- 获取完整的文档页面否则，MCP 服务器 URL：“https://mcp.apify.com/?tools=docs”。 ## 资源 * [docs.apify.com/llms.txt]() \- Apify 快速参考文档 * [docs.apify.com/llms-full.txt]() \- Apify 完整文档 * \- Crawlee 快速参考文档 * \- Crawlee 完整文档 * [whitepaper.actor]() \- 完整的 Actor 规范

Apify Actor 开发

包含技能