vtex-io-storefront-theme-versioning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Storefront Theme Versioning, Install, and Rollback

店铺前端主题的版本管理、安装与回滚

When this skill applies

本指南适用场景

Use this skill whenever the version of a content-holding storefront app (a theme such as

vendor.store-theme

, or any app that ships

store/blocks.json

store/routes.json

store/templates/

, or

store/contentSchemas.json

) is about to change in

master

Bumping the version of a theme app with
```
vtex release patch | minor | major
```
Running
```
vtex publish
```
/
```
vtex deploy
```
on a theme app
Running
```
vtex install vendor.store-theme@X.Y.Z
```
against a production account
Promoting a workspace that has a different theme version installed than
```
master
```
Planning recovery from a deploy that "lost" all storefront content
Reviewing a developer's deploy script that touches a storefront theme

Do not use this skill for:

block registration via

interfaces.json

— use

vtex-io-render-runtime-and-blocks

shopper-facing component code under
```
react/
```
— use
```
vtex-io-storefront-react
```

app-level settings under

manifest.json#settingsSchema

— use

vtex-io-app-settings

Master Data schema versioning — use
```
vtex-io-masterdata-strategy
```

当

master

环境中内容承载型店铺前端应用（如

vendor.store-theme

这类主题应用，或任何包含

store/blocks.json

、

store/routes.json

、

store/templates/

或

store/contentSchemas.json

的应用）的版本即将变更时，可使用本指南。

使用
```
vtex release patch | minor | major
```
升级主题应用版本
对主题应用执行
```
vtex publish
```
/
```
vtex deploy
```
针对生产账号执行
```
vtex install vendor.store-theme@X.Y.Z
```
发布与
```
master
```
环境主题版本不同的工作区
规划从导致「店铺前端内容丢失」的部署中恢复
审核涉及店铺前端主题的开发者部署脚本

本指南不适用于：

通过

interfaces.json

注册区块——请使用

vtex-io-render-runtime-and-blocks

```
react/
```
目录下面向购物者的组件代码——请使用
```
vtex-io-storefront-react
```

manifest.json#settingsSchema

下的应用级设置——请使用

vtex-io-app-settings

Master Data schema版本管理——请使用
```
vtex-io-masterdata-strategy
```

Decision rules

决策规则

Treat any app that ships content under
```
store/
```
(theme apps and many storefront apps) as a content-holding app. Its installed MAJOR version is part of the key the platform uses to store and look up every Site Editor change a merchant has ever saved against blocks declared by that app.
Site Editor content, custom routes, templates, and per-template render caches are stored by
```
vtex.pages-graphql
```
under keys of the form
```
vendor.app@MAJOR.x:template
```
. Examples:
```
acme.store-theme@0.x:store.home
```
,
```
acme.store-theme@0.x:store.product
```
.
A
```
patch
```
(
```
0.0.61
```
→
```
0.0.62
```
) and a
```
minor
```
(
```
0.1.0
```
→
```
0.2.0
```
) reuse the same key and the new version sees the same merchant content. A
```
major
```
(
```
0.x
```
→
```
5.x
```
) changes the key. The new major starts with zero merchant content even if the theme code is otherwise identical.
When
```
vtex.pages-graphql
```
cannot find content for the active major, it falls back to the default
```
vtex.store-theme
```
content. The site visibly degrades to "VTEX default theme" content even though the customer's app is installed and rendering.
Avoid
```
vtex release major
```
on a content-holding app whenever possible. Prefer keeping changes within the current major as
```
patch
```
or
```
minor
```
so merchant content carries forward automatically.
When a major bump is unavoidable because of a structural change to blocks, routes, or templates, migrate the merchant content from the old major to the new major with the
```
updateThemeIds
```
mutation in
```
vtex.pages-graphql@2.x
```
before promoting. The mutation rekeys all Site Editor edits, Pages, and Redirects from
```
vendor.app@{oldMajor}.x
```
to
```
vendor.app@{newMajor}.x
```
in one operation. This is the official developer-accessible recovery surface; do not assume content has to be re-authored manually.
Always install and validate a new theme major in a production-flag dev workspace (
```
vtex use rollout-workspace --production
```
, which both creates and switches to the workspace in one step) before promoting. Linking is not enough:
```
vtex link
```
does not exercise published artifacts and does not produce the same content-key behavior as
```
vtex install
```
+
```
vtex workspace promote
```
.
Run
```
updateThemeIds
```
against
```
vtex.pages-graphql@2.x
```
from the GraphQL Admin IDE (
```
vtex install vtex.admin-graphql-ide@3.x
```
, then
```
vtex browse admin/graphql-ide
```
) inside the production-flag dev workspace, after
```
vtex install
```
of the new major and before
```
vtex workspace promote
```
. Site Editor, Pages, and Redirects in that workspace will then resolve under the new major and be carried with the workspace at promote time.
Treat
```
vtex workspace promote
```
as the atomic cutover. Smoke-test the dev workspace's full page set (home, PDP, PLP, department, search, custom routes, account, checkout entry) after running
```
updateThemeIds
```
. If the dev workspace is broken, master will be broken.
Verify that the version published to the Apps Registry matches the source you expect. A common failure pattern is publishing a stripped-down boilerplate by mistake — the registry version installs cleanly, but it does not contain the custom blocks the existing Site Editor content references.
```
updateThemeIds
```
cannot fix a missing-block problem; it only rekeys existing content.
The same
```
updateThemeIds
```
step is required when downgrading to a previous major (for example
```
5.x
```
→
```
4.x
```
). The mutation moves content in either direction across MAJOR boundaries.
```
vtex workspace promote
```
does not wipe master's
```
vtex.pages-graphql
```
VBase content. The service merges with
```
MineWinsConflictsResolver
```
: a 3-way merge of
```
base
```
(the master state the dev workspace forked from),
```
master
```
(current master), and
```
mine
```
(the dev workspace). Master keys not touched by the dev workspace are preserved; conflicting keys are resolved in favor of the dev workspace ("mine wins"). Plan the rollout so that conflicting writes to master during the rollout window are minimized — for example, by pausing merchant Site Editor edits in master while the dev workspace is being prepared.
Whenever
```
MineWinsConflictsResolver
```
resolves a conflict in production,
```
vtex.pages-graphql
```
automatically writes a per-minute snapshot of
```
base
```
,
```
master
```
, and
```
mine
```
to a sibling
```
userData_backup
```
VBase bucket. This is logged with
```
subject: "conflicts_resolution"
```
in the
```
io_vtex_logs
```
index. The snapshot is the recovery source if a promote merges in something unwanted; it is not a substitute for the smoke-test step (no backup is written when there is no conflict to resolve). Treat the backup as a safety net for VTEX support escalations, not a routine self-service restore.

