在 VTEX IO 中将 React 组件注册为…

当需要把 VTEX IO 店面 React 组件暴露为 Store Framework 区块（block），或排查区块映射、组合与版本解析问题时使用。

适用场景

解决思路

1. 在 `store/interfaces.json` 中为每个要暴露给 Store Framework 的区块注册条目，区块 ID（如 `product-reviews`）必须与主题 `store/*.json` 中 `blocks` 引用的 ID 一致。
2. 在 `interfaces.json` 的 `component` 字段中映射到 `react/` 下真实的 React 入口名（如 `ProductReviews`），层级结构时可用嵌套路径（如 `product/ProductReviews`）。
3. 按需使用 `composition`：`children` 表示组件通过 `props.children` 渲染嵌套区块，`blocks` 表示区块暴露由 Store Framework 控制的具名区块插槽；简单区块可只声明 `component`，必要时加 `allowed`。
4. 确保 `composition` 与 `allowed` 反映组件实际的布局与运行时子区块预期，不要声明与实现不符的组合契约。
5. 保证区块 ID 在声明应用的 MAJOR 版本范围内解析：`vtex.pages-graphql` 以 `vendor.app@MAJOR.x:block-id` 为键查找，`0.x` 声明的区块与 `5.x` 声明的同名区块不是同一个。
6. 让消费方主题的依赖范围与声明应用的已安装 major 对齐，避免出现 `Missing block vendor.app@MAJOR.x:block-id` 错误导致页面回退或失败。
7. 将区块契约（`interfaces.json`）与组件实现（`react/`）分离，保持渲染运行时注册清晰独立。
8. 重命名区块 ID 前先与已引用该区块的消费方主题协调，因为对已存储内容而言这等同于破坏性变更。
9. 按最小生命周期接线：在 `store/interfaces.json` 声明区块与组合，在 `store/home.json` 等主题文件中通过 `blocks` 引用，在 `react/` 中提供对应导出组件。
10. 审查时逐项确认：区块是否已在 `interfaces.json` 声明、组件映射是否可解析、组合与允许子区块是否有意为之、运行时注册是否与组件内部实现分离、声明应用已安装 major 是否匹配所有消费方依赖范围。

适用边界 · 注意事项

• 不用于面向购物者的组件内部实现细节。
• 不用于管理后台界面、后端服务或路由设计、策略建模。
• 不用于主题如何将区块组合成页面与路由的问题（应使用 storefront theme 相关技能）。