vtex-io-storefront-theme-versioning

店面主题版本控制、安装和回滚

何时使用此技能

当内容承载型店面应用的版本（例如 vendor.store-theme 主题，或任何包含 store/blocks.json、store/routes.json、store/templates/ 或 store/contentSchemas.json 的应用）即将在 master 中变更时，请使用此技能。

• 使用 vtex release patch | minor | major 提升主题应用的版本
• 在主题应用上运行 vtex publish / vtex deploy
• 对生产账户运行 vtex install [email protected]
• 将已安装的主题版本与 master 中不同的工作区提升
• 规划从导致所有店面内容“丢失”的部署中恢复
• 审查会触及店面主题的开发者部署脚本

以下情况请勿使用此技能：

• 通过 interfaces.json 注册区块——请使用 vtex-io-render-runtime-and-blocks
• react/ 下的面向顾客的组件代码——请使用 vtex-io-storefront-react
• manifest.json#settingsSchema 下的应用级设置——请使用 vtex-io-app-settings
• Master Data 架构版本控制——请使用 vtex-io-masterdata-strategy

决策规则

• 将任何在 store/ 下提供内容的应用（主题应用和许多店面应用）视为内容持有型应用。其已安装的 MAJOR 版本是平台用于存储和查找商家针对该应用声明的区块保存的所有站点编辑器更改时所用键的一部分。
• 站点编辑器内容、自定义路由、模板和每个模板的渲染缓存由 vtex.pages-graphql 存储，键的格式为 [email protected]:template。例如：[email protected]:store.home、[email protected]:store.product。
• patch（0.0.61 → 0.0.62）和 minor（0.1.0 → 0.2.0）会复用同一个键，新版本也会看到相同的商家内容。major（0.x → 5.x）会更改键。即使主题代码其他部分完全相同，新 major 版本也会从零商家内容开始。
• 当 vtex.pages-graphql 找不到当前 major 版本的内容时，会回退到默认的 vtex.store-theme 内容。即使客户的应用已安装并正在渲染，网站也会明显退化为“VTEX 默认主题”内容。
• 尽可能避免对内容持有型应用运行 vtex release major。优先将更改保留在当前 major 版本内，作为 patch 或 minor 发布，以便商家内容自动延续。
• 如果因区块、路由或模板的结构性更改而无法避免 major 版本升级，请在提升版本前，使用 [email protected] 中的 updateThemeIds mutation 将商家内容从旧 major 版本迁移到新 major 版本。该 mutation 会一次性将所有站点编辑器修改、页面和重定向的键从 vendor.app@{oldMajor}.x 重新映射到 vendor.app@{newMajor}.x。这是官方提供的开发者可用恢复方式；不要认为内容必须由人手动重新编写。
• 始终在带生产标记的开发工作区中安装并验证新的主题 major 版本（vtex use rollout-workspace --production 会在一个步骤中创建并切换到该工作区），然后再提升版本。仅链接应用并不足够：vtex link 不会测试已发布的制品，也不会产生与 vtex install + vtex workspace promote 相同的内容键行为。
• 在带生产标记的开发工作区中，安装新 major 版本后、运行 vtex workspace promote 前，通过 GraphQL Admin IDE 对 [email protected] 运行 updateThemeIds（vtex install [email protected]，然后运行 vtex browse admin/graphql-ide）。这样，该工作区中的站点编辑器、页面和重定向就会使用新 major 版本解析，并在提升版本时随工作区一同迁移。
• 将 vtex workspace promote 视为原子切换。运行 updateThemeIds 后，对开发工作区的所有页面进行冒烟测试（首页、PDP、PLP、部门页面、搜索、自定义路由、账户、结账入口）。如果开发工作区有问题，master 也会有问题。
• 验证 Apps Registry 中发布的版本与预期源代码一致。一种常见的失败情况是意外发布了精简的样板代码——注册表版本可以顺利安装，但其中不包含现有站点编辑器内容所引用的自定义区块。updateThemeIds 无法修复缺少区块的问题；它只能重新映射现有内容的键。
• 降级到先前的 major 版本时（例如 5.x → 4.x），同样需要运行 updateThemeIds。该 mutation 可以在 MAJOR 版本边界之间双向迁移内容。
• vtex workspace promote 不会清除 master 中的 vtex.pages-graphql VBase 内容。该服务使用 MineWinsConflictsResolver 进行合并：对 base（开发工作区分支自的 master 状态）、master（当前 master）和 mine（开发工作区）进行三方合并。开发工作区未触及的 master 键会保留；冲突键则以开发工作区（“mine”）为准。请规划发布流程，尽量减少发布期间对 master 的冲突写入，例如在准备开发工作区期间暂停商家在 master 中的站点编辑器修改。
• 每当 MineWinsConflictsResolver 在生产环境中解决冲突时，vtex.pages-graphql 都会自动将 base、master 和 mine 的每分钟快照写入同级的 userData_backup VBase 存储桶。该操作会在 io_vtex_logs 索引中以 subject: "conflicts_resolution" 记录。如果发布合并了不需要的内容，该快照可作为恢复来源；但它不能替代冒烟测试步骤（没有待解决的冲突时不会写入备份）。请将此备份视为联系 VTEX 支持时的安全保障，而非常规的自助恢复方式。

