canvas-component-push

项目类型

应用此技能前，请检查 package.json 中是否有名为 @drupal-canvas/headless 或以 @drupal-canvas/headless- 开头的依赖项。如果存在， 则这是一个 Canvas Headless 代码库——请先阅读 canvas-headless。这里的推送行为有所不同：

• CLI 会自动检测无头 SDK，并将每个组件都推送为 type: external——仅包含元数据，不包含组件代码。这是预期行为；CLI 会记录此情况。
• 推送会创建和更新外部组件，但不会删除它们；canvas pull 也会排除这些组件。
• 下文关于依赖项重试的指导不适用于外部组件：不会推送任何导入，因此不会发生依赖顺序错误。

下文的设置关卡、身份验证处理和连接失败规则仍然适用。如果不存在此类依赖项，则这是一个 Canvas 渲染的 React 代码库：组件采用 React（index.jsx/.tsx），本技能中的所有内容均按原样适用。这是仅有的两种项目类型。

激活条件

仅当用户明确要求将组件推送、发布、同步或上传到 Canvas 时，才运行此技能。

不要在组件编辑、验证或任务完成后自动运行此技能。

推送前，请确认用户已安装 Drupal Canvas CLI，并已为目标站点完成配置。

设置关卡

运行任何推送命令前：

1. 检查 Canvas CLI 是否已通过受支持的来源配置身份验证。对于本地项目，优先使用项目根目录中的 .env 文件。CLI 也会读取 shell 环境变量、~/.canvasrc，以及存储在 ~/.config/drupal-canvas/oauth.json 中的交互式登录令牌（由 npx canvas login 写入）。
2. 验证 CANVAS_SITE_URL 已设置。
3. 主要身份验证方式（优先使用环境变量）： 至少配置以下一项：
   • CANVAS_ACCESS_TOKEN——在 .env / shell 中设置且值非空（对许多设置而言最简单），或
   • CANVAS_CLIENT_ID 和 CANVAS_CLIENT_SECRET——两者均已设置（常用于 CI 和服务类型的访问）。
4. 未配置令牌时的备用方式： 如果已设置 CANVAS_SITE_URL，但 .env / shell 中既没有 访问令牌，也没有客户端凭据，请使用 npx canvas login（基于浏览器的 Canvas 登录）。令牌会按站点 URL 存储在 ~/.config/drupal-canvas/oauth.json 中。请参阅 使用 Canvas Login 进行交互式登录。 在尝试或排除这一备用方式前，不要将身份验证视为缺失。
5. 如果已设置 CANVAS_ACCESS_TOKEN，则将其视为当前使用的身份验证模式。它会完全跳过 OAuth 客户端凭据流程，并忽略 CANVAS_CLIENT_ID、 CANVAS_CLIENT_SECRET 和 CANVAS_SCOPE。
6. 如果完成上述检查后仍缺少必需设置，请停止并先让用户完成设置。
7. 不要猜测设置步骤。请指引用户查阅官方文档：
   • Drupal Canvas OAuth 模块设置： https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
   • Drupal Canvas CLI 软件包 / 文档： https://www.npmjs.com/package/@drupal-canvas/cli
8. 仅在用户确认设置已完成后继续。

运行推送

组件工作完成并通过验证后，询问用户是否要将当前 Canvas 更改推送到 Canvas。canvas push --yes 会推送所有当前更改；它不支持选择特定组件。如果工作树中有无关或未经验证的 Canvas 更改，请停止并询问用户希望如何处理。请确保使用正确的包管理器。例如，如果使用 npm，请运行以下命令：

npx canvas push --yes

如果包含页面，且这些页面含有使用外部 URL 的图片属性，首次推送可能会失败，并出现类似“Some pages contain media that references external URLs”的错误。在媒体完成协调之前，这是预期情况。

支持的页面图片来源：

• 外部 http:// 或 https:// URL
• data:image/... URL

支持协调的图片格式：.jpg、.png、.gif、.webp 和 .avif。

不支持通过 CLI 上传本地文件系统中的图片。

页面媒体协调

处理包含图片属性的页面时：

1. 运行页面推送，例如：

   npx canvas push --yes --include-pages
   

2. 如果 Canvas 报告存在外部媒体引用，请运行：

   npx canvas reconcile-media
   

3. 重新运行页面推送：

   npx canvas push --yes --include-pages
   

4. 将页面拉取回来，以便在本地同步已解析的输入：

   npx canvas pull --include-pages
   

协调和拉取完成后，页面 JSON 可能会更新为：

• 图片属性保留相同的对象结构，但现在会包含已解析的 src、alt、width 和 height
• 可能会添加 _provenance 对象，其中包含 target_id 和 source_url 等值

后续编辑时，请保留已解析的图片属性和 _provenance，除非你有意替换媒体。

拉取操作也可能会将安全的组件 getter 调用迁移为上下文钩子。在认为工作流已完成之前，请检查源代码更改和迁移诊断信息，包括可空结果；请参阅迁移已拉取的组件。

处理推送失败

默认行为：始终重试失败的推送，除非错误明确属于连接或设置故障。

如果失败表明 Canvas 应用连接已正常工作（例如与依赖项或顺序相关的组件错误），请重试推送。不要重试连接或设置故障。

连接或设置故障：停止，不要重试

如果推送因身份验证、授权或网络／连接错误而失败，请停止并让用户先完成或验证设置。这包括无效凭据、未授权／禁止响应、DNS 问题、连接被拒绝、主机不可达、在到达 Canvas 之前发生的请求超时，或 TLS/SSL 握手／证书故障等错误。

如果当前身份验证模式为 CANVAS_ACCESS_TOKEN，请将令牌相关故障视为设置故障。对于无效或过期令牌等错误，或表明令牌未被接受的 401 响应，不要重试。

请引导用户查阅官方设置文档：

• Drupal Canvas OAuth 模块设置： https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
• Drupal Canvas CLI 软件包／文档： https://www.npmjs.com/package/@drupal-canvas/cli

请让用户先检查 CLI 正在使用的配置来源中的 CANVAS_SITE_URL，以及当前令牌或客户端凭据值（例如：Shell 环境变量、.env、~/.canvasrc 或交互式登录配置／会话）；如果这些值未设置或无效，请让他们将 npx canvas login 作为备用方案运行（或再次运行以刷新交互式令牌）。只有在用户确认设置更新已完成后，才重试推送。

依赖相关故障

推送多个新组件时，如果其中一个组件依赖另一个组件（例如，hero 导入了 heading），推送可能会失败，并提示某个组件不存在。如果包含其他组件的组件先于其依赖项推送，就会发生这种情况。

这是预期行为。 只需重试推送命令即可。后续尝试时，之前成功推送的依赖项已经存在，因此依赖它们的组件也能成功推送。

示例场景：

1. 第一次尝试推送：由于 heading 尚不存在，hero 推送失败，但 heading 推送成功。
2. 第二次尝试推送：由于 heading 已存在，hero 现在可以成功推送。

如果重试多次后推送仍然失败，请检查所有必需的依赖组件是否包含在当前本地更改中，或是否已存在于 Canvas 中。