企业官网建设流程全解析

Apify Actor 输出 Schema 权威指南：用 Output Schema 与模板变量打通数据集、键值存储与运行结果展示

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills

导读

Output Schema（输出模式）是 Apify Actor 面向外部世界的一扇窗口：它声明 Actor 把结果写到哪里（默认数据集、默认键值存储），并通过一组内建模板变量生成可直接访问这些输出的 URL。本文将围绕仓库中 output-schema.md 这份权威参考文档展开，结合 Apify Actor 开发技能包（SKILL.md）与配套的 dataset、key-value store、actor.json 参考文档，逐项拆解 Output Schema 的结构、字段语义、模板变量体系，并给出可复制到.actor/output_schema.json的完整实战配置。读完本文，你将能独立为任意 Actor 编写输出声明，让 Apify Console 正确呈现运行结果，也能在本地与云端正确验证输出。

本文所有结论均以仓库内 apify-actor-development 技能包 中的文档与示例为依据；该技能包在仓库中存在两份镜像：plugins/agentic-awesome-skills-claude/skills/apify-actor-development 与 plugins/agentic-awesome-skills/skills/apify-actor-development，内容一致。

Output Schema 在 Actor 输出体系中的位置

在 Apify 的存储模型中，Actor 的运行输出并不直接"返回"给调用方，而是落盘到两类平台级存储中：

• Dataset（数据集）：结构化 JSON 记录流，适合爬取结果、列表数据，通过Actor.pushData()/Actor.push_data()写入，其展示方式由 dataset-schema.md 定义；
• Key-Value Store（键值存储）：任意二进制/文本文件，适合 HTML 快照、图片、PDF 等非结构化产出，通过Actor.setValue()/Actor.set_value()写入，其组织方式由 key-value-store-schema.md 定义。

Output Schema 正是在这两套存储 Schema 之上建立的"总出口"：它指明 Actor 将输出存放在哪里，并定义访问这些输出的模板。根据 output-schema.md 的说明，Apify Console 会直接使用这份输出定义来渲染运行结果界面（Run 结果页），也就是说——Output Schema 写得对不对，直接决定用户在 Console 里能否一键看到成品。

从技能包的工作流看（SKILL.md 的 Quick Start Workflow），Output Schema 属于"Configure schemas"环节的必选项，与.actor/input_schema.json、.actor/dataset_schema.json一并更新，其标准存放路径为.actor/output_schema.json。

Output Schema 的结构定义

Output Schema 是一个 JSON 对象，由三个顶层字段构成：

{ "actorOutputSchemaVersion": 1, "title": "<OUTPUT-SCHEMA-TITLE>", "properties": { /* define your outputs here */ } }

各字段语义：

• actorOutputSchemaVersion（整数，必需）：Output Schema 结构文档的版本号，当前仅支持1；
• title（字符串，必需）：Output Schema 的标题，将展示在 Console 的运行结果区域，应使用人类可读的描述性文本；
• properties（对象，必需）：输出项的声明集合，每个键对应一个输出入口，键名通常与存储语义对应（如files、dataset）。

与 input-schema.md 中type: "object"+properties的结构风格一致，Output Schema 同样采用"对象 + 属性集"的声明式结构，但每个输出属性不是输入控件定义，而是一个指向真实存储位置的模板字符串。

完整示例：文件爬虫的 Output Schema

仓库文档给出了一个"文件爬虫（files scraper）"的完整示例，它同时展示了键值存储与数据集两个出口：

{ "actorOutputSchemaVersion": 1, "title": "Output schema of the files scraper", "properties": { "files": { "type": "string", "title": "Files", "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys" }, "dataset": { "type": "string", "title": "Dataset", "template": "{{links.apiDefaultDatasetUrl}}/items" } } }

逐项解读：

• files输出：模板{{links.apiDefaultKeyValueStoreUrl}}/keys解析后指向默认键值存储的 API 地址并追加/keys路径段，返回该存储下所有键（即文件清单）。这与技能包中"文件爬虫将抓取到的文件写入键值存储"的定位吻合——参考 key-value-store-schema.md 中Actor.setValue()保存文本/图片缓冲区的示例，键值存储正是文件类产出的归宿；
• dataset输出：模板{{links.apiDefaultDatasetUrl}}/items解析后指向默认数据集的 API 地址并追加/items路径段，返回数据集中的全部记录。对应Actor.pushData()写入的结构化记录流（见 dataset-schema.md 的 JavaScript/Python 示例）；
• 每个输出属性的type为string（模板最终渲染为 URL 字符串），title用于 Console 上的展示标签。

注意type字段是 Apify Console 渲染模板值所需的类型声明，务必保持为string；模板中的{{...}}占位符将在运行时被对应的模板变量值替换。

模板变量详解：links 与 run

Output Schema 之所以能动态生成正确 URL，靠的是内置模板变量。根据 output-schema.md 的完整清单，模板变量分为两个命名空间：

links（对象）——常用 URL 快捷入口

run（对象）——当前 Run 的元数据

run对象的字段与GET RunAPI 端点返回的运行信息一致，常用字段包括：