将任何包含
```
store/
```
目录内容的应用（主题应用及多数店铺前端应用）视为内容承载型应用。其安装的MAJOR版本是平台存储和查找商家针对该应用声明的区块所做的每一处Site Editor更改的关键标识。
Site Editor内容、自定义路由、模板及每个模板的渲染缓存由
```
vtex.pages-graphql
```
以
```
vendor.app@MAJOR.x:template
```
格式的键存储。示例：
```
acme.store-theme@0.x:store.home
```
、
```
acme.store-theme@0.x:store.product
```
。
```
patch
```
版本升级（
```
0.0.61
```
→
```
0.0.62
```
）和
```
minor
```
版本升级（
```
0.1.0
```
→
```
0.2.0
```
）会复用相同的键，新版本可读取相同的商家内容。
```
major
```
版本升级（
```
0.x
```
→
```
5.x
```
）会更改键。即使主题代码完全相同，新版本也会从零开始，无任何商家内容。
当
```
vtex.pages-graphql
```
无法找到当前主版本对应的内容时，会回退到默认的
```
vtex.store-theme
```
内容。此时店铺会明显降级为「VTEX默认主题」内容，尽管客户的应用已安装并正在渲染。
尽可能避免对内容承载型应用执行
```
vtex release major
```
。优先将变更作为
```
patch
```
或
```
minor
```
版本保留在当前主版本内，以便商家内容自动延续。
若因区块、路由或模板的结构性变更而必须升级主版本，请在发布前，使用
vtex.pages-graphql@2.x
中的
updateThemeIds
mutation将商家内容从旧主版本迁移到新主版本。该mutation可一次性将所有Site Editor编辑内容、页面及重定向的键从
```
vendor.app@{oldMajor}.x
```
更新为
```
vendor.app@{newMajor}.x
```
。这是官方提供的开发者可访问的恢复方式；请勿假设内容必须手动重新编辑。
发布前，务必在带生产标记的开发工作区（
```
vtex use rollout-workspace --production
```
，该命令可一步创建并切换到工作区）中安装并验证新的主题主版本。仅本地链接（
```
vtex link
```
）不足以验证：
```
vtex link
```
不会使用已发布的工件，也不会产生与
```
vtex install
```
+
```
vtex workspace promote
```
相同的内容键行为。
在安装新主版本后、执行
```
vtex workspace promote
```
前，在带生产标记的开发工作区中，通过GraphQL Admin IDE（先执行
```
vtex install vtex.admin-graphql-ide@3.x
```
，再执行
```
vtex browse admin/graphql-ide
```
）针对
```
vtex.pages-graphql@2.x
```
运行
```
updateThemeIds
```
。此时该工作区中的Site Editor、页面及重定向将使用新主版本的键，并在发布时同步到
```
master
```
环境。
将
```
vtex workspace promote
```
视为原子切换操作。运行
```
updateThemeIds
```
后，需对开发工作区的全页面集合（首页、商品详情页PDP、商品列表页PLP、分类页、搜索页、自定义路由、账户页、结账入口）进行冒烟测试。若开发工作区存在问题，
```
master
```
环境也会出现问题。
验证发布到应用注册表的版本是否与预期的源代码一致。常见的失败场景是误发布了精简版的模板——注册表中的版本可正常安装，但不包含现有Site Editor内容引用的自定义区块。
```
updateThemeIds
```
无法修复区块缺失问题；它仅能更新现有内容的键。
降级到之前的主版本（例如
```
5.x
```
→
```
4.x
```
）时，同样需要执行
```
updateThemeIds
```
步骤。该mutation可在任意主版本之间双向迁移内容。
```
vtex workspace promote
```
不会清除
```
master
```
环境中
```
vtex.pages-graphql
```
的VBase内容。该服务使用
```
MineWinsConflictsResolver
```
进行三方合并：对比
```
base
```
（开发工作区从
```
master
```
环境分叉时的状态）、
```
master
```
（当前
```
master
```
环境状态）和
```
mine
```
（开发工作区状态），冲突时以开发工作区的内容为准（「我方获胜」）。请规划发布流程以减少发布窗口内
```
master
```
环境的冲突写入——例如，在准备开发工作区期间暂停商家在
```
master
```
环境中的Site Editor编辑操作。
当
```
MineWinsConflictsResolver
```
在生产环境中解决冲突时，
```
vtex.pages-graphql
```
会自动将
```
base
```
、
```
master
```
和
```
mine
```
的每分钟快照写入同级的
```
userData_backup
```
VBase存储桶。该操作会在
```
io_vtex_logs
```
索引中记录
```
subject: "conflicts_resolution"
```
。若发布时合并了不需要的内容，该快照可作为恢复源；但它不能替代冒烟测试步骤（无冲突时不会生成备份）。请将该备份视为VTEX支持团队处理问题的安全保障，而非常规自助恢复工具。

Hard constraints

硬性约束

Constraint: Major version bumps on content-holding apps require an

updateThemeIds

migration before promote

约束：内容承载型应用升级主版本时，发布前必须执行

updateThemeIds

迁移

vtex release major

(or any version change that crosses the

MAJOR.x

boundary) on an app that owns Store Framework content MUST NOT be promoted to

master

without first migrating merchant content from the old major to the new major in a production-flag dev workspace, using the

updateThemeIds

mutation in

vtex.pages-graphql@2.x

. The new major starts empty from

vtex.pages-graphql

's point of view; promoting it to

master

without running

updateThemeIds

makes the storefront fall back to default theme content for every page that depended on Site Editor edits.

Why this matters

vtex.pages-graphql

keys every merchant-owned route, template, Site Editor edit, and Page/Redirect entry by

vendor.app@MAJOR.x:template

. A patch and minor bump preserve the key; a major bump invalidates it. After a major bump, every Site Editor change the merchant ever saved is no longer visible to the resolver under the new major, and the storefront falls back to default

vtex.store-theme

content. The official developer-accessible fix is the

updateThemeIds

mutation, which rekeys all Site Editor edits, Pages, and Redirects from the old major to the new one in a single operation. Skipping it (or assuming developers must re-author content manually) leaves the storefront degraded for shoppers.

Detection

Before running any

vtex install vendor.app@X.Y.Z

on a production account, compare

to the major currently installed (

vtex ls --production | grep store-theme

). If

differs, STOP. Require the

updateThemeIds

migration to be executed in a production-flag dev workspace, after the new major is installed and before promote.

Also STOP if a developer is about to run

vtex release major

on an app that ships any of:

store/blocks.json

store/routes.json

store/templates/

store/contentSchemas.json

. Confirm the structural change cannot be modeled as a

patch

minor

first; if the major is unavoidable, plan the

updateThemeIds

step explicitly.

Correct

bash

vtex use theme-rollout --production            # creates and switches to a production-flag dev workspace
vtex install acme.store-theme@5.0.0
vtex install vtex.admin-graphql-ide@3.x        # required to access the GraphQL IDE
vtex browse admin/graphql-ide

对于拥有Store Framework内容的应用，执行

vtex release major

（或任何跨越

MAJOR.x

边界的版本变更）后，不得直接发布到
master
环境，必须先在带生产标记的开发工作区中，使用

vtex.pages-graphql@2.x

中的

updateThemeIds

mutation将商家内容从旧主版本迁移到新主版本。从

vtex.pages-graphql

的角度来看，新主版本初始为空；若未运行

updateThemeIds

就发布到

master

环境，所有依赖Site Editor编辑内容的页面都会回退到默认主题内容。

重要性说明

vtex.pages-graphql

以

vendor.app@MAJOR.x:template

为键存储商家所有的路由、模板、Site Editor编辑内容及页面/重定向条目。Patch和minor版本升级会保留该键；major版本升级会使该键失效。升级主版本后，商家保存的所有Site Editor变更在新版本下都无法被解析，店铺前端会回退到默认的

vtex.store-theme

内容。官方提供的开发者可访问的修复方式是

updateThemeIds

mutation，它可一次性将所有Site Editor编辑内容、页面及重定向的键从旧主版本更新到新主版本。跳过该步骤（或假设开发者必须手动重新编辑内容）会导致店铺前端体验降级。

检测方式

在生产账号上执行

vtex install vendor.app@X.Y.Z

前，对比

与当前安装的主版本（执行

vtex ls --production | grep store-theme

查看）。若

不同，请停止操作。要求在带生产标记的开发工作区中安装新主版本后、发布前执行

updateThemeIds

迁移。

若开发者要对包含

store/blocks.json

、

store/routes.json

、

store/templates/

或

store/contentSchemas.json

的应用执行

vtex release major

，也请停止操作。先确认结构性变更是否可通过

patch

或

minor

版本实现；若必须升级主版本，请明确规划

updateThemeIds

步骤。

正确操作

bash

vtex use theme-rollout --production            # 创建并切换到带生产标记的开发工作区
vtex install acme.store-theme@5.0.0
vtex install vtex.admin-graphql-ide@3.x        # 需要安装以访问GraphQL IDE
vtex browse admin/graphql-ide

In the IDE, select the app

vtex.pages-graphql@2.x

from the dropdown and run:

在IDE中，从下拉菜单选择应用

vtex.pages-graphql@2.x

并运行：

mutation {

updateThemeIds(

from: "acme.store-theme@0.x",

to: "acme.store-theme@5.x"

)

}

Expected response: { "data": { "updateThemeIds": true } }

预期响应：{ "data": { "updateThemeIds": true } }

Validate Site Editor, Pages, and Redirects in this workspace, then:

验证该工作区中的Site Editor、页面及重定向，然后执行：

vtex workspace promote


**Wrong**

```bash
vtex release major
vtex publish
vtex install acme.store-theme@5.0.0

vtex workspace promote


**错误操作**

```bash
vtex release major
vtex publish
vtex install acme.store-theme@5.0.0

installed straight to master — no merchant content is visible under @5.x

直接安装到master环境——@5.x版本下无任何商家内容

and the storefront falls back to default vtex.store-theme content

店铺前端回退到默认的vtex.store-theme内容

undefined

undefined

Constraint: Never install a content-holding app version directly to master without a dev-workspace smoke test

约束：不得直接将内容承载型应用版本安装到master环境，必须先在开发工作区进行冒烟测试

Any change that swaps the installed version of a content-holding app on

master

MUST go through a production-flag dev workspace first (

vtex use $name --production

), be smoke-tested across the full page set, and then be promoted with

vtex workspace promote

Why this matters

master

is the public storefront. Installing a theme directly to

master

makes the new version live for every shopper instantly. If the install reveals a missing block, an empty content surface under the new major, or a stripped-down published artifact, the only recovery is rollback under load. A production-flag dev workspace renders against the same data as

master

and surfaces the same failures without exposing shoppers.

Detection

If a developer's command sequence runs

vtex install

while the active workspace is

master

, STOP. Require switching to a production-flag dev workspace first.

Correct

bash

vtex use theme-rollout-2026-04 --production    # creates and switches to a production-flag dev workspace
vtex install acme.store-theme@5.3.5

任何更换

master

环境中内容承载型应用安装版本的变更，都必须先通过带生产标记的开发工作区（

vtex use $name --production

），完成全页面集合的冒烟测试后，再通过

vtex workspace promote

发布。

重要性说明

master

环境是公开的店铺前端。直接将主题安装到

master

环境会使新版本立即对所有购物者生效。若安装后发现区块缺失、新版本下内容为空或发布的工件被精简，只能在负载压力下进行回滚。带生产标记的开发工作区使用与

master

环境相同的数据进行渲染，可在不影响购物者的情况下暴露相同的问题。

检测方式

若开发者的命令序列在当前工作区为

master

时执行

vtex install

，请停止操作。要求先切换到带生产标记的开发工作区。

正确操作

bash

vtex use theme-rollout-2026-04 --production    # 创建并切换到带生产标记的开发工作区
vtex install acme.store-theme@5.3.5

if this install crosses a MAJOR boundary, run updateThemeIds before smoke tests.

若该安装跨越主版本边界，在冒烟测试前运行updateThemeIds。

fetch home, PDP, PLP, search, custom routes from $workspace--$account.myvtex.com

从$workspace--$account.myvtex.com获取首页、PDP、PLP、搜索页、自定义路由

only after smoke tests pass:

仅在冒烟测试通过后执行：

vtex workspace promote


**Wrong**

```bash
vtex use master
vtex install acme.store-theme@5.3.5

vtex workspace promote


**错误操作**

```bash
vtex use master
vtex install acme.store-theme@5.3.5

any failure is now public

任何故障都会立即公开

undefined

undefined

Constraint: Verify the published artifact matches the source you expect

约束：验证发布的工件与预期源代码一致

Before installing a new published version of a content-holding app to

master

, confirm that the artifact in the Apps Registry actually contains the blocks the active merchant content references. A successful

vtex publish

does not guarantee the artifact carries the merchant's customizations.

Why this matters

A common failure pattern is publishing from a stripped-down repository or from a base-theme fork that lost the custom blocks the merchant has been editing for months. The install succeeds, but

pages-graphql

cannot resolve the blocks referenced in the merchant's stored content, and the storefront falls back to default content. The artifact and the content disagree.

Detection

If the published version was built from a repository that does not contain the custom blocks the active theme references, STOP. Republish from the correct source. The

updateThemeIds

migration only rekeys content; it cannot resolve missing block IDs, so a stripped-down artifact will still fall back to default content even after a successful migration.

Correct

bash

undefined

在将内容承载型应用的新版本安装到

master

环境前，请确认应用注册表中的工件确实包含当前商家内容引用的区块。

vtex publish

成功不代表工件包含商家的自定义内容。

重要性说明

常见的失败场景是从精简版仓库或丢失商家已编辑数月的自定义区块的基础主题分支发布。安装可成功完成，但

pages-graphql

无法解析商家存储内容中引用的区块，店铺前端会回退到默认内容。工件与内容不匹配。

检测方式

若发布版本是从不包含当前主题依赖的自定义区块的仓库构建的，请停止操作。从正确的源代码重新发布。

updateThemeIds

迁移仅能更新内容的键；无法解决区块ID缺失问题，因此即使迁移成功，精简版工件仍会回退到默认内容。

正确操作

bash

undefined

pull the published artifact and confirm it ships the custom blocks

拉取已发布的工件并确认包含自定义区块

vtex apps files acme.store-theme@5.3.5 store/ | grep -E 'umMaisUm|customHeader'

matches the block IDs the active theme depends on

匹配当前主题依赖的区块ID


**Wrong**

```bash
vtex publish
vtex install acme.store-theme@5.3.5


**错误操作**

```bash
vtex publish
vtex install acme.store-theme@5.3.5

published artifact is the boilerplate fork; it is missing every custom block

发布的工件是模板分支；缺失商家存储内容中引用的所有自定义区块

referenced in the merchant's stored content

—

undefined

undefined

Constraint: Treat

vtex workspace promote

as a 3-way mine-wins merge of pages-graphql VBase, not a wipe

约束：将

vtex workspace promote

视为pages-graphql VBase的三方「我方获胜」合并，而非覆盖

vtex workspace promote

MUST be planned as a merge between the dev workspace and master, not as a destructive replacement of master's

vtex.pages-graphql

VBase content. The service uses

MineWinsConflictsResolver

from

@vtex/api

: it diffs

base

(the master state the dev workspace forked from),

master

(current master), and

mine

(the dev workspace), and resolves conflicts in favor of the dev workspace.

Why this matters

Master keys that the dev workspace never touched are preserved on promote. Conflicting keys (something edited in both master and the dev workspace after the fork point) are overwritten by the dev workspace's value. Two practical consequences for a theme rollout:

If merchants continue to edit Site Editor in master while the dev workspace is being prepared, those edits to keys the dev workspace also touches will be lost on promote.
After
```
updateThemeIds
```
runs in the dev workspace, the dev workspace owns the new-major content map; promoting it cleanly transfers the rekeyed Site Editor edits, Pages, and Redirects into master via mine-wins.

In production, every conflict resolution writes a per-minute snapshot of

base

master

, and

mine

to the sibling

userData_backup

VBase bucket inside

vtex.pages-graphql

, logged with

subject: "conflicts_resolution"

. No backup is written when there is no conflict to resolve, so smoke-testing remains the primary safety net.

Detection

If a rollout plan assumes promote will "replace" master content, STOP and rephrase as a merge plan: which keys does the dev workspace touch, which keys is master likely to touch in the same window, and how will conflicts be reconciled. If merchants are actively editing Site Editor in master during the rollout window, STOP and either pause those edits, narrow the rollout window, or document which keys will be overwritten.

Correct

text

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.

Wrong

text

"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.

vtex workspace promote

必须被规划为开发工作区与

master

环境的合并操作，而非破坏性地替换

master

环境中

vtex.pages-graphql

的VBase内容。该服务使用

@vtex/api

中的

MineWinsConflictsResolver

：对比

base

（开发工作区从

master

环境分叉时的状态）、

master

（当前

master

环境状态）和

mine

（开发工作区状态），冲突时以开发工作区的内容为准。

重要性说明

开发工作区未触及的

master

环境键会在发布后保留。冲突键（分叉后

master

环境和开发工作区都编辑过的键）会被开发工作区的值覆盖。主题发布有两个实际影响：

若商家在准备开发工作区期间继续在
```
master
```
环境中编辑Site Editor，那些与开发工作区触及的键冲突的编辑内容会在发布后丢失。
在开发工作区中运行
```
updateThemeIds
```
后，开发工作区拥有新主版本的内容映射；发布可通过「我方获胜」机制将更新键后的Site Editor编辑内容、页面及重定向干净地同步到
```
master
```
环境。

在生产环境中，每次冲突解决都会将

base

、

master

和

mine

的每分钟快照写入

vtex.pages-graphql

的同级

userData_backup

VBase存储桶，并在

io_vtex_logs

中记录

subject: "conflicts_resolution"

。无冲突时不会生成备份，因此冒烟测试仍是主要的安全保障。

检测方式

若发布计划假设发布会「替换」

master

环境内容，请停止并重新规划为合并计划：开发工作区会触及哪些键，

master

环境在同一窗口可能触及哪些键，如何协调冲突。若商家在发布窗口期间仍在

master

环境中编辑Site Editor，请停止操作，要么暂停这些编辑，要么缩小发布窗口，要么记录哪些键会被覆盖。

正确操作

text

与商家运营团队协调发布窗口：
- 从开发工作区运行`updateThemeIds`到`vtex workspace promote`完成期间，暂停`master`环境中的Site Editor编辑操作。
- 在开发工作区进行冒烟测试，然后发布。
- 发布后，验证`master`环境中的店铺前端→Site Editor、页面、重定向。

若出现冲突解决日志（subject: "conflicts_resolution"），
记录pages-graphql在`io_vtex_logs`中显示的备份路径。
快照存储在vtex.pages-graphql的`userData_backup`存储桶中，
可通过VBase v2 API获取，用于支持团队处理问题。

错误操作

text

"发布会替换master环境内容，因此无需协调。"
- 商家在发布期间继续在master环境中编辑Site Editor。
- 发布时通过「我方获胜」机制合并这些编辑内容；所有冲突键都会
  被开发工作区的值静默覆盖。
- 若无冒烟测试或协调，丢失的编辑内容直到购物者报告内容缺失才会被发现。

Preferred pattern

推荐模式

Recommended deploy flow for any change to a content-holding app installed on

master

text

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 vendor.app@X.Y.Z

5. If the bump crosses a MAJOR boundary (including downgrades such as 5.x → 4.x):
   a. vtex install vtex.admin-graphql-ide@3.x   (if not already installed)
   b. vtex browse admin/graphql-ide
   c. In the IDE, select the app `vtex.pages-graphql@2.x` 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.

Recommended emergency rollback after a broken major install on

master

text

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 vtex.pages-graphql@2.x 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.

Recommended way to think about content-key behavior:

text

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

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

针对

master

环境中内容承载型应用的任何变更，推荐的部署流程：

text

1. 谨慎决定SemVer版本升级类型
   - patch  →  bug修复，无区块契约变更
   - minor  →  添加新的可选区块，向后兼容的新增功能
   - major  →  任何破坏现有区块契约的结构性变更
              （尽可能避免；需要执行updateThemeIds迁移）

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

3. 切换到带生产标记的开发工作区
   （vtex use可一步完成创建和切换）
   vtex use theme-rollout-YYYY-MM-DD --production

4. 在开发工作区安装新版本
   vtex install vendor.app@X.Y.Z

