mcpField
W
webflow-cli:cloud

webflow-cli:cloud

github.com/webflow云与 DevOps1331.0k 次安装今天更新
代码仓库

关于 webflow-cli:cloud

webflow-cli:cloud 是使用 Webflow CLI 初始化项目、部署应用并管理 Webflow Cloud 的技能。它会根据项目状态指导 Agent 选择流程及所需的非交互参数。

主要功能

  1. 01从模板或 GitHub 初始化项目
  2. 02部署站点关联或独立应用
  3. 03管理应用、环境、日志和部署
  4. 04设置环境变量
  5. 05指导非交互式 CLI 流程

适用场景

  1. 01部署本地 Next.js 或 Astro 项目
  2. 02连接 GitHub 仓库进行部署
  3. 03查看应用日志和部署状态

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/webflow/webflow-skills --skill webflow-cli:cloud

安装后在 Claude Code 中输入/webflow-cli:cloud确认已加载。

详细介绍

Webflow Cloud

从模板或现有 GitHub 仓库初始化新项目，部署到 Webflow Cloud，并管理现有应用（列表、检查、日志、部署、环境、环境变量）。部署支持两种模式：关联站点（部署到现有 Webflow 站点）和项目应用（作为独立应用部署，无需现有站点）。

命名空间：apps（规范）与 cloud（已弃用的别名）

webflow apps <command> 是 Webflow Cloud 的规范命名空间。webflow cloud <command> 仍可使用——其 init / deploy 形式是同一处理程序的别名——但已弃用，建议改用 apps。

规范命令已弃用的 cloud 别名说明
webflow apps initwebflow cloud init选项和处理程序相同——但 --import 及其仓库导入选项仅适用于 apps init。
webflow apps deploywebflow cloud deploy处理程序相同——但 --json 和 --dry-run 仅适用于 apps deploy。
—webflow cloud create <name>即将移除，现已弃用；建议改用 apps init（如果继续使用旧版命名空间，也可用 cloud init）。
—webflow cloud list列出的是脚手架模板，而非应用。该命令仍保留在 cloud 下；没有对应的 apps 命令。不要与列出工作区应用的 apps list 混淆。
webflow apps list / get / domains / link / update / delete / environments … / deployments … / logs … / env-vars …—**没有对应的 cloud 命令。**仅限规范命名空间。

通过 cloud init / cloud deploy 运行命令时，会在 stderr 上输出一次性弃用提示，指向对应的 apps 命令形式（使用 --json 时不显示）。

所有新工作都应优先使用 apps 命令形式。本指南始终使用 apps 命令；每个 apps init / apps deploy 调用都可使用带有相同标志的 cloud init / cloud deploy 替代，但 --import（init）和 --json / --dry-run（deploy）除外。

说明

步骤 0：确认 CLI 已安装
webflow --version

如果找不到该命令，请安装：

npm install -g @webflow/webflow-cli@latest
# or yarn global add @webflow/webflow-cli@latest
# or pnpm add -g @webflow/webflow-cli@latest

然后继续检测状态。

步骤 1：检测项目状态

在决定采用哪条路径之前，先运行这两项检查：

# Is this project already set up on Webflow Cloud?
cat webflow.json

# Is there a git remote?
git remote get-url origin 2>/dev/null

快速参考（CLI 现在会写入 cloud.app_id；旧版清单可能包含旧字段 cloud.project_id，读取时仍会将其作为备用字段）：

webflow.json 中的 cloud.app_id（或旧版 cloud.project_id）git remote→ 路径
否—A — 新项目
是否B — 现有项目，无 git
是是C — 理想状态

你在没有 TTY 的环境中运行。 只有当 process.stdin.isTTY 为 true 时，CLI 的交互式提示才会触发。作为通过子进程调用 CLI 的 Agent，你没有 TTY——所有提示都会被静默跳过，而任何未通过标志传入的必填值都会触发硬错误，例如 --app-name cannot be empty。

此技能中的每条命令都遵循以下规则： 显式传入所有必需的标志。绝不要依赖提示。当 CLI 接受 --no-input 时，请传入该标志，以明确遵循此约定。各命令所需的标志如下：

命令始终传入
apps init（关联站点）--no-input --app-name <3–39 chars> --framework <astro|nextjs|vite> --mount <path> --site-id <id>
apps init --new（应用）--no-input --app-name <3–39 chars> --framework <astro|nextjs|vite|static> --workspace-id <id>
apps init --import（关联站点）--no-input --import <repo-url> --site-id <id> --mount <non-root path> --idempotency-key <key>
apps init --import --new（项目应用）--no-input --import <repo-url> --new --idempotency-key <key> — 不要传入 --mount
apps deploy（关联站点）--no-input --mount <path> --environment <env> --site-id <id>，首次部署时还需传入 --app-name
apps deploy（项目应用，首次部署）--no-input --mount <path> --environment <env> --workspace-id <id> --app-name <name>

apps deploy 上的 --site-id、--app-id、--framework 和 --workspace-id 可让 Agent 在部署时覆盖 webflow.json 中的值。

多工作区令牌曾导致 Agent 致命挂起，因为工作区选择没有非 TTY 操作路径。现在传入 --workspace-id 即可跳过选择器。Webflow 控制面板 UI 中不会显示工作区 ID——用户无法手动查到。如果 Agent 没有该 ID，请让用户在项目目录中交互式运行一次 webflow apps deploy。预检会提示用户选择工作区，并将 cloud.workspace_id 写入 webflow.json；此后，Agent 就可以从清单中读取该值，并在后续运行时传入 --workspace-id。不要建议使用 apps init --new 来发现 ID——在现有项目中运行它会创建一个随后被丢弃的临时目录。**例外：**在 Path A2（空目录）中，可以安全地尝试不带 --workspace-id 运行 apps init --new，以自动解析仅含单个工作区的令牌——请参阅 Path A2。

控制面板中可以查看站点 ID。 如果需要 --site-id 但不知道其值，请不要向用户索要原始的 site_XXXX 值——使用 webflow sites list 获取其站点，并根据显示名称提供选择器。用户也可以在控制面板中查看并获取该值。

读取／管理命令不需要 --workspace-id。 apps list / get / domains / environments / deployments / logs / env-vars 命令会在服务端根据 OAuth 令牌推导工作区——它们没有 --workspace-id 标志，也不会提示选择工作区。请参阅管理应用。

路径 A：没有 app_id — 新项目

项目尚未部署。开始任何操作之前，先问用户两个问题：

  1. “你已经有这个项目的源代码（现有的 Next.js 或 Astro 代码库），还是要从空目录开始，并希望使用 Webflow starter 脚手架？”
  2. 如果用户已有代码：“代码已经推送到 GitHub 仓库了吗？你希望 Webflow 从该仓库构建（而不是使用本地文件）吗？”

用户的回答决定了分支——这三种情况有实质区别：

用户拥有……分支初始化步骤
现有代码，从本地文件部署路径 A1跳过 apps init。 它会在仓库内创建 ./<app-name>/ 子目录，并在其中放入一个 hello-world 脚手架，而用户并不需要这个。
空目录，或希望使用 Webflow starter路径 A2运行 apps init，从 Webflow-Examples/hello-world-* 搭建脚手架。
现有代码已在 GitHub 上，希望 Webflow 从仓库构建路径 A3运行 apps init --import <repo-url> — 创建一个连接到 GitHub、绑定到该仓库的应用。仅适用于 apps；没有 cloud init --import。

选择 A1 还是 A3 并非表面差异——它决定了应用之后能做什么。 连接到 GitHub 的应用（A3）可以使用 apps deployments trigger / redeploy，也是唯一符合控制面板推送即部署条件的应用。通过本地 apps deploy 首次创建的应用（A1）没有连接到 GitHub，因此 trigger / redeploy 会拒绝处理。如果用户的代码已经在 GitHub 上，并且提到 CI、自动部署、回滚或“我推送时就部署”，应选择 A3，而不是 A1。

无论选择哪种方式，都可以补救：之后可以通过 apps update --github-source <repo-url> 将 A1 应用指向某个仓库（参见 apps update）——但一开始就选择 A3 可以省去这一步。

确定分支后，还要询问是关联到站点还是作为独立应用（仅在首次部署前相关）：

用户表示……模式结果
“部署到我的 Webflow 站点 <name>”、“关联到站点”，提及现有站点关联到站点应用绑定到现有 Webflow 站点；站点 URL 会在选定的挂载路径托管此应用。需要 --site-id。
“项目应用”、“仅作为应用”、“不需要站点”，或未提及现有站点独立应用首次部署会配置一个全新的 Webflow 站点（<app-name>-<hash>.webflow.io）。

如果用户对任一问题的回答含糊，请进一步询问。不要自行默认。

路径 A1：已有代码库，从本地文件部署

如果代码在 GitHub 上，请先查看路径 A3。 此路径会上传并构建本地文件，生成的应用不会连接到 GitHub——apps deployments trigger / redeploy 和仪表板中的推送部署都会拒绝处理。如果代码库在 GitHub 上，且用户希望 Webflow 从中构建，请改用路径 A3。

用户已有可用的源代码。apps deploy 会处理所有事情——它会根据 package.json 检测框架，预检阶段则会从标志解析身份信息，或提示用户输入。无需运行 apps init，也无需预先手动编写 webflow.json。

步骤 1：一次性身份验证（仅限人工操作）。 告知用户在本地运行此命令；Agent 无法操作浏览器流程：

webflow auth login

步骤 2：部署。 具体命令形式取决于 Agent 已知的信息。

A1-a — 关联到站点，已知 --site-id：

webflow apps deploy --no-input \
  --site-id site_abc123 \
  --app-name my-app \
  --framework nextjs \
  --mount /app \
  --environment main \
  --skip-mount-path-check \
  --skip-update-check

如果 package.json 中存在可检测的信号，则 --framework 为可选项：nextjs / astro 对应 Cloudflare 适配器（@opennextjs/cloudflare、@astrojs/cloudflare），vite 则对应 vite 包本身。对于 monorepo，或自动检测不可靠的情况，请显式传入此参数。

如果 Agent 不知道用户的 --site-id，不要询问原始的 site_XXXX 值；请使用 webflow sites list 获取用户的站点，并提供易读的显示名称供其选择。

A1-b — 项目应用，已知 --workspace-id：

