在 VTEX IO 主题应用中组装店面页面树、自定义路由与…

设计或修改 VTEX IO storefront 主题应用（拥有 store/blocks.json、store/routes.json、store/templates/、store/contentSchemas.json 及页面树）时，如何正确声明 builder、依赖基础主题、组合块、声明路由并暴露可编辑内容。

适用场景

解决思路

1. 在 manifest.json 的 builders 中声明 "store"，否则 store/ 下的文件不会被处理，主题对店面毫无贡献。
2. 在 manifest.json 的 dependencies 中依赖一个基础主题（通常是 vtex.store-theme），从而继承其所有页面模板、块声明和默认内容；除非明确要自行承担所有原生模板的维护。
3. 用 store/blocks.json（或 store/blocks/ 下的按模板文件）按页面模板定义块树，通过引用块 ID 组装页面；块 ID 来自组件应用的 store/interfaces.json，并按声明应用的 MAJOR 版本作用域。
4. 确保 store/blocks.json 中引用的每个块 ID 都能在已安装应用的 interfaces.json 中解析，且 MAJOR 版本与 manifest.json 依赖范围一致，否则会出现 Missing block 错误导致页面渲染失败。
5. 用 store/routes.json 定义自定义店面路由，并将其绑定到真实的页面上下文（store.custom、store.product、store.search 等）；原生路由（/、/{slug}/p、搜索）来自基础主题，通常无需重新声明。
6. 为 store/routes.json 中每个路由确认：path 不与原生 VTEX 路径冲突、绑定的页面 ID 在 store/blocks.json 中存在对应模板、context 与页面实际所需数据匹配。
7. 用 store/contentSchemas.json 声明块的 Site Editor 可编辑 props，让商家能修改文案和图片，而不是把内容硬编码在 props 中。
8. 有意识地选择变更位置：主题应用的 store/ JSON 负责组合、路由、默认内容和允许的子块（promote 后立即影响所有购物者）；组件应用代码负责块的 React 行为（按自身版本节奏发布）；Site Editor 负责商家在主题默认值之上的内容覆盖（由 vtex.pages-graphql 存储，按声明应用的已安装 major 作用域）。
9. 优先扩展基础主题而不是 fork 它；fork 会把每个块、路由和模板的维护责任永久转移到你的应用，包括上游的 bug 修复。
10. 把店面页面保持为块树：叶子是组件块，分支是容器块（flex-layout.row、flex-layout.col 等）；在满足设计的前提下尽量保持树浅，深树会膨胀渲染和内容占用。
11. 把主题应用当作内容持有型应用：其已安装 major 版本是平台为商家针对该应用声明的块所保存的每个 Site Editor 变更的键的一部分，因此其版本契约面向商家而非开发者。
12. 按推荐结构组织主题应用：manifest.json（store builder、基础主题依赖）、messages/（本地化字符串）、store/blocks.json（全局块声明）、store/routes.json（自定义路由）、store/contentSchemas.json（Site Editor 可编辑 props）、store/blocks/（按模板的块树，如 home.jsonc、product.jsonc、search.jsonc、category.jsonc、custom/about.jsonc、custom/stores.jsonc）。
13. 组合 store.home 时使用容器块包裹叶子块，例如 store.home 的 blocks 列出 flex-layout.row#home-hero、shelf#home-best-sellers、rich-text#home-newsletter，再为 flex-layout.row#home-hero 声明 children 为 image#hero-banner，并为 image#hero-banner 设置 props（src、alt）。
14. 声明自定义机构路由时，在 store/routes.json 中为 store.custom#about 设置 path（如 /institucional/sobre）和 context（如 vtex.store-resources/InstitutionalPageContext），并在 store/blocks/custom/about.jsonc 中声明匹配的 store.custom#about 模板及其块树。
15. 为 Site Editor 可编辑表面编写 contentSchemas.json，例如为 rich-text#about-copy 声明 type 为 object、properties.text 为 string 并带 title 和 widget（如 ui:widget 为 textarea）；商家对 text 的编辑由 vtex.pages-graphql 以包含主题应用 MAJOR 版本的键持久化。
16. 避免在 store/blocks.json 中把 Site Editor 可编辑文案直接放进 props 而不提供 contentSchemas.json，否则商家无法修改。
17. 避免在 store/routes.json 中添加自定义路由却不添加匹配的 store.custom#<id> 模板到 store/blocks.json。
18. 避免把 React 组件代码放进主题应用，应放在专门的组件应用中，以免混淆块声明与块消费并影响复用。
19. 避免在主题 store/ 文件中存储运营数据或购物者特定数据；主题是全局的，按购物者或按分群的数据应放在别处。
20. 避免在两个不同应用中声明同一个块 ID，否则渲染时解析不确定。
21. 避免把主题应用版本当作面向开发者随意提升 major 来“整理”，这会使新 major 没有商家内容，并需要在 promote 前用 vtex.pages-graphql@2.x 的 updateThemeIds 迁移。
22. 在评审时检查：manifest.json 是否声明 store builder；是否依赖基础主题或明确有意完全拥有原生模板；store/blocks.json 中每个块 ID 是否在已安装应用中以匹配 major 解析到真实 interfaces.json 条目；store/routes.json 中每个条目是否有有效 path、context 和匹配模板；商家可编辑文案与图片字段是否通过 contentSchemas.json 暴露；React 组件是否留在专门组件应用中；团队是否考虑过计划变更是否会强制这个内容持有型应用提升 major。

适用边界 · 注意事项

• 注册组件应用中的新块（store/interfaces.json）——应使用 vtex-io-render-runtime-and-blocks。
• 实现块背后的 React 组件——应使用 vtex-io-storefront-react。
• 更改 master 上主题应用的已安装版本——应使用 vtex-io-storefront-theme-versioning。
• 处理本地化字符串——应使用 vtex-io-messages-and-i18n。