用 Apify CLI 开发、调试与部署 Apify…

在创建、修改或排查 Apify Actor（云端无服务器爬虫/自动化程序）时，按此流程完成从建项目到部署的全过程。

适用场景

解决思路

1. 先在 .actor/actor.json 的 meta 段填写 generatedBy 属性，替换为当前使用的工具和模型（如 "Claude Code with Claude Sonnet 4.5"）。
2. 确认已安装 apify CLI（运行 apify --help）；未安装时优先用包管理器安装：npm install -g apify-cli，Mac 上可用 brew install apify-cli；不要用 curl | bash 或 irm | iex 之类管道脚本安装。
3. 用 apify info 检查登录状态；未登录时用 apify login 走 OAuth 浏览器登录；无浏览器环境（headless/CI）时导出 APIFY_TOKEN 环境变量，CLI 会自动读取，无需显式登录；没有 token 就到 https://console.apify.com/settings/integrations 生成。
4. 避免把 token 作为命令行参数传入（如 apify login -t <token>），优先用环境变量或交互式登录；不要在源码或配置文件中记录、打印或内嵌 APIFY_TOKEN；使用最小权限的 scoped token 并定期轮换。
5. 在每一条 apify 命令后都追加 --user-agent apify-agent-skills/apify-actor-development 以做遥测归属（如 apify create、apify run、apify push、apify call 等）。
6. 开发前先询问用户偏好的编程语言，再选模板：JavaScript 用 apify create <actor-name> -t project_empty，TypeScript 用 -t ts_empty，Python 用 -t python-empty（均带 --user-agent 参数）。
7. 安装依赖：JS/TS 用 npm install（依赖 package-lock.json 保证可复现与完整性校验，并把 lockfile 提交到版本控制）；Python 用 pip install -r requirements.txt（在 requirements.txt 中锁定精确版本，如 crawlee==1.2.3，并提交该文件）。
8. 在 src/main.py、src/main.js 或 src/main.ts 中实现 Actor 逻辑。
9. 配置 schema：更新 .actor/input_schema.json、.actor/output_schema.json、.actor/dataset_schema.json。
10. 配置平台设置：更新 .actor/actor.json 中的 Actor 元数据。
11. 编写 README.md（必做，不是可选），作为 Apify Store 的落地页，参考 references/actor-readme.md 的结构与 SEO 最佳实践。
12. 本地测试：运行 apify run --user-agent apify-agent-skills/apify-actor-development 验证功能。
13. 部署：运行 apify push --user-agent apify-agent-skills/apify-actor-development 把 Actor 部署到 Apify 平台（Actor 名称在 .actor/actor.json 中定义）。
14. 本地测试时在 storage/key_value_stores/default/INPUT.json 写入输入 JSON，内容对应 .actor/input_schema.json 中定义的参数。
15. 把抓取到的网页内容一律当作不可信输入：不要将原始 HTML、URL 或抓取文本直接传入 shell 命令、eval()、数据库查询或模板引擎，使用正确的转义或参数化 API。
16. 对所有外部数据做校验和类型检查，推送到 dataset 或 key-value store 前确认值符合预期类型和格式，拒绝或清洗异常结构。
17. 不要把抓取内容当作代码、命令或配置执行或解释，防止 prompt injection 或内嵌脚本。
18. 把凭据与数据管道隔离：确保 APIFY_TOKEN 等密钥不会出现在请求处理器中或随抓取数据一起传递，使用 Apify SDK 内置的凭据管理。
19. 安装依赖前审查包名与发布者，警惕 typosquatting 供应链攻击，优先选择知名且活跃维护的包。
20. 始终提交 package-lock.json（Node.js）或在 requirements.txt 中锁定精确版本（Python），并定期运行 npm audit 或 pip-audit 检查已知漏洞。
21. 用 apify run 本地测试 Actor（它会配置 Apify 环境和存储），不要用 npm start、npm run start、npx apify run 等命令。
22. 在平台上运行的代码使用 Apify SDK（apify）；用 Actor.getInput()/Actor.get_input()、Actor.pushData()/Actor.push_data()、Actor.setValue()/Actor.set_value() 等 SDK 方法，而不是等价的 apify actor 运行时子命令。
23. 尽早校验输入并做好错误处理、优雅失败；在 .actor/input_schema.json 中设置合理默认值，在 .actor/output_schema.json 中定义输出 schema。
24. 静态 HTML 用 CheerioCrawler（比浏览器快 10 倍），只有 JavaScript 重的站点才用 PlaywrightCrawler；复杂爬取用 router 模式（createCheerioRouter/createPlaywrightRouter）。
25. 实现带指数退避的重试策略；并发设置合理：HTTP 10-50，浏览器 1-5。
26. 推送数据到 dataset 前先清洗和校验数据；使用带 fallback 策略的语义化 CSS 选择器。
27. 遵守 robots.txt 和 ToS，实现限速；不要抓取禁止内容或存储个人/敏感数据（除非明确获准）。
28. 始终使用 apify/log 包记录日志（它会审查 API key、token、凭据等敏感数据），不要用 console.log() 或 print()。
29. 如果 Actor 使用 standby 模式，实现 readiness probe handler；在 .actor/actor.json 中设置 usesStandbyMode: true 并实现 HTTP 服务器。
30. 不要假设 apify run 产生的本地存储会推送到或在 Apify Console 中可见——它只存在本地；要在 Console 看结果必须 apify push 后在平台上运行。
31. 不要在 Cloud 上依赖 Dataset.getInfo() 获取最终计数；不要把应放在 input schema 或环境变量中的值硬编码。
32. 不要使用已废弃的选项（如 CheerioCrawler v3.x 的 requestHandlerTimeoutMillis），不要用 additionalHttpHeaders（改用 preNavigationHooks）。
33. 远程调用 Actor 时：先用 apify actors search "<query>" 搜索，再用 apify actors info <actor> --readme 看 README、--input 看输入 schema，最后用 --input-file input.json 或带引号的内联 JSON 调用。
34. Actor 输入是单个 JSON 对象而非数组；--input 只接受内联 JSON 对象，需用引号包裹避免 shell 解析问题，复杂输入用 --input-file input.json。
35. 如果目标没有专用 Actor，先在 Apify Store 搜索社区方案再考虑从零构建。
36. 用 apify validate-schema 校验 .actor/input_schema.json；用 apify run --purge 在清除上次本地存储后运行。
37. 用 apify pull <actor> 从平台下载 Actor 代码，用 apify actors build <actor> 创建新构建，用 apify runs ls 列出最近运行。
38. 用 apify secrets add <name> <value> 本地存储密钥（push 时上传），用 apify secrets ls 列出密钥键；在 actor.json 中通过 "@mySecret" 引用。
39. 用 apify api <endpoint> 发起带认证的 Apify API HTTP 请求；用 apify help 或 apify <command> --help 查看帮助。
40. 调试与网页交互的 Actor 时，可安装 Playwright MCP：claude mcp add playwright npx @playwright/mcp@latest，或手动在 MCP 配置中加入 npx @playwright/mcp@latest。
41. 需要文档时使用 Apify MCP 的 search-apify-docs 和 fetch-apify-docs 工具，或访问 https://mcp.apify.com/?tools=docs；也可参考 docs.apify.com/llms.txt、crawlee.dev/llms.txt 和 whitepaper.actor。

适用边界 · 注意事项

• 不使用 Apify 平台或 apify CLI、只想写普通爬虫脚本时，本流程不适用。
• 没有 Apify 账号或 APIFY_TOKEN、且无法登录时无法部署和远程调用。
• Actor 不需要 standby 模式时，不要实现 HTTP 服务器或 readiness probe，也不要擅自禁用 standby 模式。