8.0
热点
AI SCORE
技术实践2026-08-21 04:03
Shopify告别React：Polaris迁移Web Components实战
dev.to · AI#Shopify#Web Components#React迁移
Editor brief · 编辑速览
Shopify正式废弃Polaris React组件库，全面转向CDN交付的Custom Elements。迁移后可减少800KB-1.2MB的客户端JS负担，渲染逻辑推至浏览器原生执行。
执行 Polaris Web Components 迁移不再是 Shopify 应用团队的可选清理任务。随着 Polaris for React 正式废弃，以及 CDN 交付的自定义元素成为管理后台的标准配置，维持单体的 React 包装器会引入不必要的包体积膨胀和脆弱的接口漂移，最终将破坏商家的工作流程。
Shopify 正式归档了遗留的 React 组件库，旨在通过框架无关的自定义元素统一嵌入式 Admin 应用、POS、Checkout 和 Customer Accounts 的用户界面。现在不再需要将数百个 React 组件打包到你的应用构建中，而是直接从 Shopify 边缘服务器加载标准的自定义元素。
历史上，从 @shopify/polaris 导入意味着将大约 800KB 到 1.2MB 的未打包 JavaScript 包直接拉取到客户端分发中。即使使用激进的 tree-shaking 和现代打包器，基础运行时重量也会惩罚 Shopify admin iframe 中的初始页面渲染。新的模型用单个 CDN script 标签替代了本地重量，该标签从 cdn.shopify.com/shopifycloud/polaris.js 提供服务，将组件渲染逻辑推到由 MDN Web Components 规范定义的原生浏览器原语。
在为我们迁移 Shopify Plus 商家的嵌入式应用的工作中，我们发现移除 React 包消除了 App Bridge 版本与 UI 组件之间的依赖漂移。当 Shopify 在管理后台刷新设计令牌、按钮内边距或模态框行为时，你的嵌入式应用会立即继承这些更新，无需进行包升级、重新编译或重新部署。
迁移到 Polaris Web Components 需要剥离 React npm 包、将 Shopify CDN script 标签注入 HTML 文档 head、用 HTML 自定义元素标签替换复合 React 组件，以及安装类型定义。这一过渡将你的前端从 props 驱动的 JSX 抽象迁移到标准 DOM 元素属性和自定义事件监听器。
第一个结构化步骤涉及清理根模板。在标准的 Remix 或 React Router 嵌入式应用中，你移除 AppProvider 包装器，并将 script 标签直接放置在根布局中 App Bridge 旁边：
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
</head>
对于 TypeScript 项目，你不会在这一过渡中失去类型安全。你卸载 @shopify/polaris 并添加 @shopify/polaris-types 作为开发依赖。在 tsconfig.json 中，更新编译器选项以识别自定义元素接口：
{
"compilerOptions": {
"types": ["@shopify/app-bridge-types", "@shopify/polaris-types"]
}
}
完成 Polaris React 到 Web Components 的重构时，你可以使用本地自动化加速组件转换。官方 Dev Assistant 和我们在 Shopify MCP 服务器实现指南中介绍的工具允许你直接在编辑器中检查组件签名并验证自定义元素标记。
Polaris Web Components 通过标准浏览器事件而非合成的 React 回调 props 来传递状态变化。如果你尝试将回调函数如 onAction={handleClick} 传递给自定义元素标签，浏览器会将其视为无效属性并静默丢弃处理器。
自定义元素使用标准 DOM 事件监听器或自定义元素属性来替代声明式回调 props。简单按钮触发标准 click 事件，而复杂组件则分发携带事件详情自定义事件。对于 React 和 Remix 开发者，语法根据框架版本略有不同：
<s-page heading="Order Management">
<s-section heading="Fulfillment Status">
<s-banner tone="info" heading="Batch Processing Active">
<s-paragraph>Orders are being synchronised with the warehouse.</s-paragraph>
</s-banner>
<s-stack gap="base">
<s-button variant="primary" onClick={handleExport}>Export Manifest</s-button>
<s-button variant="secondary" onClick={handleRefresh}>Refresh Feed</s-button>
</s-stack>
</s-section>
</s-page>
模态叠加层等复杂控件需要通过 DOM 元素方法打开和关闭，或直接设置属性属性。而不是在导入的模态组件上控制 open={isOpen} React 状态布尔值，你查询自定义元素引用并调用原生方法如 show() 或 hide()。这种分离使组件逻辑与前端视图层解耦。
选择何时迁移取决于包支持生命周期和扩展边界。由于 Shopify 已停止在公共 Shopify Polaris 仓库上为 React 库发布新功能和修复 bug，所有前瞻性开发必须针对 Web Components。
此比较表明，遗留 React 包现在是纯粹的责任。如果你运营一个产生经常性收入的嵌入式应用，规划 Shopify Polaris Web Components 指南重构应该优先于构建依赖废弃样式钩子的辅助功能。
从 Shopify 边缘 CDN 动态加载 UI 组件保证了你的应用 UI 与 Shopify Admin 重新设计保持一致，但它消除了在 package lockfile 中固定精确组件版本的能力。使用未固定的 CDN script 运行应用就像没有园丁的园艺：你会发现你的主按钮在你工程师睡觉时改变了样式。
由于 CSS 变量或自定义元素 shadow DOM 结构中的破坏性更改可能在没有相应应用部署的情况下进入生产环境，你的 QA 策略必须从构建时单元测试转向自动化运行时视觉回归测试。我们建议在暂存开发商店上配置 Playwright 或 Cypress 运行，按持续 cron 计划执行。
对于运行 UI 扩展的自定义应用和 Plus 品牌，迁移受到平台废弃时间表的严格强制。在 API 版本 2025-10 和 2026-01 上构建的扩展迁移到 remote-dom 和 Preact，直接在沙箱化扩展 worker 中使用 Polaris Web Components。
正如我们在 Shopify Checkout 扩展指南中详述的，Shopify 对 Checkout 扩展执行严格的 64KB 包体积限制。遗留 React 协调引擎消耗了该预算的很大一部分。切换到轻量级 Preact 包装器和原生 Polaris Web Components 大幅减少了扩展包体积，为复杂的商家业务逻辑腾出了空间。
商家和应用开发者需要在 2026 年 10 月 1 日之前完成迁移，届时包含 2026-01 前扩展版本的部署将完全被阻止。提前迁移可防止在高销量销售期间需要发布紧急 Checkout 补丁时出现部署死锁。
今天审计你的嵌入式应用仓库，识别所有对 @shopify/polaris 的活动引用。一个典型的嵌入式应用迁移需要大约 2 到 4 周的工程工作量，主要花在重构自定义数据表、模态触发器和表单状态同步上。
首先通过搭建测试分支、按官方 Shopify App Home 文档添加 CDN script 标签，并将其简单的布局容器如 Page、Layout 和 Card 替换为各自对应的 s-page、s-section 和 s-card 自定义元素，来开始你的工作。如果你的团队管理着大型自定义应用组合或复杂的 Plus 扩展，并且需要专门的工程支持来现代化你的技术栈，我们的团队提供全周期的 Shopify 开发服务来审计、重构和加固你的应用架构。