webflow apps deploy --no-input \
  --workspace-id ws_abc123 \
  --app-name my-app \
  --framework nextjs \
  --mount / \
  --environment main \
  --skip-mount-path-check \
  --skip-update-check

A1-c — 项目应用，不知道 workspace ID（常见的缺失信息）：

Webflow 仪表板 UI 中的任何位置都看不到 workspace ID。 用户无法手动查找——发现它的唯一方法是运行 CLI。因此，操作流程如下：

请用户在本地交互式运行一次部署。 在其项目目录中运行：

webflow apps deploy

不传入 --no-input 或任何身份标志时，预检会提示："此项目尚未针对 Webflow Cloud 初始化。您希望如何部署？" → 用户选择“创建新应用” → 选择工作区 → 完成。经过这次由用户操作的部署后，cloud.workspace_id 和 siteId 会写入 webflow.json，WEBFLOW_SITE_ID 会写入 .env。之后 Agent 就可以使用 --site-id（新配置的站点）运行所有后续部署。

不要让用户运行 apps init --new 来“发现”其 workspace ID。在已有项目中，这会在用户的代码库内创建一个弃用的 ./<app-name>/ 临时目录，并在其中生成 hello-world 脚手架。请使用上述交互式 apps deploy 流程——它能在同一步骤中发现 workspace ID 并完成首次部署。

步骤 3：设置 git（如果尚未设置）——与下文路径 A2 的步骤 3 相同。

路径 A2：空目录，从头搭建脚手架

  1. 搭建项目脚手架——选择符合用户意图的形式：

    # Project app (no site attachment). --workspace-id avoids the multi-workspace hang.
webflow apps init --new --no-input \
  --app-name my-app \
  --framework astro \
  --workspace-id ws_abc123

    # Site-attached (connect to an existing Webflow site). Requires --site-id.
webflow apps init --no-input \
  --app-name my-app \
  --framework astro \
  --mount /app \
  --site-id site_abc123

    所有标志请参阅 apps init。

    仅适用于路径 A2 中项目应用的工作区 ID 发现：由于路径 A2 从空目录开始，apps init --new 无论如何都会创建全新的脚手架，不会造成任何污染。因此，如果 Agent 没有 --workspace-id，可以先尝试不带该参数运行 apps init --new：

    # Try this first if --workspace-id is unknown (Path A2 only — empty dir)
webflow apps init --new --no-input \
  --app-name my-app \
  --framework astro
    • **单工作区令牌：**CLI 会自动选择唯一的工作区，将 cloud.workspace_id 写入 webflow.json，然后以状态码 0 退出。从清单中读取该值，并在第 2 步运行 apps deploy 时将其作为 --workspace-id 传入。
    • **多工作区令牌：**工作区选择器会启动，而命令会一直挂起（没有 TTY）。为 Bash 调用设置 30 秒超时（或使用 timeout 30s ... 包装命令）——单工作区初始化成功需要 10–20 秒（OAuth 检查 + GET /v2/workspaces + 从 GitHub 下载脚手架），因此超过 30 秒仍无输出，就表示选择器已挂起。超时后，直接向用户询问工作区 ID，并使用 --workspace-id 重新运行。

    对于路径 A2 中的关联站点，没有等效的自动发现方式——必须预先提供 --site-id。请使用下方的站点选择器模式帮助用户选择。

    **路径 A1（现有代码库）不适用此方法。**在现有项目中运行 apps init --new 会创建一个随后被丢弃的临时子目录。路径 A1 的工作区 ID 发现方式仍按路径 A1-c 中的说明进行。

路径 A3：现有 GitHub 仓库，已连接 GitHub 的应用

用户的代码已在 GitHub 上，并且希望 Webflow 从仓库构建，而不是从本地文件构建。apps init --import <repo-url> 会创建绑定到该仓库的应用，并将其克隆到本地。

仅适用于 apps。 --import 仅适用于 apps init，刻意不提供 cloud init --import。如果用户因其他原因使用 cloud 命名空间，请改用路径 A1，稍后再通过 apps update --github-source 关联仓库。

步骤 0：前置条件——Webflow GitHub App。 必须将其安装到仓库所有者名下，并连接到工作区。CLI 无法完成此操作；这需要在控制面板/GitHub 端进行设置。如果导入因权限问题失败，首先应检查这一点。

步骤 1：一次性身份验证（仅限人工操作）。 与 A1 相同——Agent 无法执行浏览器流程：

webflow auth login

步骤 2：导入。 必须且只能指定 --site-id 或 --new 其中之一——CLI 不会根据仓库中的任何内容推断目标。

A3-a——关联到站点（必须指定 --mount，且不能是根路径）：

webflow apps init --import https://github.com/acme/site \
  --site-id 6234abc --mount /app --dry-run

webflow apps init --import https://github.com/acme/site \
  --site-id 6234abc --mount /app

A3-b——项目应用（不允许指定 --mount——项目应用独占其自身域名的根路径）：

webflow apps init --import https://github.com/acme/site --new

A3-c——非交互式 / CI。 此处必须指定 --idempotency-key。使用一个在重试时保持不变、且对该仓库和目标唯一的密钥（例如 $GITHUB_RUN_ID-$REPOSITORY-$SITE_ID），这样重试时会复用原有应用，而不是创建第二个：

webflow apps init --import https://github.com/acme/site --new --no-input \
  --idempotency-key "$GITHUB_RUN_ID-acme-site" \
  --branch main --json

添加 --skip-clone，即可注册应用而不在文件系统中写入任何内容——此时会输出应用和环境 ID。适用于仓库已检出，或运行环境不适合进行克隆的情况。

--branch 用于选择构建所用的分支；默认使用仓库的默认分支。

步骤 3：启用推送部署（控制面板，手动操作）。 导入会将应用连接到仓库，但完成控制面板配置之前，推送不会触发部署——请参阅完整工作流示例的第 3 步及后续步骤。在此之前，可按需构建：

webflow apps deployments trigger --json

不要对 A3 应用运行 apps deploy 来“推送更新”。 该命令会上传本地文件，属于 A1 模式；对于已连接 GitHub 的应用，对应的操作是 deployments trigger（构建当前 HEAD）和 deployments redeploy <depId>（重新运行之前的提交，即回滚）。

从列表中选择 --site-id

在需要 --site-id 时（Path A1 关联站点、Path A2 关联站点或其他情况），如果用户没有提供，请使用 webflow sites list --json 枚举令牌可访问的站点，然后向用户展示简短的可读名称列表供其选择。站点 ID 可在 Webflow 控制面板的 URL 配置中查看，但要求用户输入数字 ID 的体验很差；除非用户要求查看 ID，否则应展示名称。

# Returns a JSON array of sites with id, displayName, lastPublished, etc.
webflow sites list --json

工作流：

  1. 运行 webflow sites list --json。CLI 会以 JSON 数组形式返回，退出码为 0。

  2. 解析输出。向用户展示以 displayName 为键的简短列表（如果用户有很多站点，则同时显示 lastPublished）。示例：

    Which site should this project deploy to?

1. Acme Marketing  (last published 2 days ago)
2. Acme Docs       (last published 3 weeks ago)
3. Acme Internal   (never published)

  3. 将用户的选择映射回对应的 id 字段，并将其作为 --site-id 传入。

如果 webflow sites list 出错（缺少认证或认证已过期），请向用户展示错误，并让用户在本地运行 webflow auth login；不要尝试通过 Agent 操作。

  1. 部署： 选择与上述初始化形式匹配的形式。传入 --site-id（如果是项目应用的首次部署，则传入 --workspace-id），以免在清单文件部分写入时导致部署误读清单。

    # Project-app first deploy — provisions the Cloud site/app/env
webflow apps deploy \
  --no-input \
  --app-name my-app \
  --workspace-id ws_abc123 \
  --mount / \
  --environment main \
  --skip-mount-path-check \
  --skip-update-check

    # Site-attached first deploy — uses the existing Webflow site
webflow apps deploy \
  --no-input \
  --app-name my-app \
  --site-id site_abc123 \
  --mount /app \
  --environment main \
  --skip-mount-path-check \
  --skip-update-check

    这会在 Webflow Cloud 上创建应用，并在 webflow.json 中设置 cloud.app_id。提交更新后的 webflow.json。

  2. 设置 git（如果尚未设置）：

    git init && git add . && git commit -m "init"
git remote add origin https://github.com/your-org/my-app.git
git push -u origin main

  3. （可选）通过 Webflow 控制面板启用推送部署。 仅推送到 GitHub 不会触发部署——相关设置位于 Webflow 控制面板中，不在 CLI 或代码库中。告知用户：

    1. 打开 Webflow 控制面板 → 他们的 Cloud 应用 → Settings → Git
    2. 连接他们的 GitHub 账户，然后选择代码库和分支
    3. 确认——控制面板会自动运行一次初始部署，以验证连接
    4. 从此之后，每次推送到已连接的分支都会触发部署

    CLI 无法执行上述任何步骤。如果用户跳过此操作，则每次部署都必须手动运行 webflow apps deploy（类似 Path B 的方式），或使用 CI/CD 流水线。

如果第 2 步出现部署认证错误：运行 webflow auth login，完成浏览器流程，然后重试。

Path B：app_id 已存在，没有 git 远程仓库——已有项目，没有 git

项目已在 Webflow Cloud 上，但没有 git 仓库。直接部署，并建议用户设置 git。

  1. 部署： 先读取 webflow.json。如果设置了 siteId，则传入与其匹配的 --site-id。如果只设置了 cloud.workspace_id，则传入与其匹配的 --workspace-id。

    webflow apps deploy \
  --no-input \
  --site-id site_abc123 \
  --mount / \
  --environment main \
  --skip-mount-path-check \
  --skip-update-check

  2. 建议启用推送部署： 建议用户初始化 git 仓库、推送到 GitHub，然后在 Webflow 控制面板中连接该仓库（应用 → Settings → Git）。控制面板中的这一步才会启用推送部署——CLI 无法执行此操作。请参阅 Path A 的第 3–4 步。

如果出现部署认证错误：运行 webflow auth login，完成浏览器流程，然后重试第 1 步。

路径 C：存在 app_id 和 git remote — 可能是理想情况