• run.defaultDatasetId（string）：默认数据集的 ID；
• run.defaultKeyValueStoreId（string）：默认键值存储的 ID。

run命名空间的价值在于：当你想在输出中直接拼出存储 ID（而不是依赖links的快捷 URL）时，可以写成{{run.defaultDatasetId}}。例如，一个更底层的 dataset 输出模板可以是：

{ "type": "string", "title": "Dataset (raw ID)", "template": "https://api.apify.com/v2/datasets/{{run.defaultDatasetId}}/items" }

组合使用建议

• 优先使用links.*：它把 URL 拼装细节（域名、路径前缀、ID 注入）全部封装好，且与文档示例保持一致，最不易出错；
• 需要引用非默认存储或做自定义拼装时，使用run.defaultDatasetId/run.defaultKeyValueStoreId作为原材料；
• links.containerRunUrl仅在 Actor 内运行了 HTTP 服务（典型场景是 standby-mode.md 描述的 standby 模式，Actor 像实时 Web/API 服务器一样常驻等待请求）时才有意义。

将 Output Schema 接入 Actor 项目

1. 在 actor.json 中声明引用

actor.json（.actor/actor.json）通过output字段指向 Output Schema 文件，同时可在storages中声明 dataset / key-value store 的存储 Schema——三者共同构成完整的输出声明链。参考 actor-json.md 的结构：

{ "actorSpecification": 1, "name": "project-cheerio-crawler-javascript", "title": "Project Cheerio Crawler Javascript", "description": "Crawlee and Cheerio project in javascript.", "version": "0.0", "meta": { "templateId": "js-crawlee-cheerio", "generatedBy": "Claude Code with Claude Sonnet 4.5" }, "input": "./input_schema.json", "output": "./output_schema.json", "storages": { "dataset": "./dataset_schema.json" }, "dockerfile": "../Dockerfile" }

要点：

• output指向.actor/output_schema.json；
• storages.dataset/storages.keyValueStore分别指向 dataset 与键值存储 Schema 文件，Output Schema 里的{{links.apiDefaultDatasetUrl}}、{{links.apiDefaultKeyValueStoreUrl}}正是为这些默认存储生成访问地址；
• 按技能包要求（SKILL.md 开头的重要提示），meta.generatedBy必须填写你实际使用的工具与模型（如Claude Code with Claude Sonnet 4.5），用于 Apify 追踪 AGENTS.md 的改进。

2. 本地验证与云端部署

技能包明确要求：本地测试必须用apify run，而不是npm start/npx apify run等命令，因为只有apify run才会正确配置 Apify 运行环境与本地存储。完整流程为：

apify run # 本地运行：写入 storage/ 目录（本地专用，不会同步到 Console） apify push # 部署到 Apify 平台（Actor 名取自 .actor/actor.json 的 name 字段）

两条重要事实需要牢记（来源：SKILL.md 的 Local Testing 一节）：

• apify run产生的数据集、键值存储、请求队列只存在于本地storage/目录，永远不会自动上传；
• 要验证 Output Schema 在 Console 上的渲染效果，必须apify push后在平台运行，再查看 Run 结果页。

因此，本地验证输出时请检查storage/目录或 Actor 日志，而不是去 Console 找结果；云端验证时再关注 Console 的 Output 标签页是否按模板正确渲染出数据集/文件列表入口。

与 Dataset、Key-Value Store Schema 的分工边界

为了避免混淆，需要厘清三份"输出相关"Schema 各自的职责：

三者是叠加而非替代关系：dataset schema 决定"数据集里的每条记录长什么样、怎么显示"（如views.transformation.fields决定列顺序，display.properties.<字段>.format支持text|number|date|link|boolean|image|array|object八种展示格式，详见 dataset-schema.md）；key-value store schema 通过collections.<name>.keyPrefix把键按前缀归类（如document-、image-），并用contentTypes限制允许的 MIME 类型（见 key-value-store-schema.md）；而 Output Schema 站在最上层，用模板变量把"默认数据集 / 默认键值存储"的整体访问入口暴露给用户。

实战检查清单与常见误区

写作 Output Schema 时建议按以下清单自检：

• ✅actorOutputSchemaVersion设置为1，title使用可读描述；
• ✅ 每个输出属性type为string，template以{{开头且引用的变量名拼写正确（links.apiDefaultDatasetUrl、links.apiDefaultKeyValueStoreUrl是最常用的两个）；
• ✅ 文件类产出通过.../keys暴露键清单，记录类产出通过.../items暴露数据；
• ✅.actor/actor.json中output与storages路径正确，generatedBy已填写；
• ✅ 用apify run本地验证、apify push部署后在 Console 复核模板渲染结果；
• ❌ 不要混淆：Output Schema 不是 dataset schema，properties里放的是模板 URL，不是字段格式化定义；
• ❌ 不要使用console.log()/print()代替 Apify 日志（会绕过凭据脱敏），详见 logging.md。

遵循以上规范，你的 Actor 输出就能在 Apify 平台上"开箱即见"——用户从 Run 结果页一键直达数据集与文件清单，这正是 Output Schema 设计的最终目的。

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills