将应用主页构建为 UI 扩展

从 API 版本 2026-07 开始，自定义分发应用可使用 App Home UI 扩展。它们允许你使用 admin.app.home.render 目标将应用的 App Home 页面构建为由 Shopify 托管的 Preact UI 扩展，从而使轻量级应用能够在不托管独立 Web 应用的情况下提供主要管理工作区。

iframe 模型仍然是大多数应用的首选方案，尤其是面向公众的应用以及需要服务端逻辑的应用。对于符合运行时约束的仅扩展型应用，App Home UI 扩展提供了更简单的实现路径。

当前的 App Home

每个 Shopify 应用都在 Shopify 管理后台拥有一个主要体验区域，称为 App Home。商家在此配置设置、查看数据并管理工作流。

长期以来，开发者一直使用由开发者托管的 iframe 模型来构建 App Home。你可以通过 Shopify CLI 生成应用脚手架，使用首选的 Web 框架进行开发，自行托管该应用，然后 Shopify 会将该应用嵌入到管理后台中。

对于大多数应用而言，该模型仍然是正确的默认选择，因为它让你能够充分利用整个 Web 平台：

• 使用任何 Web 框架。
• 托管服务端逻辑和后端路由。
• 使用完整的浏览器 API。
• 构建多页面和全栈应用体验。
• 使用 App Bridge API、App Bridge Web 组件、Polaris Web 组件以及 GraphQL Admin API。
• 通过公开或自定义渠道发布应用。

对于许多应用来说，这种灵活性正是 App Home 所需要的。

iframe 模型可能超出你的需求

有些应用并不需要完整的由开发者托管的 Web 应用来渲染其主要的管理工作区。例如，采用自定义分发渠道的应用可能主要基于扩展；内部工作流应用可能只包含一个简单的仪表板、设置流程或资源管理器；而仅扩展型应用甚至可能不需要服务端渲染、Webhook 或独立的后端服务。

在这些情况下，iframe 模型可能会引入并非应用工作流核心的基础设施。即使应用的主要 UI 可以与应用的其余部分在同一扩展模型中运行，你仍然需要一个托管的 Web 界面作为 App Home。

App Home UI 扩展为这些应用提供了另一种选择。

推出 App Home UI 扩展

App Home UI 扩展是一种由 Shopify 托管的构建 App Home 页面的方式。与其为主工作区托管基于 iframe 的 Web 应用，不如构建一个针对 admin.app.home.render 的 Preact UI 扩展。

在 shopify.extension.toml 中配置该扩展：

api_version = "2026-07" [[extensions]] name = "t:name" type = "ui_extension" [[extensions.targeting]] module = "./src/AppHome.jsx" target = "admin.app.home.render"

通过此模型，您的 App Home 页面在管理扩展运行时中运行，使用 Polaris Web 组件进行渲染，并作为应用版本的一部分进行部署。Shopify 托管该扩展，因此无需单独部署或维护 App Home Web 服务器。

工作原理

App Home UI 扩展并非为所有应用替换基于 iframe 的 App Home。它们为自定义分发应用提供了一条专注的路径，当扩展运行时足以满足应用主工作区的需求时即可使用。

1. App Home 成为扩展目标：admin.app.home.render 目标将你的扩展渲染到 Shopify 管理界面的 App Home 区域。你的扩展入口模块指向一个 Preact 文件，例如 extensions/app-home/src/AppHome.jsx。生成的模板可以使用客户端路由来实现简单的多页流程。例如，单个 App Home UI 扩展可以从同一个入口模块渲染主页、详情页和未找到页面。

2. 你的 UI 随扩展包一起发布：App Home UI 扩展与其他应用扩展并存。Shopify CLI 会创建一个包含扩展配置和源文件的 extensions/app-home/ 文件夹。这意味着应用的主要 UI 可以与应用其余部分共享相同的基于扩展的工作流。你可以使用 shopify app dev 进行预览，并使用 shopify app deploy 作为应用版本的一部分进行部署。

3. Shopify 托管 App Home 界面：由于 Shopify 托管了该扩展，因此你无需为 App Home 页面执行单独的托管步骤。当应用的主工作区是一个完全可以在扩展运行时中运行的轻量级仪表板、配置页面、资源管理器或引导式工作流程时，这非常有用。

4. 运行时存在限制：App Home UI 扩展有意比 iframe 模型更具限制性。仅在这些限制符合你的应用需求时才使用此模型：

• App Home UI 扩展适用于自定义分发应用。

• 运行时使用 Preact。

• UI 使用 Polaris Web 组件构建。

• 与开发者自托管的 Web 应用相比，浏览器 API 受到一定限制。

• 压缩后的包大小限制为 64 KB。

• 如果您发现当前运行时已无法满足需求，可以将 App Home 体验重新开发为基于 iframe 的应用。

  如果您的应用需要公开分发、服务端逻辑、Webhook、不受限制的浏览器 API 或 Web 框架的全部灵活性，请继续使用 iframe 模型。

开始使用

您可以使用 Shopify CLI 创建一个仅包含扩展且带有 App Home UI 扩展的新应用脚手架：

1. 运行 shopify app init。
2. 在提示时选择 Build an extension-only app。
3. 打开 extensions/app-home/shopify.extension.toml 并确认扩展针对 admin.app.home.render。
4. 运行 shopify app dev 并选择你的开发商店。
5. 按 p 以打开预览 URL，并在 Shopify 管理界面中测试 App Home 页面。
6. 使用 shopify app deploy 将扩展作为应用版本的一部分进行部署。

你还可以通过运行 shopify app generate extension 并将 App home 添加到现有应用中，在提示时进行选择。

相关文档

• App Home 中的应用
• App Home UI 扩展
• App Home UI 扩展参考
• 配置应用扩展
• 构建仅包含扩展的应用