项目已部署且有 git remote，但存在 remote 并不能证明已配置好推送即部署。 这项连接是在仪表板端配置的，CLI 无法查看。提出建议前，请先确认。

务必询问用户： “此仓库是否已在仪表板中连接到你的 Webflow Cloud 应用（应用 → Settings → Git，并已选择分支）？” 答案会影响建议：

  • 是，已连接 — 推送即部署已启用。唯一需要执行的操作是 git push。不要建议重新关联或重新部署。
  • 否，未连接 — git push 在 Webflow 端不会执行任何操作。可以立即手动部署，也可以先让用户在仪表板中连接仓库，以便为后续提交启用推送即部署。
  • 不知道 — 假设尚未连接，并建议在仪表板中进行连接（一次性设置，之后推送即部署将持续生效）。

  1. 如果已连接 — 只需提交并推送：

    git add .
git commit -m "your message"
git push

    Webflow Cloud 会检测到推送并自动部署。连接后的首次部署由仪表板本身执行；之后的推送都会自动触发部署。

  2. 如果尚未连接 — 有两种方式：

    • 为后续提交启用推送即部署（推荐）。告知用户打开 Webflow 仪表板 → 自己的 Cloud 应用 → Settings → Git，连接仓库并选择分支。仪表板会自动执行首次部署，以验证连接。从此以后，向该分支执行的每次 git push 都会触发部署。
    • 立即进行一次手动部署，不启用推送即部署。传入与 webflow.json 中 siteId 匹配的 --site-id： 
      webflow apps deploy \
  --no-input \
  --site-id site_abc123 \
  --mount / \
  --environment main \
  --skip-mount-path-check \
  --skip-update-check
      这会部署当前状态，但不会配置推送即部署。下一次 git push 在 Webflow 端仍然不会执行任何操作。

如果出现部署身份验证错误：运行 webflow auth login，完成浏览器流程，然后重试。

工具使用
  • 所有 webflow apps / webflow cloud 命令都使用 Bash 工具
  • 使用 Read 工具检查 webflow.json、package.json — 不要直接修改这些文件
  • 使用 Glob 工具查找项目文件
  • 不要将 Webflow MCP 工具用于 CLI 工作流
身份验证
# Interactive — local-only, opens a browser. NOT for agents or CI.
webflow auth login

webflow auth login 会在用户的浏览器中执行 OAuth 流程，然后将令牌写入 .env。使用 --no-input 时，该命令会拒绝运行（并退出，提示 No-input mode enabled. Aborting OAuth authentication）。Agent 无法执行此命令。 如果需要运行 webflow auth login（令牌缺失或已过期），请让用户在本地运行一次，并在完成后告知你。

CLI 在两种模式下都会写入相同的令牌环境变量，不会针对不同模式分别设置。

webflow auth login 会写入 .env：

变量始终写入？描述
WEBFLOW_API_TOKEN是（两种模式下均会写入）OAuth 访问令牌。规范的令牌环境变量。由 webflow auth login 设置。
WEBFLOW_SITE_ID仅限绑定站点的项目（或首次部署项目应用后）站点 ID。对于绑定站点的项目，由 apps init 写入；对于项目应用，在首次部署配置站点后，由 apps deploy 写入。

首次部署项目应用后，CLI 会在后端配置一个站点，并将 WEBFLOW_SITE_ID 写入 .env。从那时起，该项目的行为就与绑定站点的项目相同，但令牌环境变量仍为 WEBFLOW_API_TOKEN。

已弃用的旧变量： WEBFLOW_SITE_API_TOKEN（以及 WEBFLOW_WORKSPACE_API_TOKEN）是只读的旧版回退变量。CLI 不会写入这些变量；但如果未设置 WEBFLOW_API_TOKEN，且发现环境中设置了其中一个变量，就会使用旧版变量的值，并且每次运行都会打印弃用警告。新项目不要将 WEBFLOW_SITE_API_TOKEN 写入 .env 或 CI 密钥，应使用 WEBFLOW_API_TOKEN。

其他环境变量（适用于任何模式）：

变量描述
DO_NOT_TRACK设置为 1 可选择退出遥测。
WEBFLOW_SKIP_UPDATE_CHECKS设置为 true 可跳过 @webflow package 更新检查。

WEBFLOW_SITE_ID 环境变量为只读。 如果未设置标志或清单值，它会在运行时使用，但不会写回 webflow.json。在 .env 中设置 WEBFLOW_SITE_ID=X 不会更新清单——只有 apps init、apps deploy 和清单本身可以设置该值。

GitHub Secrets： 在所有模式下，令牌都使用 WEBFLOW_API_TOKEN。对于绑定站点的项目，以及已完成首次部署的项目应用，还应设置 WEBFLOW_SITE_ID。切勿提交 .env 文件。如果现有 CI 使用 WEBFLOW_SITE_API_TOKEN，请将其重命名——部署仍会成功，但在切换之前，每次运行都会打印弃用警告。

配置 — webflow.json
{
  "siteId": "site_abc123",
  "cloud": {
    "app_id": "app_xyz",
    "environment_id": "env_xyz",
    "workspace_id": "ws_xyz",
    "framework": "nextjs",
    "skipMountPathCheck": false
  }
}

所有 cloud.* 键均采用 snake_case（app_id，而非 appId）。

键设置时机说明
siteId关联站点的应用：在 apps init 时。项目应用：首次部署后（CLI 会配置一个站点）。尚未部署的项目应用中不存在此项。
cloud.framework在 apps init 时。部署解析必需 — 见下文。
cloud.app_id首次部署后。规范字段。 自动写入。取代旧版 cloud.project_id。
cloud.project_id仅旧版使用。已弃用。 当 cloud.app_id 不存在时，作为回退值读取（适用于 Project → App 更名之前创建的清单）。新部署不再写入此字段；未来的主版本中将移除。
cloud.environment_id首次项目应用部署后。由 createCloudApp 自动写入。
cloud.workspace_id在项目应用的 apps init 时（--new）。首次部署时用于配置站点。
cloud.skipMountPathCheck由用户管理。等同于 --skip-mount-path-check。

CLI 还会在构建时将 cloud.deployment_type（"ssr" | "ssg" | "spa"）、cloud.entrypoint_path 和 cloud.framework_version 写入打包后的 webflow.json（这些字段供 cosmic deployer 的 wrangler 配置和遥测使用）。它们是构建时输出 — 如果在源 webflow.json 中发现这些字段，请勿将其删除；缺少这些值会导致 Next.js 服务端部署静默失败。

ID 解析与环境变量

共享解析器会按严格的优先级顺序解析 siteId、appId、environmentId 和 workspaceId：

explicit flag / positional arg  >  env var  >  webflow.json manifest  >  interactive prompt  >  error
资源标志 / 参数环境变量（只读）webflow.json
App ID--app-id / [appId] 参数WEBFLOW_APP_IDcloud.app_id（回退到旧版 cloud.project_id）
环境 ID--environment-id / [envId] 参数WEBFLOW_APP_ENVIRONMENT_IDcloud.environment_id
Site ID--site-idWEBFLOW_SITE_IDsiteId
Workspace ID--workspace-idWEBFLOW_WORKSPACE_IDcloud.workspace_id

环境变量为只读，永远不会被写回清单文件。当值来自清单文件时，CLI 会记录一行 Using <resource> from webflow.json（使用 --json 时会抑制此信息）。如果没有解析到值，且命令无法提示用户（--no-input、CI=true 或没有 TTY），则会以错误中可供机器读取的 missingFlag 退出；请参阅管理应用中的 --no-input 约定。

部署时解析 cloud.framework：

  1. 存在包含 cloud.framework 的 webflow.json — 按原值使用。值无效时以代码 1 退出。
  2. 存在 webflow.json，但没有 cloud.framework — 回退到从 package.json 检测。
  3. 不存在 webflow.json — 自动从 package.json 检测。成功后，CLI 会写入新的 webflow.json。

通过 apps init 创建的项目始终属于情况 1。

命令
webflow cloud list
webflow cloud list

列出可用的脚手架模板（供 init 使用）。在执行 apps init --framework 前检查此列表，以确认有效的脚手架 ID。此命令不同于 apps list（后者会列出已部署的应用），且仅位于 cloud 命名空间下。该命令已弃用，即将移除——目前仍可使用，但会打印警告；建议使用 apps init --framework <bad-value> 或 --help 查看有效的脚手架 ID。

webflow apps init

在本地引导创建新应用。支持两种模式：关联 Site 和 应用。（webflow cloud init 是使用相同标志的弃用别名。）

关联 Site（连接到现有 Webflow Site）：

# Agent / non-TTY — always pass every flag
webflow apps init \
  --no-input \
  --app-name my-app \
  --framework nextjs \
  --mount /app \
  --site-id site_abc123

# Human at a real terminal — interactive prompts will fill in any missing flag
webflow apps init

标志：

标志简写描述
--app-name <name>-n应用名称。必须为 3–39 个字符——CLI 会在初始化和首次部署项目应用时拒绝超出此范围的名称。
--project-name <name>—--app-name 的已弃用别名。仍可使用。
--framework <framework>-f必须与 cloud list 中的脚手架 ID 相匹配。目前支持：nextjs、astro、vite、static（static 仅适用于独立模式——参见框架）。
--mount <path>-m挂载路径（新域名默认为 /，现有站点默认为 /app）。在生成脚手架时替换配置文件中的对应内容。不存储在 webflow.json 中。
--site-id <id>-s在非交互式站点关联模式下必需。不能与 --workspace-id 同时使用。
--workspace-id <id>-w在 --new（应用模式）下跳过工作区选择器。不能与 --site-id 同时使用。
--new—项目应用模式（不关联站点）。
--no-input—CI 模式。需要 --app-name 和 --framework。如果没有 --new，则默认为应用行为。

--no-input 站点关联模式下的凭据解析顺序：--site-id 标志 → webflow.json 中的 siteId → WEBFLOW_SITE_ID 环境变量 → 报错。

生成站点关联项目的脚手架后，CLI 会自动运行 DevLink 同步。

项目应用（不关联站点）：

# Agent / non-TTY — always pass --workspace-id to skip the workspace picker
webflow apps init --new --no-input \
  --app-name my-app \
  --framework nextjs \
  --workspace-id ws_abc123

# Human at a real terminal — prompts for workspace if not passed
webflow apps init --new

如果令牌可访问多个工作区，而 Agent 没有工作区 ID，请让用户在项目目录中以交互方式运行 webflow apps deploy——预检提示会选择一个工作区，并将 cloud.workspace_id 写入 webflow.json，供后续由 Agent 驱动的运行使用。Webflow 控制面板 UI 不会显示工作区 ID，因此交互式 CLI 运行是获取该 ID 唯一实用的方法。

站点关联项目应用（--new）
OAuth / 站点选择初始化时必需跳过（改为选择工作区）
.env 中的 WEBFLOW_SITE_ID初始化时写入仅在首次部署后写入
.env 中的 WEBFLOW_API_TOKEN写入写入
webflow.json 中的 cloud.workspace_id不设置初始化时设置（首次部署时使用）
脚手架astro、nextjs、viteastro、nextjs、vite、static
挂载路径可配置（默认为 /app）始终为 /
DevLink 同步初始化后运行跳过
**工作区选择（仅限 project-app 模式）：**如果未传入 --workspace-id，CLI 会调用 GET /v2/workspaces，列出令牌有权访问的工作区。只有一个工作区时会自动选中；有多个工作区时则会显示交互式选择器。传入 --workspace-id 后会跳过 API 请求，CLI 会信任该标志；如果 ID 无效，稍后会通过 createCloudApp 返回 404。选中的 ID 会作为 cloud.workspace_id 持久化到 webflow.json 中。

**Agent 注意事项：**如果用户的令牌可访问多个工作区，而 Agent 无法传入 --workspace-id，选择器就会启动，并在非 TTY 环境中挂起。Webflow 仪表板界面不会显示工作区 ID，因此解决方法是：**请用户在项目目录中交互式运行一次 webflow apps deploy。**预检提示会让用户选择工作区、完成首次部署，并将 cloud.workspace_id（以及 siteId、app_id、environment_id）写入 webflow.json。之后，Agent 可以从清单中读取工作区 ID，并在后续运行时传入 --workspace-id（或者在站点创建后传入 --site-id）。若之后要部署到其他工作区，请删除 cloud.workspace_id，并让用户再次交互式部署。

webflow apps init --import <repo-url>（仅限 apps）

从现有 GitHub 仓库创建 Cloud 应用，并将其克隆到本地，而不是使用起始模板。此路径用于接入已存在于 GitHub 上的代码库——不会生成脚手架，也不会选择框架。

**此标志仅适用于 apps init。**有意不提供 cloud init --import：仓库接入路径会创建真正的应用，因此仍归属规范命名空间，而不是已弃用的别名。

**前提条件：**必须在仓库上安装 **Webflow GitHub App，并将其连接到你的工作区。**如果未完成，创建操作就会失败——CLI 无法替你安装该应用；此项设置必须在仪表板中完成。

Flag说明
--import <repo-url>https://github.com/<owner>/<repo。不能为空。
--site-id <siteId>关联到现有站点。不能与 --new 同时使用，且必须指定其中一个。
--new创建项目应用，而不是关联到站点。
--mount <path>使用 --site-id 时必填（且不能是根路径）。不能与 --new 同时使用——项目应用拥有自己域名的根路径，因此始终挂载在 /。
--branch <branch>要构建的分支。默认为仓库的默认分支。
--idempotency-key <key>非交互式运行（CI、--no-input）时必填。请使用对重试稳定且对该仓库和目标唯一的键，例如 $GITHUB_RUN_ID-$REPOSITORY-$SITE_ID，这样重试会重放原始应用，而不是创建第二个应用。
--skip-clone创建应用但不在本地克隆。不会写入文件系统；而是打印应用和环境 ID。
--json仅适用于导入路径——脚手架路径没有可序列化的单一响应对象。
--dry-run与脚手架路径共用：验证并预览，不产生副作用。

即使仓库中存在 siteId，也绝不会用它来选择目标——必须明确指定 --site-id 或 --new。

如果未指定 --import，则导入专用标志（--branch、--idempotency-key、--skip-clone、--json）会被拒绝，而非忽略；同样，使用 --import 时会拒绝 --framework / --workspace-id / --project-name（仓库会携带自己的代码，工作区则根据令牌确定）。每次拒绝都会通过 missingFlag 以机器可读的方式指出不兼容的标志，因此 Agent 无需解析说明文字即可修正调用。

# Attach an existing repo to an existing site at /app
webflow apps init --import https://github.com/acme/site \
  --site-id 6234abc --mount /app --dry-run

webflow apps init --import https://github.com/acme/site \
  --site-id 6234abc --mount /app

# Project app from a repo, CI-safe (note: --idempotency-key required, no --mount)
webflow apps init --import https://github.com/acme/site --new --no-input \
  --idempotency-key "$GITHUB_RUN_ID-acme-site" \
  --branch main --json

# Register the app without touching the local filesystem
webflow apps init --import https://github.com/acme/site --new --skip-clone --json
webflow cloud create（已弃用）

webflow cloud create <name> 仍可使用，但会发出弃用警告，并将在未来的主版本中移除。在关联到站点的模式下，它会将挂载路径硬编码为 /app，且仅提供 apps init 的部分功能。请始终优先使用 apps init（或在应用模式下使用 apps init --new）。

webflow apps deploy

webflow cloud deploy 是 apps deploy 的已弃用别名，标志和处理程序均相同。 预检阶段：身份解析。 在任何后端调用之前，apps deploy 都会运行预检步骤，确定这是站点关联部署还是项目应用的首次部署。解析顺序如下（以第一个匹配项为准）：

#来源结果
1--site-id <id> 标志站点关联部署，优先于环境变量和清单
2--workspace-id <id> 标志项目应用首次部署，优先于环境变量和清单。不能与 --site-id 同时使用
3WEBFLOW_SITE_ID 环境变量站点关联部署（只读；不会写回 webflow.json）
4manifest.siteId（来自 webflow.json）站点关联部署
5WEBFLOW_WORKSPACE_ID 环境变量项目应用首次部署（只读；不会持久化）
6manifest.cloud.workspace_id项目应用首次部署
7无匹配项 + --no-input硬错误，列出必需的标志
8无匹配项，交互模式选择器：创建新应用 / 关联现有站点 / 取消

环境变量优先于清单，站点优先于工作区。 两方面都很重要：已导出的 WEBFLOW_SITE_ID 会覆盖 manifest.siteId，而且一旦解析出站点，就不会再尝试解析工作区——因此，环境中残留的 WEBFLOW_SITE_ID 会悄然优先于配置为项目应用部署的清单。如果这不是你想要的结果，请取消设置该变量，或显式传入 --workspace-id。

此预检阶段旨在防止项目应用部署路径在身份确定之前运行并创建 Cloud 应用——早期版本可能会在后续步骤失败时留下一个孤立的 Webflow 站点。

尽可能显式传入 --site-id 或 --workspace-id。 这能避免清单只写入了一部分的情况，也能避免依赖 apps init 留下的状态。若用户需要站点关联部署，请传入 --site-id。若要进行项目应用首次部署，请传入 --workspace-id。

项目应用首次部署（由 --workspace-id 标志或 manifest.cloud.workspace_id 触发）会调用 POST /cosmic/workspaces/:workspace_id/cloudApps，以原子方式创建站点、应用和环境。成功后，它会将 siteId、cloud.app_id 和 cloud.environment_id 写入 webflow.json，将 WEBFLOW_SITE_ID 写入 .env，并在此次部署中强制使用 --skip-mount-path-check。后续部署的行为与常规站点关联部署相同。

如果项目应用首次部署时未指定 --app-name，CLI 会使用当前工作目录文件夹名称（长度为 3–39 个字符时），否则使用 "Cloud App"。在 CI 中请显式指定 --app-name，以免出现意外。

未初始化的项目（没有 siteId、workspace_id 或标志）：CLI 会提示用户创建新的项目应用、关联现有站点或取消。使用 --no-input 时会触发硬错误并列出必需的标志。使用 --no-input 运行的 Agent 在未初始化项目的首次部署时，必须始终提供 --site-id 或 --workspace-id。

有两种部署方式。推荐使用 GitHub 关联部署——它不需要配置 CI。完成一次性仪表板设置（CLI 无法执行）后，连接分支上的每次推送都会触发部署。

选项 1（推荐）：GitHub 关联部署 完成一次性仪表板设置后，推送到已连接分支的每次提交都会触发部署——无需 CLI 命令，也无需工作流文件。**此设置只能在仪表板中完成——CLI 无法独自完成此操作。**仅将代码库推送到 GitHub 并不会自动启用推送部署。

  1. 将项目推送到 GitHub（用户至少需要推送一次提交）
  2. 告知用户打开 Webflow 仪表板 → 他们的 Cloud 应用 → Settings → Git，如果尚未连接 GitHub 帐户，则连接该帐户
  3. 选择代码库，然后选择要部署的分支（例如 main）
  4. 确认——仪表板会自动运行初始部署，以验证连接
  5. 此后：向已连接的分支执行 git push = 部署

步骤 2–4 无法通过脚本完成。如果用户想要推送部署，就必须在仪表板中手动点击完成一次。之后，该项目的 Agent 基本上就完成任务了——后续部署会在推送时自动进行。

向用户建议部署设置时，始终优先推荐此选项。只有当用户需要原生 GitHub 集成不支持的自定义前置／后置步骤、密钥注入或多环境逻辑时，才建议使用 GitHub Actions。

选项 2：GitHub Actions（手动 CI/CD）

当你需要自定义构建步骤、特定环境的密钥，或原生 GitHub 集成不支持的部署门控时使用。请参阅示例部分中的 GitHub Actions 示例。

选项 3：本地／手动部署

用于开发和临时部署：

webflow apps deploy \
  --no-input \
  --mount / \
  --environment main \
  --skip-mount-path-check \
  --skip-update-check

所有 apps deploy 标志：

标志简写描述
--no-input—CI 模式。禁用大多数提示，但不会禁用项目选择提示——见下方说明。
--mount <path>-m挂载路径。**务必与 --no-input 一起传入——不会强制要求。**省略此项不会报错；系统会静默地部署到根路径（/）。不会自动从 webflow.json 中读取。见下方警告。
--environment <env>-e环境名称。如果不存在则创建。必须与 --mount 一起传入。
--app-name <name>-n使用 --no-input 首次部署，且 webflow.json 中没有 cloud.app_id 时必填。项目应用首次部署时，长度必须为 3–39 个字符。
--project-name <name>—--app-name 的已弃用别名。仍可使用。
--site-id <id>-s用于关联站点的部署的 Webflow 站点 ID。会覆盖 webflow.json 中的 siteId。不能与 --workspace-id 同时使用。可用于在不编辑 JSON 的情况下，从写入不完整的清单中恢复。
--workspace-id <id>-w用于项目应用首次部署的工作区 ID。会覆盖 webflow.json 中的 cloud.workspace_id。不能与 --site-id 同时使用。
--app-id <id>-aCloud 应用 ID。跳过应用选择器。会覆盖 webflow.json 中的 cloud.app_id。
--project-id <id>—--app-id 的已弃用别名。仍可使用。
--framework <fw>-f覆盖框架检测结果。必须为 nextjs、astro、vite 或 static。会将该值写回 webflow.json。当根据 package.json 自动检测不可靠时（如单体仓库、缺少依赖等），可使用此项。
--directory <path>-d应用目录（默认值：cwd）。用于单体仓库。
--description <text>—首次部署时的应用描述。
--skip-mount-path-check—跳过域名清单验证。CI 中必需。也可在 webflow.json 中设置为 cloud.skipMountPathCheck: true。
--auto-publish—发布 Webflow 站点以同步挂载路径路由。不影响应用部署。
--skip-update-check—跳过 @webflow 软件包更新检查。
--dry-run—**仅适用于 apps deploy——不适用于 cloud deploy 别名。**从标志、环境变量和 webflow.json 中解析所有信息，不进行网络调用，并报告实际运行将执行 create、select 还是 deploy。
--json—**仅适用于 apps deploy——不适用于 cloud deploy 别名。**输出单个文档，而非构建/上传进度文本：成功时输出 {appId, environmentId, deploymentId, deployUrl}（较旧的后端中 deployUrl 为 null）；失败时输出错误文档；与 --dry-run 一起使用时则输出试运行计划。
# Preview what a deploy would do, no side effects
webflow apps deploy --no-input --mount /app --environment main --site-id site_abc123 --dry-run --json

# Deploy and parse the result instead of scraping progress output
webflow apps deploy --no-input --mount /app --environment main --site-id site_abc123 --json

Agent：每次都要同时传入 --mount 和 --environment。 部署提示（选择现有应用、为新应用命名、选择环境）是否出现，取决于是否_同时_设置了 --mount 和 --environment，而非是否设置了 --no-input。如果不同时传入这两个参数就使用 --no-input，应用选择提示仍会出现，并在非 TTY 环境中卡住。对 Agent 安全的最低部署参数集为 --no-input --mount <path> --environment <env> --site-id <id>（如果是项目应用的首次部署，则使用 --workspace-id <id>），此外，当 webflow.json 中没有 cloud.app_id 时，还要传入 --app-name。

⚠️ 在 --no-input 下省略 --mount 会静默部署到根目录。 这是部署错误风险，而非硬性失败——不会报错，也不会警告。挂载提示提供了 /app 默认值，但没有验证器；而无输入路径只会返回通过验证的默认值；没有验证器时，则什么都不返回，随后会被规范化为 /。根目录是有效挂载点，因此部署会继续执行。在非交互式运行中，绝不要依赖 /app 默认值——每次都要显式传入 --mount。这也是为什么下文将“假定使用默认挂载点”列为 ENVIRONMENT_MOUNT_MISMATCH 的一个原因：失败会在稍后、不同的层级显现，与导致问题的参数相距甚远。

管理应用

用于检查和操作现有 Cloud 应用的命令。它们与 init / deploy 互为补充：

  • 工作区位于服务端。 每条读取命令都从 OAuth 令牌中获取工作区——它们都没有 --workspace-id 参数，也绝不会提示选择工作区。

  • ID 解析。 appId 和 envId 通过共享解析器解析：显式参数/标志 → 环境变量（WEBFLOW_APP_ID / WEBFLOW_APP_ENVIRONMENT_ID）→ webflow.json（cloud.app_id / cloud.environment_id，旧版 cloud.project_id 作为回退）→ 交互式 TTY 提示。在应用目录中运行（以便通过 webflow.json 解析 ID）是常见做法，但不是必需条件。

  • 自动选择与 --no-input 约定。 未提供 ID 时，选择器会自动选择工作区中唯一的应用，或应用中唯一的环境，因此单应用/单环境配置可在非交互模式下运行（包括 CI）。如果存在多个选项，且命令无法提示（--no-input、CI=true、没有 TTY 或使用 --json），命令会以非零状态退出，并在错误中提供机器可读的 missingFlag，让 Agent 可以通过重新运行命令并传入该标志来恢复。人类可读形式例如：Missing required appId. Pass --app-id, set WEBFLOW_APP_ID, or add it to webflow.json.

    missingFlag 有两种形式——两种都要匹配。 解析器错误使用裸键（appId、environmentId、depId、yes）；apps init 上的标志兼容性拒绝则使用标志写法（--import、--site-id、--mount、--new）。匹配前请先规范化（去掉前导 --，并忽略大小写），不要假定只有一种形式。两种情况下，该值都表示要添加或移除的标志——对于互斥标志对，它表示要移除的那个，因此如果按错误提示添加标志后重试，就会陷入无限循环。

  • --json。 每条命令都支持 --json，会输出原始 API 响应并忽略 --fields。可用它进行程序化解析。--json 也会抑制 Using … from webflow.json 信息行。

  • --fields <comma-list>。 读取命令会渲染表格；--fields 用于指定显示哪些列（无效字段名会在网络请求前立即报错）。下文列出了每条命令的默认字段和完整字段集。

筛选语义（list 命令）

apps list、apps environments list 和 apps env-vars list 使用同一套筛选模型：

  • 精确筛选（--name、--branch、--key、--site、--status）进行精确且区分大小写的匹配。
  • --q 仅对相应资源的主要名称字段进行不区分大小写的子串（包含）匹配——应用名称、环境分支或变量键。它不会搜索 ID，也不会搜索变量值。用它来发现项目；用精确筛选来定位单个项目。
  • 多个筛选条件以 AND 组合。 精确筛选条件与不匹配的 --q 一起使用时，会返回空页面——这表示没有项目满足所有筛选条件，并不表示资源不存在。 不要仅凭筛选后的空页面就断定应用或变量不存在；在报告其不存在之前，请使用更少的筛选条件重新运行。
  • 每个筛选值都必须非空（--q "" 属于用法错误，而不是不执行任何操作）。
apps list

列出工作区中的所有应用。--fields 默认值为 id,name,siteId,createdAt（全部字段：id,name,description,siteId,appPath,sourceUrl,createdAt,siteName,shortName）。

筛选条件：--site <site-id>（精确匹配站点 ID）、--name <name>（精确且区分大小写）、--q <text>（对应用名称进行不区分大小写的子串匹配）。

应用名称仅在同一站点内唯一。 单独使用 --name 可能会匹配多个站点中的应用，而单独使用 --site 可能会匹配多个应用——请同时传入 --site 和 --name，以将结果限定为至多一个应用。

--site 不会默认从 webflow.json 获取：不带筛选条件的 apps list 会返回令牌可见的所有应用，而不会悄悄缩小到清单文件中指定的站点。

webflow apps list --json

# Resolve one app by name within a known site
webflow apps list --site 6234abc --name "Marketing" --json

# Discover apps whose name contains "mark" (case-insensitive)
webflow apps list --q mark --json
apps get [appId]

获取单个应用的详情。appId 默认为 webflow.json / WEBFLOW_APP_ID。--fields 默认值为 id,name,description,siteId,appPath,createdAt（全部字段：id,name,description,siteId,appPath,sourceUrl,createdAt,siteName,shortName——与 apps list 的字段集相同）。sourceUrl 是已连接的 GitHub 仓库（如有；请参阅 apps update --github-source）。

webflow apps get app_abc123 --json
apps domains [appId]

获取应用的域名和线上 URL。--fields 默认值为 id,url,lastPublished（全部字段另加 fullSiteCompiledAt）。

支持分页：--limit <n>（服务端上限为 100）以及从之前的 nextCursor 获取的 --cursor <cursor>。分页时，每一页都要重新传入相同的 --limit 和所有非默认的 --fields。

webflow apps domains app_abc123 --json
webflow apps domains app_abc123 --limit 50 --cursor "$NEXT_CURSOR" --json
apps environments list [appId]

列出应用的环境。--fields 默认值为 id,branch,publicUrl,latestDeploymentStatus,createdAt（全部字段：id,branch,mount,publicUrl,latestDeploymentStatus,lastDeploymentSucceededAt,lastVariableModifiedAt,createdAt,updatedAt）。

表格默认字段不包含 mount。 要读取环境的挂载路径，可以使用 --json（它会返回完整的 API 结构，并忽略 --fields），也可以通过 --fields id,branch,mount 显式指定。默认的 environments list 表格不会显示该字段。

筛选条件：--branch <branch>（精确且区分大小写——由于分支在单个应用内唯一，因此最多匹配一个环境）和 --q <text>（对分支进行不区分大小写的子串匹配，用于发现项目）。

webflow apps environments list app_abc123 --json

# Resolve the environment that builds `main`
webflow apps environments list --branch main --fields id,branch,publicUrl --json
apps deployments list

列出某个环境最近的部署，按从新到旧排序。不接受 appId 参数——它会从 WEBFLOW_APP_ID / WEBFLOW_APP_ENVIRONMENT_ID、webflow.json 或选择器解析应用和环境。--limit 默认为 20。--fields 默认为 id,status,sourceType,commitHash,buildStartedAt。

筛选：--status <status>（精确匹配以下枚举值之一——如果值无效，CLI 会在发起任何网络请求前拒绝）。通过上一次响应中的 nextCursor 使用 --cursor 分页；每一页都要重新传入相同的 --limit、--status 和非默认的 --fields。

webflow apps deployments list --limit 20 --json

# Most recent failed build
webflow apps deployments list --status failed --limit 1 --json

部署状态枚举： starting | building | deploying | success | failed | canceled | unstaged。请注意，构建完成／部署进行中对应 deploying（只有达到 success 后，才算部署成功；没有单独的“已部署”状态）。终态包括 success、failed、canceled 和 unstaged。

apps deployments get <depId>

查看单个部署的详细信息（必须提供位置参数 <depId>）。与 deployments list 一样解析应用和环境。--fields 默认为 id,status,sourceType,commitHash,buildStartedAt。

--wait 会阻塞，直到部署达到终态（success / failed / canceled / unstaged）或超时，然后成功时退出码为 0，否则为 1——因此无需自行编写轮询循环，即可将其用作 CI 检查门禁。--interval <seconds> 设置轮询间隔（最低为 5s），--timeout <seconds> 限制等待时长（最长为 30 分钟）。

webflow apps deployments get dep_abc123 --json

# Block until the build finishes; non-zero exit fails the CI step
webflow apps deployments get dep_abc123 --wait --interval 10 --timeout 900 --json
apps deployments redeploy <depId>

在相同的提交上重新运行现有部署，并排入一个新的构建。**如需回滚，请重新部署较早的成功部署 ID。**与 deployments list 一样解析应用和环境。--dry-run 可预览操作。

**需要连接到 GitHub 的应用。**通过 apps deploy 从本地文件部署的应用不符合条件——没有可重新运行的提交。

--idempotency-key <key> 会发送 Idempotency-Key 标头，以便对重试的入队请求去重，避免排入第二次构建。传入的值必须是非空的可打印 ASCII 字符（不能包含控制字符、换行符或非 ASCII 字符）；如需不去重地运行，请完全省略此标志。

**--wait（与 deployments get --wait 的行为相同）。**排入构建只会返回 202，不会返回可供轮询的部署 ID，因此 --wait 会先通过对比入队前后的环境部署列表，找到新部署，然后阻塞等待其达到终态；成功时退出码为 0，否则为 1。--interval <seconds>（最低为 5s）和 --timeout <seconds>（最长为 30 分钟）用于调整轮询，行为与 get 相同。使用此选项，可通过一条命令根据重新部署的结果设置 CI 门禁，无需先排入构建，再单独轮询 deployments get。

webflow apps deployments redeploy dep_abc123 --dry-run --json
webflow apps deployments redeploy dep_abc123 --idempotency-key "$GITHUB_RUN_ID-redeploy" --json

# Roll back and block until the new build finishes; non-zero exit fails the CI step
webflow apps deployments redeploy dep_abc123 --wait --interval 10 --timeout 900 --json

# Roll back: find the last success, then redeploy it
webflow apps deployments list --status success --limit 1 --fields id --json
apps deployments trigger

按需构建所解析环境的当前 HEAD——与 redeploy 相同，但不需要 <depId>：没有先前的部署可供重新运行，它只会构建环境当前配置的分支所指向的内容。--dry-run 可预览操作。--idempotency-key 的行为与 redeploy 相同。

需要连接到 GitHub 的应用，与 redeploy 相同。

它构建的是环境配置的分支，而不是你当前检出的分支。如果二者不同，CLI 会发出警告，但不会阻止操作——如果不确定实际会构建哪个分支，请先检查 apps environments list --fields id,branch。

--wait / --interval / --timeout 的行为与 redeploy 和 deployments get 相同——由于 trigger 也只会返回 202，--wait 会先找到排入队列的部署，再轮询直到其达到终态。

webflow apps deployments trigger --dry-run --json
webflow apps deployments trigger --json

# Build current HEAD and block until it finishes; non-zero exit fails the CI step
webflow apps deployments trigger --wait --interval 10 --timeout 900 --json
apps logs build <depId>

查看部署的构建日志。必须提供 depId——CLI 不会回退到最新部署。省略该参数会立即失败（在身份验证之前），并返回机器可读的 missingFlag: "depId"；请先运行 apps deployments list 查找 ID。--fields 默认为 timestamp,message（全部字段：timestamp,message,phase）。

筛选条件：--since <iso>（仅显示指定 ISO 日期时间及之后的日志）、--q <substr>（按消息进行子字符串匹配）、--limit <n>（默认为 100）、--cursor <cursor>（来自上一次响应中 nextCursor 的分页游标）。没有 --level 筛选条件。分页时，每一页都要重新传入相同的 --limit、非默认的 --fields、--since 和 --q。

# Find a deployment ID first — `logs build` will not guess one
webflow apps deployments list --limit 1 --fields id --json

webflow apps logs build dep_abc123 --since 2026-07-14T00:00:00Z --q error --limit 100 --json
apps logs runtime [envId]

查看某个环境的运行时日志。[envId] 默认为应用的唯一环境。如果应用有多个环境且未指定环境，CLI 会在 TTY 中提示选择；无法提示时则会报错并返回 missingFlag: "environmentId"（例如使用 --no-input、CI=true、没有 TTY 或使用 --json 时）——此时请显式传入 env（通过参数、WEBFLOW_APP_ENVIRONMENT_ID 或 cloud.environment_id）。筛选条件与 logs build 相同（--since、--q、--limit、--cursor；没有 --level），并且分页时也必须在每一页重新传入这些参数。

webflow apps logs runtime env_abc123 --q timeout --json

这两个日志命令都支持分页：响应中包含 nextCursor（base64url；没有更多结果时为 null）。将其原样通过 --cursor 传回，即可获取下一页。

apps env-vars

以非交互方式管理 Cloud 应用环境变量。所有四个子命令都接受 --app-id 和 --environment-id（默认通过共享解析器从 webflow.json 获取），以及 --json。绝不会在输出、日志或遥测中打印密钥值——服务器在每次读取时都会对密钥进行掩码处理，CLI 也绝不会解除掩码。

apps env-vars list — --fields 默认为 key,isSecret（全部字段：key,isSecret,value,id,environmentId）。默认不包含 value；即使使用 --fields value，密钥值仍会被掩码。

筛选条件：--key <key>（区分大小写的精确匹配——最多匹配一个变量；仍不会返回其值）和 --q <text>（对键进行不区分大小写的子字符串匹配）。--q 绝不会搜索值——按设计，无法搜索环境变量的内容。

webflow apps env-vars list --json

# Check whether one key is set, and whether it's a secret
webflow apps env-vars list --key API_KEY --json

apps env-vars set <key> [value] — 创建或更新一个变量。[value] 为可选参数：省略后，可从管道标准输入读取或通过提示输入（建议用于密钥，以免内容留在 shell 历史记录中）。--secret 会加密该值（省略时会保留该键已有的密钥属性）。--dry-run 可预览但不写入。

webflow apps env-vars set API_URL https://api.example.com --json
# secret — value read from stdin/prompt, never echoed:
printf '%s' "$TOKEN" | webflow apps env-vars set API_KEY --secret --json

apps env-vars delete <key> — 删除一个变量。--dry-run 可预览。

webflow apps env-vars delete API_KEY --json

apps env-vars import <file> — 从 .env（KEY=value）文件批量新增或更新变量。--secret 会将文件中的所有键标记为密钥。--dry-run 可预览（值会显示为 KEY=********，绝不显示明文）。每个键的失败情况都会报告，并导致非零退出状态。

webflow apps env-vars import .env.production --secret --json
apps environments create [appId]

在应用上创建一个环境，并将其绑定到一个分支，且通过挂载路径提供服务。必须提供 --branch 和 --mount。--dry-run 可预览。

此命令不会部署——环境创建后为空。 随后运行 apps deployments trigger 以构建该环境。

  • --branch <branch> — 此环境用于构建的 Git 分支。必须是有效的分支名称，且未被此应用的其他环境使用。
  • --mount <path> — 环境提供服务时使用的 URL 路径（例如 /app）。在整个站点中必须唯一。
  • --idempotency-key <key> — 可选的重试稳定键（作为请求的 requestId 发送），用于对重试的创建操作去重。与 deployments redeploy 使用相同的可打印 ASCII 规则。
webflow apps environments create --branch staging --mount /staging --dry-run --json
webflow apps environments create --branch staging --mount /staging --json
webflow apps deployments trigger --json   # the environment is empty until you do this
apps environments update [appId] [envId]

更新环境的 --branch 和/或 --mount（至少需要一个）。唯一性规则与 create 相同。通过位置参数、WEBFLOW_APP_ID / WEBFLOW_APP_ENVIRONMENT_ID、webflow.json 或选择器解析应用和环境；也可以通过显式的 --app-id / --environment-id 标志指定。--dry-run 可预览。

**此命令不会部署。**更改 --branch 后，运行 apps deployments trigger 来构建新分支；在此之前，环境仍会提供旧构建。

webflow apps environments update --branch release --dry-run --json
webflow apps environments update env_abc123 --mount /v2 --json
apps environments delete [appId] [envId]

从应用中删除环境。应用和环境的解析方式与 environments update 相同。需要确认：传入 --yes 可跳过提示；非交互模式下若未传入该标志，命令会因 missingFlag: "yes" 而拒绝删除。--dry-run 可预览。

webflow apps environments delete env_abc123 --dry-run --json
webflow apps environments delete env_abc123 --yes --json
apps link [appId]

通过写入 webflow.json，将当前目录指向现有应用和环境。此命令会验证应用，但不会创建或部署任何内容——可用于从全新克隆中接入应用，或将目录重新指向其他应用/环境。--dry-run 可预览清单变更。

位置参数 [appId] 的优先级高于 --app-id、WEBFLOW_APP_ID 和 webflow.json。--environment-id 用于选择环境。

只有显式传入 --workspace-id 时，才会保存工作区 ID——无法从应用推导或验证该 ID，因此 CLI 会按原样写入，不会猜测。

webflow apps link app_abc123 --environment-id env_abc123 --dry-run --json
webflow apps link app_abc123 --environment-id env_abc123 --json
apps update [appId]

更新应用的 --name、--description 和/或 --github-source（至少需要一个）。--dry-run 可预览。appId 默认取自 webflow.json / WEBFLOW_APP_ID。

--github-source <repo-url> 可将仓库关联到尚未关联仓库的应用，或将已有应用重新指向其他仓库。传入格式为 https://github.com/<owner>/<repo>，并请注意：

  • **此命令不会部署。**之后运行 apps deployments trigger，从新关联的仓库进行构建。
  • 需要在仓库所有者的账号中安装 Webflow GitHub App，并将其连接到此工作区——这与 apps init --import 的前提相同。
  • 若要更改环境构建的分支，请使用 apps environments update --branch，而不是此标志。--github-source 用于选择仓库；环境用于选择分支。