硬性约束

约束：包含内容的应用升级主版本前，必须先执行 updateThemeIds 迁移，再进行 promote

对拥有 Store Framework 内容的应用执行 vtex release major（或任何跨越 MAJOR.x 边界的版本变更）后，绝不能在未先通过生产标记的开发工作区，使用 [email protected] 中的 updateThemeIds mutation 将商家内容从旧主版本迁移到新主版本的情况下，就将其 promote 到 master。从 vtex.pages-graphql 的角度来看，新主版本的内容为空；如果未运行 updateThemeIds 就将其 promote 到 master，所有依赖 Site Editor 编辑内容的页面都会回退到默认主题内容。

为何这很重要

vtex.pages-graphql 会使用 [email protected]:template 作为每条商家自有路由、模板、Site Editor 编辑内容以及 Page/Redirect 条目的键。补丁和次版本升级会保留此键；主版本升级则会使其失效。主版本升级后，商家曾保存的所有 Site Editor 更改都无法再由解析器通过新主版本访问，店面会回退到默认的 vtex.store-theme 内容。开发者可通过官方方式修复：执行 updateThemeIds mutation，在一次操作中重新为所有 Site Editor 编辑内容、Pages 和 Redirects 设置从旧主版本到新主版本的键。跳过此步骤（或认为开发者必须手动重新编写内容）会导致店面对顾客的体验下降。

检测

在生产账号上运行任何 vtex install [email protected] 之前，将 X 与当前安装的主版本进行比较（vtex ls --production | grep store-theme）。如果 X 不同，立即停止。必须先在生产标记的开发工作区中安装新主版本，再执行 promote；updateThemeIds 迁移必须在两者之间完成。

如果开发者准备对包含以下任意内容的应用运行 vtex release major，也立即停止：store/blocks.json、store/routes.json、store/templates/、store/contentSchemas.json。先确认无法通过 patch 或 minor 表达此结构变更；如果必须升级主版本，则明确规划 updateThemeIds 步骤。

正确

vtex use theme-rollout --production            # creates and switches to a production-flag dev workspace
vtex install [email protected]
vtex install [email protected]        # required to access the GraphQL IDE
vtex browse admin/graphql-ide
# In the IDE, select the app `[email protected]` from the dropdown and run:
#
# mutation {
#   updateThemeIds(
#     from: "[email protected]",
#     to:   "[email protected]"
#   )
# }
#
# Expected response: { "data": { "updateThemeIds": true } }
# Validate Site Editor, Pages, and Redirects in this workspace, then:
vtex workspace promote

错误

vtex release major
vtex publish
vtex install [email protected]
# installed straight to master — no merchant content is visible under @5.x
# and the storefront falls back to default vtex.store-theme content

约束：包含内容的应用版本绝不能未经开发工作区冒烟测试就直接安装到 master

在 master 上更换包含内容的应用版本，必须先经过生产标记的开发工作区（vtex use $name --production），针对完整页面集进行冒烟测试，然后使用 vtex workspace promote 进行 promote。

为何这很重要

master 是公开的店面。直接在 master 上安装主题会让新版本立即对所有顾客生效。如果安装后发现缺少区块、新主版本下的内容区域为空，或已发布的制品被精简，唯一的恢复方式就是在流量压力下回滚。生产标记的开发工作区使用与 master 相同的数据进行渲染，因此可以发现相同的问题，同时不会影响顾客。

检测

如果开发者的命令序列在活动工作区为 master 时运行 vtex install，立即停止。要求先切换到生产标记的开发工作区。

正确

vtex use theme-rollout-2026-04 --production    # creates and switches to a production-flag dev workspace
vtex install [email protected]
# if this install crosses a MAJOR boundary, run updateThemeIds before smoke tests.
# fetch home, PDP, PLP, search, custom routes from $workspace--$account.myvtex.com
# only after smoke tests pass:
vtex workspace promote

错误

vtex use master
vtex install [email protected]
# any failure is now public

约束：确认已发布的构件与预期源代码一致

将内容承载型应用的新发布版本安装到 master 之前，请确认 Apps Registry 中的构件确实包含当前商家内容所引用的区块。vtex publish 成功并不保证构件包含商家的自定义内容。

为什么这很重要

一种常见的故障模式是：从精简版仓库或基础主题分支发布，而该分支丢失了商家数月来一直编辑的自定义区块。安装虽然成功，但 pages-graphql 无法解析商家已存储内容中引用的区块，店面便会回退到默认内容。构件与内容不一致。

检测

如果已发布版本是从不包含当前主题所引用自定义区块的仓库构建的，请停止。应从正确的源重新发布。updateThemeIds 迁移只会重新为内容编配键，无法解析缺失的区块 ID，因此即使迁移成功，精简版构件仍会回退到默认内容。

正确

# pull the published artifact and confirm it ships the custom blocks
vtex apps files [email protected] store/ | grep -E 'umMaisUm|customHeader'
# matches the block IDs the active theme depends on

错误

vtex publish
vtex install [email protected]
# published artifact is the boilerplate fork; it is missing every custom block
# referenced in the merchant's stored content

约束：将 vtex workspace promote 视为 pages-graphql VBase 上的三方“以我的为准”合并，而不是清除操作

必须将 vtex workspace promote 规划为 dev 工作区与 master 之间的合并，而不是对 master 的 vtex.pages-graphql VBase 内容进行破坏性替换。该服务使用 @vtex/api 中的 MineWinsConflictsResolver：它会比较 base（dev 工作区分支时的 master 状态）、master（当前 master）和 mine（dev 工作区），并以 dev 工作区为准解决冲突。

为什么这很重要

dev 工作区从未触及的 master 键会在 promote 后保留。冲突键（分支点之后在 master 和 dev 工作区中都被编辑的内容）会被 dev 工作区的值覆盖。主题上线时有两个实际影响：

1. 如果在准备 dev 工作区期间，商家继续在 master 中编辑 Site Editor，那么 dev 工作区也修改过的键上的这些编辑会在 promote 时丢失。
2. updateThemeIds 在 dev 工作区运行后，dev 工作区便拥有新的大版本内容映射；promote 会通过“以我的为准”机制，将重新编配键后的 Site Editor 编辑、Pages 和 Redirects 干净地转移到 master。

在生产环境中，每次冲突解决都会将 base、master 和 mine 的每分钟快照写入 vtex.pages-graphql 内的同级 userData_backup VBase 存储桶，并记录 subject: "conflicts_resolution"。没有冲突需要解决时不会写入备份，因此冒烟测试仍是首要的安全保障。

检测

如果上线计划假设 promote 会“替换”master 内容，请停止并改为制定合并计划：dev 工作区会触及哪些键，master 在同一时间段内可能会触及哪些键，以及如何协调冲突。如果商家在上线期间积极编辑 master 中的 Site Editor，请停止，并暂停这些编辑、缩短上线窗口，或记录哪些键会被覆盖。

正确

Coordinate the rollout window with the merchant ops team:
- Pause Site Editor edits on master from the moment `updateThemeIds`
  runs in the dev workspace until `vtex workspace promote` completes.
- Smoke-test in the dev workspace, then promote.
- After promote, validate Storefront → Site Editor, Pages, Redirects
  on master.

If a conflict-resolution log appears (subject: "conflicts_resolution"),
record the backup paths surfaced by pages-graphql in `io_vtex_logs`.
The snapshot lives in the `userData_backup` bucket of vtex.pages-graphql
and can be fetched via the VBase v2 API for support escalation.

错误

"Promote will replace master, so we don't need to coordinate."
- Merchants keep editing Site Editor in master during the rollout.
- Promote merges those edits with mine-wins; every conflicting key is
  silently overwritten by the dev workspace value.
- Without a smoke-test or coordination, the lost edits are not noticed
  until shoppers report missing content.

推荐模式

对安装在 master 上的任何内容承载型应用进行更改时，建议采用的部署流程：

1. Decide the SemVer bump deliberately
   - patch  → bug fix, no block contract change
   - minor  → new optional block, backward-compatible additions
   - major  → ANY structural change that breaks an existing block contract
              (avoid when possible; requires the updateThemeIds migration)

2. vtex release [patch|minor|major]
   vtex publish

3. Switch to a production-flag dev workspace
   (vtex use both creates and switches in one step)
   vtex use theme-rollout-YYYY-MM-DD --production

4. Install the new version in the dev workspace
   vtex install [email protected]

5. If the bump crosses a MAJOR boundary (including downgrades such as 5.x → 4.x):
   a. vtex install [email protected]   (if not already installed)
   b. vtex browse admin/graphql-ide
   c. In the IDE, select the app `[email protected]` from the dropdown
   d. Run:
        mutation {
          updateThemeIds(
            from: "{appVendor}.{appName}@{oldMajor}.x",
            to:   "{appVendor}.{appName}@{newMajor}.x"
          )
        }
      Keep the literal "x" in both keys; do not replace it with a minor or
      patch number or the mutation silently fails.
   e. Expected response: { "data": { "updateThemeIds": true } }
   If the bump is patch or minor inside the same major, skip this step —
   content keys are preserved automatically.