5. 若版本升级跨越主版本边界（包括降级，如5.x → 4.x）：
   a. vtex install vtex.admin-graphql-ide@3.x   （若尚未安装）
   b. vtex browse admin/graphql-ide
   c. 在IDE中，从下拉菜单选择应用`vtex.pages-graphql@2.x`
   d. 运行：
        mutation {
          updateThemeIds(
            from: "{appVendor}.{appName}@{oldMajor}.x",
            to:   "{appVendor}.{appName}@{newMajor}.x"
          )
        }
      请保留两个键中的字面量"x"；不要将其替换为minor或patch版本号，否则mutation会静默失败。
   e. 预期响应：{ "data": { "updateThemeIds": true } }
   若版本升级为同一主版本内的patch或minor，跳过此步骤——
   内容键会自动保留。

6. 在开发工作区对全页面集合进行冒烟测试
   - $workspace--$account.myvtex.com/             （首页）
   - $workspace--$account.myvtex.com/<pdp-slug>/p （商品详情页）
   - $workspace--$account.myvtex.com/<category>   （商品列表页）
   - $workspace--$account.myvtex.com/<dept>       （分类页）
   - $workspace--$account.myvtex.com/<search>?_q  （搜索页）
   - 任何/institucional/*或其他自定义路由
   - VTEX Admin → 店铺前端 → Site Editor、页面、重定向
   - 账户、登录、购物车、结账入口

7. 若出现任何问题：停止操作。不要发布。进行排查。
   若所有内容渲染正常：
   - 与商家运营团队协调发布窗口，确保在开发工作区运行`updateThemeIds`到`vtex workspace promote`完成期间，
     没有Site Editor编辑内容提交到master环境。发布操作会针对pages-graphql VBase执行三方「我方获胜」合并，
     因此任何冲突的master环境编辑内容都会被开发工作区覆盖。
   - vtex workspace promote

8. 在$account.myvtex.com（master环境）和公网域名上重新测试。
   - 验证master环境中的店铺前端→Site Editor、页面、重定向。
   - 若公网CDN提供过期内容，使用缓存清除查询字符串验证；边缘节点会在正常TTL后刷新。
   - 若`io_vtex_logs`显示该账号在发布时间前后有`vtex.pages-graphql`的`subject: "conflicts_resolution"`条目，
     记录列出的备份路径。这些路径存储在pages-graphql的`userData_backup`存储桶中，
     若后续需要恢复，可通过VBase v2 API获取。

9. 保留开发工作区至少一个工作日，以便快速重新发布。

针对

master

环境中失败的主版本安装，推荐的紧急回滚流程：

text

1. vtex use rollback-YYYY-MM-DD --production
   （vtex use可一步完成创建和切换；没有`vtex workspace create`命令）
2. vtex install vendor.store-theme@<previous major version>
3. 若回滚跨越主版本边界（几乎总是如此），在vtex.pages-graphql@2.x中运行
   updateThemeIds，将存储的Site Editor编辑内容、页面及重定向从失败的主版本迁移回之前的主版本：

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

4. 对回滚工作区进行端到端冒烟测试（店铺前端页面及
   VTEX Admin → 店铺前端 → Site Editor、页面、重定向）。
5. vtex workspace promote

若`updateThemeIds`返回false、GraphQL IDE显示错误或
迁移后内容未显示，请在发布前联系VTEX支持团队；
不要发布未验证Site Editor内容的工作区。

若之前的发布合并了不需要的内容，重新发布前请检查
`io_vtex_logs`中该账号在原发布时间前后是否有`vtex.pages-graphql`的`subject: "conflicts_resolution"`条目。
该条目列出了`userData_backup`存储桶中的每分钟快照路径（`store/templates.{base|master|mine}.<TS>.json`、
`store/content.{...}.json`、`store/routes.{...}.json`），可通过VBase v2 API获取：

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

该恢复路径需要管理员授权令牌，文档位于
`vtex/pages-graphql`的`TROUBLESHOOTING.md`中。请将其视为支持团队主导的
问题排查方式，而非常规自助步骤，并始终先在非master环境的工作区中测试恢复的内容。

理解内容键行为的推荐方式：

text

Patch / minor版本升级
   acme.store-theme @ 0.0.61  →  0.0.62
   存储键前缀不变：acme.store-theme@0.x:*
   商家内容自动延续

Major版本升级
   acme.store-theme @ 0.0.61  →  5.0.0
   存储键前缀变更：acme.store-theme@0.x:*  →  acme.store-theme@5.x:*
   从解析器的角度来看，新版本初始为空
   在带生产标记的开发工作区中，针对vtex.pages-graphql@2.x运行updateThemeIds，
   将Site Editor编辑内容、页面及重定向的键从acme.store-theme@0.x更新为acme.store-theme@5.x，然后发布

Common failure modes

常见失败模式

Running
```
vtex release major
```
on a theme to "clean up" the version number, not realizing it requires the
```
updateThemeIds
```
migration before promote.
Installing a new theme major directly on
```
master
```
because the dev workspace "looked the same".
Publishing from a forked repository that does not contain the custom blocks the active theme depends on.
```
updateThemeIds
```
rekeys content but cannot resolve missing block IDs.
Treating
```
vtex link
```
as equivalent to
```
vtex install
```
for content-holding apps.
```
link
```
does not exercise the published artifact resolution path or the major-keyed content lookup.
Running
```
vtex workspace promote
```
from a workspace that was never smoke-tested end-to-end.
Promoting a major bump without running
```
updateThemeIds
```
first, so the storefront goes live with default
```
vtex.store-theme
```
content for every page that previously depended on Site Editor edits.
Reaching for a non-existent
```
vtex workspace create
```
command. The CLI creates a workspace as a side effect of
```
vtex use {workspaceName} --production
```
; that single command both creates and switches.
Replacing the literal
```
x
```
in
```
updateThemeIds
```
arguments with a minor or patch number (
```
acme.store-theme@5.0.0
```
instead of
```
acme.store-theme@5.x
```
). The mutation requires the major-with-x form and silently no-ops otherwise.
Running
```
updateThemeIds
```
against the wrong app in the GraphQL IDE dropdown. The mutation only exists in
```
vtex.pages-graphql@2.x
```
.
Trusting the public domain to confirm a fix immediately after promotion. CloudFront serves stale content; use
```
?utm_source=<value>
```
or another cache-busting parameter to bypass the edge during validation.
Forgetting that downgrades (for example
```
5.x
```
→
```
4.x
```
) also cross a MAJOR boundary and need their own
```
updateThemeIds
```
run before promote.
Assuming
```
vtex workspace promote
```
wipes master
```
vtex.pages-graphql
```
VBase content and re-fills it from the dev workspace. It does not — it 3-way merges with mine-wins, so master keys not touched by the dev workspace survive, and master keys that are also touched by the dev workspace get overwritten silently. Coordinate the rollout window with merchant ops to avoid losing concurrent Site Editor edits in master.
Treating the
```
userData_backup
```
bucket inside
```
vtex.pages-graphql
```
as a routine restore endpoint. It is only written when conflicts are resolved (no conflict, no backup), it requires admin-level auth and the VBase v2 API, and it is a support-led TROUBLESHOOTING surface — not a substitute for smoke-testing or for the
```
updateThemeIds
```
flow.

为了「清理」版本号而对主题执行
```
vtex release major
```
，未意识到发布前需要执行
```
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
```
替换为minor或patch版本号（如
```
acme.store-theme@5.0.0
```
而非
```
acme.store-theme@5.x
```
）。该mutation要求使用主版本加x的格式，否则会静默失败。
在GraphQL IDE下拉菜单中选择错误的应用运行
```
updateThemeIds
```
。该mutation仅存在于
```
vtex.pages-graphql@2.x
```
中。
发布后立即信任公网域名确认修复。CloudFront会提供过期内容；验证时请使用
```
?utm_source=<value>
```
或其他缓存清除参数绕过边缘节点。
忘记降级（如
```
5.x
```
→
```
4.x
```
）也跨越主版本边界，发布前需要执行
```
updateThemeIds
```
。
假设
```
vtex workspace promote
```
会清除
```
master
```
环境中
```
vtex.pages-graphql
```
的VBase内容并从开发工作区重新填充。实际并非如此——它会执行三方「我方获胜」合并，因此开发工作区未触及的
```
master
```
环境键会保留，而开发工作区触及的
```
master
```
环境键会被静默覆盖。请与商家运营团队协调发布窗口，避免丢失
```
master
```
环境中并发的Site Editor编辑内容。
将
```
vtex.pages-graphql
```
中的
```
userData_backup
```
存储桶视为常规恢复端点。仅在解决冲突时才会生成备份（无冲突则无备份），它需要管理员级别的授权和VBase v2 API，是支持团队主导的问题排查工具——不能替代冒烟测试或
```
updateThemeIds
```
流程。

Review checklist

审核检查清单

Is the proposed version bump correctly classified as patch, minor, or major against SemVer rules?
If the bump crosses a major boundary, is there a documented
```
updateThemeIds
```
migration step in the production-flag dev workspace (in either direction, including downgrades)?
Is the install going to a production-flag dev workspace first (
```
vtex use $name --production
```
), never directly to
```
master
```
?
If the bump is major, has
```
updateThemeIds
```
been run against
```
vtex.pages-graphql@2.x
```
from the GraphQL Admin IDE, and has the response been
```
{ "updateThemeIds": true }
```
?
Has the published artifact been verified to contain the custom blocks the active theme depends on?
Has the dev workspace been smoke-tested across home, PDP, PLP, department, search, custom routes, account, checkout entry, and the Storefront module (Site Editor, Pages, Redirects)?
Has the rollout window been coordinated so that no concurrent Site Editor edits land on master between the dev workspace's
```
updateThemeIds
```
and
```
vtex workspace promote
```
, given the 3-way mine-wins merge?
After promote, has
```
io_vtex_logs
```
been checked for a
```
subject: "conflicts_resolution"
```
entry on
```
vtex.pages-graphql
```
for this account, and (if present) have the listed
```
userData_backup
```
paths been recorded for support escalation?
Is the dev workspace retained for at least one business day after promotion in case a fast re-promote is needed?

提议的版本升级是否根据SemVer规则正确分类为patch、minor或major？
若版本升级跨越主版本边界，是否在带生产标记的开发工作区中记录了
```
updateThemeIds
```
迁移步骤（包括降级等任何方向的迁移）？
安装是否先在带生产标记的开发工作区中进行（
```
vtex use $name --production
```
），而非直接安装到
```
master
```
环境？
若版本升级为major，是否已通过GraphQL Admin IDE针对
```
vtex.pages-graphql@2.x
```
运行
```
updateThemeIds
```
，且响应为
```
{ "updateThemeIds": true }
```
？
是否已验证发布的工件包含当前主题依赖的自定义区块？
是否已对开发工作区的首页、PDP、PLP、分类页、搜索页、自定义路由、账户页、结账入口及店铺前端模块（Site Editor、页面、重定向）进行冒烟测试？
是否已协调发布窗口，确保在开发工作区运行
```
updateThemeIds
```
到
```
vtex workspace promote
```
完成期间，
```
master
```
环境中没有并发的Site Editor编辑内容（考虑到三方「我方获胜」合并机制）？
发布后，是否检查了
```
io_vtex_logs
```
中该账号的
```
vtex.pages-graphql
```
是否有
```
subject: "conflicts_resolution"
```
条目，且（若存在）记录了列出的
```
userData_backup
```
路径用于支持团队处理问题？
开发工作区是否在发布后保留至少一个工作日，以便快速重新发布？

Related skills

Reference

参考资料

Manifest — How
```
vendor
```
,
```
name
```
, and
```
version
```
form the app identity used in storefront content keys.
Versioning an App —
```
vtex release
```
and the SemVer rules that decide whether a bump preserves or invalidates downstream content keys.
Publishing an App — How
```
vtex publish
```
produces the artifact installed by
```
vtex install
```
.
Installing an App — Workspace scope of
```
vtex install
```
and why dev workspaces must be production-flag for realistic testing.
Creating a Production Workspace —
```
vtex use {workspaceName} --production
```
is the single command that both creates and switches to a production-flag workspace.
Promoting a Workspace to Master —
```
vtex workspace promote
```
as the atomic cutover from a production-flag dev workspace to
```
master
```
.
Migrating CMS settings after a major theme update — Official procedure for the
```
updateThemeIds
```
mutation in
```
vtex.pages-graphql@2.x
```
, including the GraphQL IDE setup and the literal
```
MAJOR.x
```
argument format.
```
vtex/pages-graphql
```
```
TROUBLESHOOTING.md
```
— How
```
MineWinsConflictsResolver
```
writes per-minute
```
base
```
,
```
master
```
, and
```
mine
```
snapshots into the
```
userData_backup
```
bucket of
```
vtex.pages-graphql
```
and how to fetch them via the VBase v2 API for support-led recovery (internal VTEX repo).
Store Framework — Why theme apps own
```
store/
```
content and how Store Framework consumes it at render time.

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 —
```
vtex.pages-graphql@2.x
```
中
```
updateThemeIds
```
mutation的官方流程，包括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在渲染时如何使用这些内容。

vtex-io-storefront-theme-versioning

Original

Translation

Storefront Theme Versioning, Install, and Rollback

店铺前端主题的版本管理、安装与回滚

When this skill applies

本指南适用场景

Decision rules

决策规则

Hard constraints

硬性约束

Constraint: Major version bumps on content-holding apps require an updateThemeIds migration before promote

约束：内容承载型应用升级主版本时，发布前必须执行updateThemeIds迁移

In the IDE, select the app vtex.pages-graphql@2.x from the dropdown and run:

在IDE中，从下拉菜单选择应用vtex.pages-graphql@2.x并运行：

mutation {

mutation {

updateThemeIds(

updateThemeIds(

from: "acme.store-theme@0.x",

from: "acme.store-theme@0.x",

to: "acme.store-theme@5.x"

to: "acme.store-theme@5.x"

)

)

}

}

Expected response: { "data": { "updateThemeIds": true } }

预期响应：{ "data": { "updateThemeIds": true } }

Validate Site Editor, Pages, and Redirects in this workspace, then:

验证该工作区中的Site Editor、页面及重定向，然后执行：

installed straight to master — no merchant content is visible under @5.x

直接安装到master环境——@5.x版本下无任何商家内容

and the storefront falls back to default vtex.store-theme content

店铺前端回退到默认的vtex.store-theme内容

Constraint: Never install a content-holding app version directly to master without a dev-workspace smoke test

约束：不得直接将内容承载型应用版本安装到master环境，必须先在开发工作区进行冒烟测试

if this install crosses a MAJOR boundary, run updateThemeIds before smoke tests.

若该安装跨越主版本边界，在冒烟测试前运行updateThemeIds。

fetch home, PDP, PLP, search, custom routes from $workspace--$account.myvtex.com

从$workspace--$account.myvtex.com获取首页、PDP、PLP、搜索页、自定义路由

only after smoke tests pass:

仅在冒烟测试通过后执行：

any failure is now public

任何故障都会立即公开

Constraint: Verify the published artifact matches the source you expect

约束：验证发布的工件与预期源代码一致

pull the published artifact and confirm it ships the custom blocks

拉取已发布的工件并确认包含自定义区块

matches the block IDs the active theme depends on

匹配当前主题依赖的区块ID

published artifact is the boilerplate fork; it is missing every custom block

发布的工件是模板分支；缺失商家存储内容中引用的所有自定义区块

referenced in the merchant's stored content

Constraint: Treat vtex workspace promote as a 3-way mine-wins merge of pages-graphql VBase, not a wipe

约束：将vtex workspace promote视为pages-graphql VBase的三方「我方获胜」合并，而非覆盖

Preferred pattern

推荐模式

Common failure modes

常见失败模式

Review checklist

审核检查清单

Related skills

相关指南

Reference

参考资料

Constraint: Major version bumps on content-holding apps require an
`updateThemeIds`
migration before promote

约束：内容承载型应用升级主版本时，发布前必须执行
`updateThemeIds`
迁移

In the IDE, select the app
`vtex.pages-graphql@2.x`
from the dropdown and run:

在IDE中，从下拉菜单选择应用
`vtex.pages-graphql@2.x`
并运行：

Constraint: Treat
`vtex workspace promote`
as a 3-way mine-wins merge of pages-graphql VBase, not a wipe

约束：将
`vtex workspace promote`
视为pages-graphql VBase的三方「我方获胜」合并，而非覆盖