cloudcannon-configuration

CloudCannon 配置

此技能介绍如何创建和自定义 cloudcannon.config.yml，该文件用于告知 CloudCannon 如何理解和呈现网站内容；以及如何创建和自定义 .cloudcannon/initial-site-settings.json，该文件用于告知 CloudCannon 如何构建网站。

适用场景

• 创建或自定义 cloudcannon.config.yml 或 .cloudcannon/initial-site-settings.json
• 添加或更改 Collections、Inputs、Structures 或 Select Data
• 编辑器中缺少某个字段，或显示了错误的 Input 类型
• 配置 Collection URL，让页面能在 Visual Editor 中打开

不适用场景

• 向模板添加可编辑区域——请使用 cloudcannon-visual-editing。此技能负责配置这些区域背后的数据。
• 内容中的 MDX 组件或内联 HTML——请使用 cloudcannon-snippets
• 执行完整迁移——请从 migrate-to-cloudcannon 开始；该技能会在第 2 阶段进入此技能
• 操作托管网站——身份验证、列出或创建网站、读取和写入网站文件、触发构建，或更改现有网站的构建配置，请使用 cloudcannon-cli。此技能用于确定配置应包含什么内容；而 CLI 技能用于运行命令。

编写任何配置前，请先执行此操作

mkdir -p .cloudcannon/migration
curl -sL "https://github.com/cloudcannon/configuration-types/releases/latest/download/cloudcannon-config.latest.schema.json" \
  -o .cloudcannon/migration/cloudcannon-config.latest.schema.json
curl -sL "https://github.com/cloudcannon/configuration-types/releases/latest/download/cloudcannon-initial-site-settings.schema.json" \
  -o .cloudcannon/migration/cloudcannon-initial-site-settings.schema.json

在两个文件都存在之前，不要继续。训练数据会虚构键；只有这些 Schema 是权威依据。

查询示例、.gitignore 规则和 yaml-language-server 规则请参阅 json-schemas.md。

检查是否存在任何格式的现有配置——cloudcannon.config.{yml,yaml,json,js,cjs,mjs}，而不只是 .yml。如果存在，请自定义该配置，并仅使用 --dry-run 运行 configure generate 以供参考；如果不使用 --dry-run，CLI 会在其旁边写入第二个 cloudcannon.config.yml。如果不存在，请生成基线配置——参阅 configuration.md § 生成基线配置。

无效键

编写配置前请检查此表。这些是 Agent 曾编写过、但 Schema 中不存在的键；JSON Schema 才是权威依据。

错误	正确
disable_url_preview: true	disable_url: true，这会关闭集合的输出 URL。
output: false	省略 url 并设置 disable_url: true，或改用 data_config，而非集合。
type: hidden	在任意输入项中，将 hidden: true 放在 type 旁边；hidden: "<query>" 可有条件地隐藏输入项。
options.max 用于 text 或 textarea 输入项	使用 options.max_length，并配合 min_length。
_editables.text 使用块级键（bulletedlist、blockquote、format、table）	_editables.text 仅支持行内内容——参见 § _editables 键到架构的映射。
heading2: true、heading3: true	使用以空格分隔的字符串 format: "p h1 h2 h3"——参见 § _editables 键到架构的映射。
options.collections: [team]	使用 values: collections.team，并设置 value_key 和 preview——参见 inputs.md § 从集合中选择值。
options.structures: my_blocks	使用完整路径 _structures.my_blocks——参见 structures.md § 四条规则。
timezone: "+10:00"	使用顶层 IANA 名称，例如 Australia/Melbourne，默认值为 Etc/UTC——参见 configuration.md § 检查生成的配置。
paths.collections、paths.data	使用 collections_config.<name>.path 和 data_config.<name>.path。
paths.output	没有此键：构建工具会设置输出目录。paths 仅用于存放资源目录：static、uploads、uploads_filename、dam_uploads、dam_uploads_filename、dam_static、uploads_use_relative_path。
Material Symbols 名称不在架构枚举范围内，例如 place	使用枚举中的名称，例如 location_on；无效名称会回退到默认图标——使用 json-schemas.md 中的图标示例进行检查。

每项任务的规则

• 开始前，阅读验证清单和 SSG 的清单，明确需要达到的目标。
• 只有在两份清单中的每一项都通过验证后，才算完成。
• 为编辑器可见的每个字段添加明确的 _inputs 条目；类型推断仅作为备用方案——参见 configuration.md § 明确配置每个字段。
• 每轮更改后都要运行 npx @cloudcannon/cli validate。如果它标记了某个键，请在§ 无效键中查找正确的键。

目录

文件	何时阅读
configuration.md	始终先阅读；编写配置时查看步骤和通用验证清单。
json-schemas.md	编写任何键之前，检查它是否存在于架构中。
cloudcannon-cli-guide.md	逐步生成基线配置，或进行验证时阅读；CLI 的其余内容见 cloudcannon-cli。
schemas.md	添加集合或编写其 schemas 之前阅读——一个集合可以包含多个架构。
inputs.md	编写 _inputs 之前阅读。
structures.md	任何字段包含数组或对象时阅读，因为没有结构，编辑器就无法添加项目。
collection-urls.md	任何集合会生成页面，或页面无法在 Visual Editor 中加载时阅读。
build-commands.md	编写 install_command 或 node_version 时，或构建包含生成器或构建后步骤时阅读。
routing.md	网站设置了响应标头、重定向或重写规则时阅读（框架配置、_headers、netlify.toml、vercel.json）。
configuration-gotchas.md	配置时查找跨 SSG 常见问题。
troubleshooting.md	配置已经有误，且你正在根据症状排查时阅读。

针对特定 SSG： 从对应 SSG 的 overview.md 开始；其中会说明阅读顺序，并列出该 SSG 的所有文件。

网站使用的技术	从此处开始
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy	eleventy/overview.md
Next.js	nextjs/overview.md

其他技能：

技能	何时阅读
make-site-multilingual	配置多语言网站时：区域设置数据集、按区域设置划分的集合，以及带区域设置前缀的 URL。
cloudcannon-dev-server	用户希望在 CloudCannon 中打开已配置的网站，并试用集合和输入项时阅读。