6. Smoke-test in the dev workspace against the full page set
   - $workspace--$account.myvtex.com/             (home)
   - $workspace--$account.myvtex.com/<pdp-slug>/p (product)
   - $workspace--$account.myvtex.com/<category>   (PLP)
   - $workspace--$account.myvtex.com/<dept>       (department)
   - $workspace--$account.myvtex.com/<search>?_q  (search)
   - any /institucional/* or other custom routes
   - VTEX Admin → Storefront → Site Editor, Pages, Redirects
   - account, login, cart, checkout entry

7. If anything is wrong: stop. Do not promote. Investigate.
   If everything renders correctly:
   - Coordinate the promote window with the merchant ops team so that
     no Site Editor edits land on master between `updateThemeIds` in
     the dev workspace and `vtex workspace promote`. Promote performs
     a 3-way mine-wins merge against pages-graphql VBase, so any
     conflicting master edit will be overwritten by the dev workspace.
   - vtex workspace promote

8. Re-test on $account.myvtex.com (master) and the public domain.
   - Validate Storefront → Site Editor, Pages, Redirects on master.
   - If the public CDN serves stale content, validate with cache-busting
     query strings; the edge will refresh on its normal TTL.
   - If `io_vtex_logs` shows a `subject: "conflicts_resolution"` entry
     for `vtex.pages-graphql` in this account around the promote time,
     record the listed backup paths. They live in the `userData_backup`
     bucket of pages-graphql and can be fetched via the VBase v2 API
     if a recovery is needed later.

9. Keep the dev workspace for at least one business day in case a fast
   re-promote is needed.

在 master 上安装损坏的大版本后，建议采用的紧急回滚方式：

1. vtex use rollback-YYYY-MM-DD --production
   (vtex use both creates and switches; there is no `vtex workspace create`)
2. vtex install vendor.store-theme@<previous major version>
3. If the rollback crosses a MAJOR boundary (it almost always does), run
   updateThemeIds in [email protected] to migrate stored Site Editor
   edits, Pages, and Redirects from the broken major back to the previous
   major:

     mutation {
       updateThemeIds(
         from: "{appVendor}.{appName}@{brokenMajor}.x",
         to:   "{appVendor}.{appName}@{previousMajor}.x"
       )
     }

4. Smoke-test the rollback workspace end-to-end (storefront pages and
   VTEX Admin → Storefront → Site Editor, Pages, Redirects).
5. vtex workspace promote

If `updateThemeIds` returns false, the GraphQL IDE shows an error, or
content does not appear after migration, escalate to VTEX support
before promoting; do not promote a workspace whose Site Editor content
has not been validated.

If a previous promote merged in something unwanted, before re-promoting
check `io_vtex_logs` for a `subject: "conflicts_resolution"` entry on
`vtex.pages-graphql` for this account around the original promote
time. The entry lists per-minute snapshot paths inside the
`userData_backup` bucket (`store/templates.{base|master|mine}.<TS>.json`,
`store/content.{...}.json`, `store/routes.{...}.json`) which can be
fetched through the VBase v2 API:

   GET https://infra.io.vtex.com/vbase/v2/{account}/{workspace}/
       buckets/vtex.pages-graphql/userData_backup/files/{path}

This recovery path requires an admin auth token and is documented in
`vtex/pages-graphql` `TROUBLESHOOTING.md`. Treat it as a support-led
escalation, not a routine self-service step, and always test the
restored payload in a non-master workspace first.

建议的内容键行为理解方式：

Patch / minor bump
   acme.store-theme @ 0.0.61  →  0.0.62
   storage key prefix unchanged: [email protected]:*
   merchant content carries over automatically

Major bump
   acme.store-theme @ 0.0.61  →  5.0.0
   storage key prefix changes: [email protected]:*  →  [email protected]:*
   the new major starts empty from the resolver's point of view
   run updateThemeIds in [email protected] inside the production-flag
   dev workspace to rekey Site Editor edits, Pages, and Redirects from
   [email protected] to [email protected], then promote

常见故障模式

• 在主题上运行 vtex release major 来“整理”版本号，却没意识到 promote 前必须先执行 updateThemeIds 迁移。
• 因为开发工作区“看起来一样”，就直接在 master 上安装新的主题主版本。
• 从分叉的仓库发布，而该仓库不包含当前主题所依赖的自定义区块。updateThemeIds 会重新编排内容键，但无法解析缺失的区块 ID。
• 将 vtex link 视为等同于对承载内容的应用运行 vtex install。link 不会经过已发布制品的解析路径，也不会触发按主版本键查找内容。
• 从从未进行过端到端冒烟测试的工作区运行 vtex workspace promote。
• 主版本升级时未先运行 updateThemeIds，导致店面上线后，所有之前依赖 Site Editor 编辑内容的页面都使用默认的 vtex.store-theme 内容。
• 尝试使用不存在的 vtex workspace create 命令。CLI 会在执行 vtex use {workspaceName} --production 时顺带创建工作区；这条命令会同时创建并切换工作区。
• 将 updateThemeIds 参数中的字面量 x 替换为次版本号或修订号（例如使用 [email protected]，而不是 [email protected]）。该变更要求使用“主版本号加 x”的格式，否则会静默地不执行任何操作。
• 在 GraphQL IDE 下拉菜单中选错应用，然后对其运行 updateThemeIds。该变更只存在于 [email protected]。
• 在 promote 后立即依赖公共域名确认修复是否生效。CloudFront 会提供过期内容；验证时请使用 ?utm_source=<value> 或其他缓存破坏参数绕过边缘缓存。
• 忘记降级（例如从 5.x 降到 4.x）同样会跨越主版本边界，因此 promote 前也需要单独运行 updateThemeIds。
• 以为 vtex workspace promote 会清除 master 中的 vtex.pages-graphql VBase 内容，并用开发工作区的内容重新填充。实际上并非如此——它会执行“三方合并”，并采用我的版本优先策略，因此开发工作区未触及的 master 键会保留，而开发工作区也触及的 master 键则会被静默覆盖。请与商家运营团队协调发布时间窗口，避免丢失 master 中并发进行的 Site Editor 编辑。
• 将 vtex.pages-graphql 中的 userData_backup 存储桶当作常规恢复入口。只有在解决冲突时才会写入该存储桶（无冲突就不会备份）；使用它需要管理员级别的身份验证和 VBase v2 API，而且它是由支持团队主导的故障排查途径，不能替代冒烟测试或 updateThemeIds 流程。

审核清单

• 根据 SemVer 规则，提议的版本升级是否正确归类为 patch、minor 或 major？
• 如果升级跨越 major 版本边界，是否已在生产标志的开发工作区中记录 updateThemeIds 迁移步骤（包括升级和降级两个方向）？
• 是否先将应用安装到生产标志的开发工作区（vtex use $name --production），而不是直接安装到 master？
• 如果是 major 版本升级，是否已在 GraphQL Admin IDE 中针对 [email protected] 运行 updateThemeIds，并且响应是否为 { "updateThemeIds": true }？
• 是否已验证发布的构件包含当前主题所依赖的自定义区块？
• 是否已在开发工作区中对首页、PDP、PLP、部门页面、搜索、自定义路由、账户、结账入口和 Storefront 模块（Site Editor、Pages、Redirects）进行冒烟测试？
• 是否已协调上线时间窗口，确保在开发工作区运行 updateThemeIds 到执行 vtex workspace promote 之间，没有其他 Site Editor 编辑内容写入 master，因为合并策略是 3 路合并中以我的版本为准？
• Promote 后，是否已检查 io_vtex_logs，确认其中是否存在针对该账户的 vtex.pages-graphql subject: "conflicts_resolution" 条目；如果存在，是否已记录所列的 userData_backup 路径，以便升级寻求支持？
• 是否会在 Promote 后至少保留开发工作区一个工作日，以备需要快速重新 Promote？

相关技能

• vtex-io-app-contract — 当问题涉及 manifest 应声明什么契约，以及为什么对于包含内容的应用来说，major 版本升级会破坏契约时。
• vtex-io-storefront-theme-app — 当问题涉及主题应用实际拥有的内容（store/blocks.json、store/routes.json、页面模板），以及这些文件与商家的 Site Editor 内容有何关联时。
• vtex-io-render-runtime-and-blocks — 当问题涉及主题中的区块名称如何解析为 React 组件，以及当前 major 版本下缺少区块为何会导致渲染失败时。
• vtex-io-data-access-patterns — 当问题涉及某项数据是否应该放在 Site Editor 中，还是应存放在应用设置、Master Data 或其他存储位置时。

参考资料

• Manifest — 说明 vendor、name 和 version 如何构成应用标识，并用于生成店面内容键。
• Versioning an App — 介绍 vtex release 和 SemVer 规则，以及它们如何决定版本升级会保留还是使下游内容键失效。
• Publishing an App — 介绍 vtex publish 如何生成由 vtex install 安装的制品。
• Installing an App — 介绍 vtex install 的工作区范围，以及为什么开发工作区必须标记为生产环境，才能进行真实测试。
• Creating a Production Workspace — vtex use {workspaceName} --production 是一条同时创建并切换到生产标记工作区的命令。
• Promoting a Workspace to Master — 介绍如何使用 vtex workspace promote，将生产标记的开发工作区原子性地切换为 master。
• Migrating CMS settings after a major theme update — [email protected] 中 updateThemeIds 变更的官方操作流程，包括 GraphQL IDE 设置和字面量 MAJOR.x 参数格式。
• vtex/pages-graphql TROUBLESHOOTING.md — 介绍 MineWinsConflictsResolver 如何将每分钟的 base、master 和 mine 快照写入 vtex.pages-graphql 的 userData_backup 存储桶，以及如何通过 VBase v2 API 获取这些快照以便支持团队进行恢复（VTEX 内部仓库）。
• Store Framework — 介绍主题应用为何拥有 store/ 内容，以及 Store Framework 如何在渲染时使用这些内容。