--json 输出：在 --dry-run 时输出计划——仅包含实际要更改的键，以及 dryRun: true——因此仅更新名称的计划完全不会包含 githubSource 键（而不是设为 null）；实际运行时则输出完整的更新后应用对象（结构与 apps get --json 相同）。

webflow apps update app_abc123 --name "New Name" --description "Marketing site app" --json

# Attach a repo, then build it
webflow apps update app_abc123 --github-source https://github.com/acme/site --json
webflow apps deployments trigger --json
apps delete [appId]

删除（或归档——由服务端根据站点类型决定）应用。需要确认：传入 --yes 可跳过提示。非交互模式（--no-input / --json）下若未传入 --yes，命令会因 missingFlag: "yes" 而拒绝删除。--dry-run 可预览影响，但不会执行删除。

--json 输出：无论是试运行还是真实运行，输出文档结构都相同——{ appId, name, action: "archive" | "hard_delete", siteId, siteName, permanent, dryRun, message }——因此两种情况都可由同一个解析器处理。试运行会先读取应用，以填充 name / siteId / siteName / action / permanent；真实的 --json 运行始终需要 --yes（见上文），并会完全跳过读取，因此真实运行时 name、siteId 和 siteName 始终为 null，而 action 则取自删除响应本身。试运行时 message 为 null，实际完成删除后才会填充。

webflow apps delete app_abc123 --dry-run --json
webflow apps delete app_abc123 --yes --json
框架
框架初始化脚手架部署支持通过软件包检测
nextjs✓（独立 + 关联站点）✓@opennextjs/cloudflare
astro✓（独立 + 关联站点）✓@astrojs/cloudflare
vite✓（独立 + 关联站点）✓vite
static✓（仅独立）✓不适用 — 见下文

cloud.framework 中的任何其他值都会导致 apps deploy 以代码 1 退出。

static 只会生成独立应用的脚手架 — apps init --new --framework static 可用；apps init --site-id ... --framework static（关联站点）不可用，因为没有关联站点的静态脚手架。对于现有静态项目（已构建或手写），部署时检测无需脚手架：根目录中有 index.html 且没有 package.json 的目录会被自动检测为静态项目（仅资源，无构建、无 worker）；在 webflow.json 中显式指定 { "cloud": { "framework": "static" } } 也会选择静态项目，即使存在构建/运行时文件，该设置始终优先。如果目录中有 index.html 以及构建/运行时标识，但未显式指定 framework，则会被拒绝，而不会猜测 — 请显式声明 cloud.framework 以强制采用某种解释。

脚手架会在初始化时从 GitHub 获取。 CLI 会从 Webflow-Examples/hello-world-{astro,nextjs,vite,static-app}* 下载脚手架压缩包（关联站点的脚手架来自对应的 *-devlink 仓库），每个压缩包都固定到已安装 CLI 所需的带版本号（vN）分支。因此，apps init 需要访问网络以连接 github.com。旧版 CLI 安装仍可正常工作，因为每个版本都会固定到兼容的脚手架分支。

全局标志
标志说明
--no-input禁用所有交互式提示。CI/自动化必需。当 CI=true 或检测不到 TTY 时会自动启用。
--manifest <path>webflow.json 的自定义路径。适用于 monorepo。
--skip-update-check跳过 @webflow 软件包更新检查。也可设置 WEBFLOW_SKIP_UPDATE_CHECKS=true。
--verbose显示更多信息以便调试。

输出

apps deploy 成功后，CLI 会打印两项输出。

1. 部署面板 URL — 成功时始终显示：

https://webflow.com/dashboard/sites/{siteId}/webflow-cloud/projects/{appId}/environments/{environmentId}/deployments/{deploymentId}

始终向用户显示此 URL。用户可在此查看构建日志、部署状态、历史记录和环境设置。

2. 应用实时 URL — 有条件显示：

🌐 Your cloud app will soon be available at:
   https://{your-site}.webflow.io/{mount-path}

如果打印了真实 URL，请将其作为应用实时链接显示给用户。域名是其 Webflow 站点的域名，路径则是部署时使用的 --mount 值（例如 /、/app 或用户选择的其他路径）。之后也可以通过 webflow apps domains --json 以编程方式获取实时 URL。

如果输出内容为 No domains found with the correct mount path configuration yet.，则不要显示实时 URL — 请引导用户通过上方的部署面板链接查看状态并配置域名。

不要获取或 curl 任一 URL 来验证部署 — 只需返回 CLI 打印的内容。若要以编程方式确认状态，请改用 webflow apps deployments list --json 或 webflow apps logs build --json。

示例

完整工作流：搭建脚手架 → GitHub → 连接仪表板 → 推送部署（推荐）

CLI 负责步骤 1 和 2。**步骤 3 必须在 Webflow 仪表板中完成 — CLI 无法执行此操作。**如果不执行步骤 3，推送到 GitHub 并不会触发部署。

# 1. Scaffold locally (CLI)
webflow apps init --new --no-input \
  --app-name my-app \
  --framework nextjs \
  --workspace-id ws_abc123

# 2. Push to GitHub (CLI / git)
git init && git add . && git commit -m "init"
git remote add origin https://github.com/your-org/my-app.git
git push -u origin main

# 3. Connect in the Webflow dashboard (manual, dashboard-only):
#    a. Open the Cloud app → Settings → Git
#    b. Connect the GitHub account (if not already), pick the repo
#    c. Pick the branch to deploy from (e.g. main)
#    d. Confirm — the dashboard runs an initial deploy to verify the wiring
#
# After step 3, every push to the selected branch triggers a deploy automatically.
# Skip step 3 and push-to-deploy is NOT active — deploys must be manual or CI-driven.
项目应用工作流：初始化 → 首次部署时配置站点
# Agent-safe init — assumes the token sees a single workspace.
# If the token sees multiple workspaces, ask the user to run this command locally first.
webflow apps init --new --no-input \
  --app-name my-app \
  --framework astro

# First deploy creates site + app + environment on the backend,
# writes siteId / app_id / environment_id back to webflow.json,
# and writes WEBFLOW_SITE_ID to .env. Subsequent deploys are normal.
cd my-app
webflow apps deploy --no-input \
  --app-name my-app \
  --mount / \
  --environment main \
  --skip-update-check
在本地搭建关联站点的 Astro 应用脚手架
webflow apps init \
  --no-input \
  --app-name my-site-app \
  --framework astro \
  --mount /app \
  --site-id site_abc123
检查现有应用及其最新部署
# Which apps can this token see?
webflow apps list --json

# Details + live URLs for one app (or omit the ID inside the app dir)
webflow apps get app_abc123 --json
webflow apps domains app_abc123 --json

# Most recent deployments (newest first), then drill into one
webflow apps deployments list --limit 5 --json
webflow apps deployments get dep_abc123 --json

# Block until a build reaches a terminal status (exit 0 = success, 1 = not)
webflow apps deployments get dep_abc123 --wait --interval 10 --timeout 900 --json

# Read that deployment's build log, filtered. `logs build` requires the ID —
# it will not fall back to the latest deployment.
webflow apps logs build dep_abc123 --q error --json
管理环境变量
# Non-secret value inline
webflow apps env-vars set PUBLIC_API_URL https://api.example.com

# Secret value piped from stdin (stays out of shell history / logs)
printf '%s' "$DB_PASSWORD" | webflow apps env-vars set DB_PASSWORD --secret

# Bulk import a .env file, all keys secret; preview first
webflow apps env-vars import .env.production --secret --dry-run
webflow apps env-vars import .env.production --secret

# List (secrets shown masked) and delete
webflow apps env-vars list --json
webflow apps env-vars delete OLD_KEY
GitHub Actions CI/CD 流水线（需要自定义步骤时）
name: Deploy to Webflow Cloud

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      # Pin an exact version in CI: the @latest tag moves without notice.
      - name: Install Webflow CLI
        run: npm install -g @webflow/webflow-cli@latest

      - name: Deploy
        run: |
          webflow apps deploy \
            --no-input \
            --mount / \
            --environment main \
            --skip-mount-path-check \
            --skip-update-check
        env:
          WEBFLOW_API_TOKEN: ${{ secrets.WEBFLOW_API_TOKEN }}
          WEBFLOW_SITE_ID: ${{ secrets.WEBFLOW_SITE_ID }}
          # For project apps pre-first-deploy, omit WEBFLOW_SITE_ID
手动部署（本地 / 单次）
webflow apps deploy \
  --no-input \
  --app-name my-app \
  --mount / \
  --environment main \
  --skip-mount-path-check \
  --skip-update-check
手动部署并处理错误
webflow apps deploy --no-input --mount / --skip-mount-path-check --skip-update-check
if [ $? -ne 0 ]; then
  echo "Deploy failed. Log file:"
  webflow log
  exit 1
fi

指南

CI 中的 Init 与 Deploy
  • **apps init 用于在本地进行一次性项目设置 — 切勿在 CI 中运行。**关联站点模式会打开浏览器窗口；没有无头 OAuth 流程。请在本地运行一次 apps init，提交结果，然后在 CI 中使用 apps deploy。
挂载路径
  • 使用 --no-input 时，始终必须指定 --mount。CLI 不会从 webflow.json 读取已保存的挂载路径。
  • **切勿假设存在默认值。**假设路径为 / 或 /app，如果应用使用了其他路径，就会导致 ENVIRONMENT_MOUNT_MISMATCH。请在 Webflow 仪表板的环境设置中查看，或运行 webflow apps environments list --json 并读取 mount 字段（默认表格会省略 mount — 使用 --fields 时必须指定该字段：--fields id,branch,mount）。
不要添加确认步骤

设置 --no-input 后，不要在 apps deploy 之前添加人工确认步骤。这会阻塞无人值守的 CI 运行，而且没有必要 — 部署流程没有内置提示需要绕过。（apps delete 是例外：按设计，非交互模式下必须指定 --yes。）

机器读取时优先使用 --json

对于任何读取或管理命令（list、get、domains、environments、deployments、logs、env-vars），请传入 --json 并解析结构化输出，而不是抓取表格内容。--json 会忽略 --fields 并返回完整的 API 数据结构。

包管理器

无论存在什么锁文件，CLI 只使用 npm。pnpm 和 yarn 锁文件会被忽略 — 这些项目会静默地执行 npm install。

构建时文件管理

在执行 apps deploy 期间，CLI 会临时替换两个文件，并在成功或失败后恢复：

  • 框架配置（next.config.ts / astro.config.mjs）— 重命名为 clouduser.*，替换为 CLI 模板，然后恢复。
  • wrangler.json — 替换为 CLI 模板（原文件保存为 clouduser.wrangler.json），然后恢复。部署期间不要修改 wrangler.json。

如果框架是 Astro 且缺少 @astrojs/react，CLI 会在不提示的情况下运行 npm install --save @astrojs/react。

Cloudflare 绑定（D1 / KV / R2）

CLI 会在构建时合并 wrangler.json 中的绑定。每种类型都没有固定数量上限 — 存储容量由工作区的云存储权益决定，而非 CLI 中的硬编码数量限制。对于 D1，请在绑定中设置 migrations_dir — CLI 会自动复制迁移文件。

错误处理
  • CLI 遇到任何错误都会以代码 1 退出。请检查退出代码 — 不要根据 stdout 中的表情符号或文本模式进行匹配。
  • 对于管理命令，（JSON）错误中的 missingFlag 会指出需要重新运行命令并提供的标志（appId、environmentId、yes）。
  • 发生任何故障后，使用 webflow log 获取完整的错误跟踪信息。
部署版本控制
情况发送的版本标签
工作树干净git@{40-char-hash}
存在未提交的更改git@{40-char-hash}+dirty
不在 git 仓库中noversion@{ISO-timestamp}

部署到生产环境之前，请提交所有更改。

已知限制
  • apps deploy 支持 --dry-run 和 --json，但仅限 apps 形式——已弃用的别名 cloud deploy 两者都不支持。确切的输出格式请参见部署标志表。其他所有写入操作也都支持 --dry-run：apps init（两种路径——脚手架和 --import）、link、update、delete、environments create / update / delete、deployments redeploy / trigger，以及全部四个 env-vars 子命令。请注意，init 上的 --dry-run 仅注册在 apps init，不适用于别名 cloud init。
  • 日志不支持 --watch——日志端点可以轮询，但不会流式传输；要跟踪构建，请按间隔轮询。部署是例外：apps deployments get / redeploy / trigger 都支持 --wait，可阻塞命令，直到进入终态。
  • apps logs build 需要部署 ID——不会默认使用最新部署。请先通过 apps deployments list 获取 ID。
  • deployments redeploy / trigger 需要已连接 GitHub 的应用——通过 apps deploy 从本地文件部署的应用不符合条件。
  • --q 永远不会搜索值或 ID——只搜索资源的主要名称字段（应用名称、环境分支、变量键）。
  • 没有回滚命令。
  • 构建大小上限为 100 MB——超过 104,857,600 字节的构建会在上传时失败。

故障排除

apps init 上出现 --app-name cannot be empty（或任何必填标志错误）

CLI 会根据 process.stdin.isTTY 判断是否显示交互式提示。Agent 会在没有 TTY 的子进程中调用 CLI，因此整个提示区块会被跳过，并立即针对第一个缺失的必填值触发验证错误。

**解决方法：**显式传入所有必填标志。对于 apps init：

webflow apps init --new --no-input --app-name my-app --framework astro
# or, site-attached:
webflow apps init --no-input --app-name my-app --framework astro --mount /app --site-id site_abc123

严格来说，无需传入 --no-input 也会跳过提示——没有 TTY 已足以实现这一点——但这样可以明确表达约定，并与本技能顶部的必填标志矩阵保持一致。

apps init --new 一直挂起 / 始终无法返回

在项目应用模式下，如果令牌关联了多个工作区，工作区选择会无条件显示提示。传入 --workspace-id 可跳过选择器；如果不传，在非 TTY 环境中 CLI 会挂在提示处。

**解决方法：**向 apps init --new 传入 --workspace-id <id>。Webflow 控制台 UI 中不会显示工作区 ID，因此如果 Agent 没有该 ID，请让用户在现有项目目录中交互式运行 webflow apps deploy。预检提示会选择一个工作区，并将 cloud.workspace_id 写入 webflow.json——之后 Agent 可以读取该值，并在后续运行时传入 --workspace-id。单工作区令牌不受影响——系统会自动跳过选择步骤。

管理命令挂起或因缺少 ID 而报错

读取/管理命令会依次从参数/标志、WEBFLOW_APP_ID / WEBFLOW_APP_ENVIRONMENT_ID、webflow.json 中解析 appId / envId，最后才显示提示。在非 TTY 环境中，如果存在多个应用/环境且未传入任何值，命令会以机器可读的 missingFlag 退出。

**解决方法：**在应用目录中运行命令（这样就能从 webflow.json 解析 ID），或显式传入 ID——apps get <appId>、apps env-vars list --app-id <id> --environment-id <id>、apps logs runtime <envId>。单应用 / 单环境设置会自动选择，无需额外参数。

当我预期部署到关联站点时，却新建了一个已预配站点

症状： 用户想要部署到现有的 Webflow 站点，但 apps deploy 输出了 Creating Cloud app... / Cloud app created: <name>，生成的线上 URL 是 <name>-<hash>.webflow.io（一个刚创建的站点），而不是用户指定的站点。

原因： webflow.json 处于项目应用初始化状态——已设置 cloud.workspace_id，但未设置 siteId——通常是因为该项目之前使用 apps init --new 搭建。预检阶段会优先采用显式标志，但如果未传入任何标志，仍会回退到清单中的值。

预防（主要修复方法）： 为 apps deploy 传入 --site-id <existing-site-id>。预检阶段会优先根据标志解析站点身份，因此此参数会覆盖 webflow.json 中的值，并将部署指向预期的 Webflow 站点。已知需要部署到关联站点时，技能应始终传入 --site-id。

webflow apps deploy --no-input \
  --site-id site_abc123 \
  --mount /app --environment main \
  --skip-mount-path-check --skip-update-check

如果新站点已创建，如何恢复：

  • 保留部署刚创建的新项目应用站点——无需操作；后续部署会继续指向同一站点（如有歧义，也可以传入新站点的 --site-id）。
  • 改为指向现有的 Webflow 站点。 自动预配的站点创建后，无法重新绑定到现有站点。可选方案：
    1. 从 Webflow 仪表板中删除项目应用（及其自动预配的站点），或运行 webflow apps delete <appId> --yes。
    2. 编辑 webflow.json（移除 cloud.workspace_id、cloud.app_id、cloud.environment_id、siteId）并使用 --site-id <existing-site-id> 重新运行 apps init；或者跳过编辑清单，直接运行 apps deploy --site-id <existing-site-id>——预检会将其视为全新的关联站点部署。
部署时出现身份验证错误

运行 webflow auth login 并完成浏览器身份验证流程。CLI 会将新的 WEBFLOW_API_TOKEN 写入 .env。登录后重试部署。

在 CI 中无法进行浏览器身份验证——出现身份验证错误意味着密钥中的 WEBFLOW_API_TOKEN 缺失或已过期。请修复密钥，不要尝试运行 webflow auth login。如果 CI 使用旧版 WEBFLOW_SITE_API_TOKEN，部署仍会成功，但运行日志会显示弃用警告；请将密钥重命名为 WEBFLOW_API_TOKEN 以消除警告。

部署到其他工作区

对于项目应用（--new）：为 apps init 或 apps deploy 传入 --workspace-id <new-id>，以覆盖 webflow.json 中的 cloud.workspace_id。或者，从 webflow.json 中删除 cloud.workspace_id 并重新运行 init（或在现有项目中交互式部署），重新设置该值。

对于关联站点项目，工作区上下文由身份验证令牌隐式确定。重新运行 webflow auth login，并在浏览器中选择目标工作区；新令牌会替换 .env 中的旧令牌。

首次部署项目应用时出现 missing_scopes 错误

保存到 .env 的令牌不包含创建 Cloud 应用所需的权限范围。重新运行 webflow auth login 并重新批准所需权限范围，然后重试部署。

首次部署项目应用时失败：“your workspace has reached its app limit”

所选工作区（cloud.workspace_id）已达到应用数量上限。请升级工作区套餐，或从 Webflow 仪表板中删除未使用的应用（也可以运行 webflow apps delete <appId> --yes），然后重试。

首次部署项目应用时出现 workspace-not-found / 404 错误

工作区 ID（来自 --workspace-id 标志或 webflow.json 中的 cloud.workspace_id）已无法解析——工作区已删除，或令牌无权访问。CLI 不会预先验证该标志，而是信任其值，并显示来自 createCloudApp 的 404 错误。修复方法：

  • 为 apps init 或 apps deploy 传入 --workspace-id <correct-id>。
  • 或者，从 webflow.json 中删除 cloud.workspace_id，然后在空目录中重新运行 apps init --new --workspace-id <id>，或在现有项目中以交互方式运行 webflow apps deploy，让预检提示重新设置工作区 ID。
ENVIRONMENT_MOUNT_MISMATCH

--mount 值与该环境注册的路径不匹配。请通过 webflow apps environments list --json 查看正确的挂载路径（读取 mount 字段），或通过 --fields id,branch,mount 查看表格形式的输出——mount 不在默认字段集中；也可以查看 Webflow 控制面板，然后显式传入该路径。

无法检测框架／必须显式指定框架

包含 cloud 块但没有 framework 键的 webflow.json 不会报错——CLI 会回退到从 package.json 检测框架。只有在显式将 cloud.framework 设置为不受支持的值时，才会触发旧版错误 “webflow.json exists but doesn't contain valid framework information”。

如果仍然无法检测框架（例如 monorepo、缺少框架依赖或设置不明确），请在 apps deploy 中使用 --framework 标志进行修复：

webflow apps deploy --no-input --framework nextjs --mount /app --environment main ...

这会将 cloud.framework 写回 webflow.json，以便后续部署无需再使用该标志。或者直接手动编辑清单文件：

{
  "cloud": {
    "framework": "nextjs"
  }
}

有效值：nextjs、astro、vite、static。任何其他值都会以代码 1 退出。

构建失败，需要完整追踪信息
webflow log

打印包含完整错误追踪信息的最新日志文件路径。

评论

支持 Markdown