Shopify Checkout Extensibility 结账扩展开发

先判断问题出现在哪里

过去很多 Shopify 结账页自定义依赖 checkout.liquid、Additional scripts 或直接注入脚本。现在新项目不应该再围绕这些旧入口设计：Shopify 官方文档已经说明，checkout.liquid 不再支持 Information、Shipping、Payment 这些结账步骤，Thank you / Order status 相关旧脚本也进入迁移周期。

核心逻辑是：从“修改源码”走向“沙盒化扩展（Sandboxed Extensions）”。

现在的主线是 Checkout Extensibility：用 App Extension、Checkout UI Extension、Shopify Functions 和 Web Pixels 分别处理界面、业务规则和追踪。它不是主题代码的一部分，也不是把任意 HTML/CSS/JS 塞进结账页，而是在 Shopify 允许的 target 和组件范围内扩展。像 purchase.checkout.block.render 这类 block target 可以由商家在结账编辑器中放到支持的位置，但最终可用范围要以当前店铺计划、后台入口和 API 版本为准。

实战步骤

步骤 1：初始化 Checkout UI Extension 项目

操作路径：系统终端 -> 使用 Shopify CLI 创建应用

1. 注意：Checkout 扩展不能直接写在主题代码里！它本质上是一个独立的 Shopify App。
2. 运行当前 Shopify CLI 推荐的命令创建新应用，例如 npm init @shopify/app@latest。
3. 进入应用目录后，用 CLI 的 app generate extension 流程生成扩展；命令和模板名称会随 CLI 更新，以命令行提示为准。
4. 选择 Checkout UI extension，并记录生成的 shopify.extension.toml、入口文件和 target 配置。
5. 当前文档默认会持续调整模板技术栈，开发时按项目生成的模板和对应 API 版本写代码，不要照搬旧教程里的包名。

步骤 2：理解 Extension Targets (注入点)

操作路径：在 shopify.extension.toml 中配置

1. 你需要告诉 Shopify，你的这个扩展想要插入到结账页的哪个位置。
2. 常见的 Targets 包括：
   • purchase.checkout.block.render：可以被商家自由拖拽到结账页的任何允许区域。
   • purchase.checkout.cart-line-item.render-after：固定渲染在购物车每个商品的下方（适合做单品相关的提示，如“该商品不支持退换”）。
   • purchase.checkout.contact.render-after：渲染在填写邮箱/手机号的下方（适合做短信订阅的复选框）。

步骤 3：使用专属 UI 组件库编写 React 代码

操作路径：在 src/Checkout.jsx 中编写视图逻辑

1. 重点：不要按主题前端的方式操作 DOM、塞全局 CSS 或依赖浏览器页面里的 window。Checkout UI extension 要使用 Shopify 提供的组件、API 和 target。
2. 下面的代码只用于理解结构；实际开发时请以当前 CLI 生成的模板和对应包名为准。

   import {
     reactExtension,
     Banner,
     BlockStack,
     Text,
     useCartLines
   } from '@shopify/ui-extensions-react/checkout';
   
   export default reactExtension(
     'purchase.checkout.block.render',
     () => <Extension />
   );
   
   function Extension() {
     const cartLines = useCartLines(); // 获取购物车里的商品数据
     
     return (
       <Banner status="warning" title="发货延迟通知">
         <BlockStack>
           <Text>由于极端天气，您的订单预计将延迟 2-3 天发货。</Text>
         </BlockStack>
       </Banner>
     );
   }

3. 使用官方组件的好处是：界面更容易跟随 Shopify 结账体验升级，也能减少样式和可访问性问题。但上线前仍要在测试店铺里检查桌面端、移动端、不同付款方式和多语言场景。

步骤 4：实现高级功能：结账页追加销售 (In-Checkout Upsell)

操作路径：结合 Storefront API 与 ApplyCartLinesChange Hook

1. 在结账页推荐一个低价配件（如“加 $5 购买延长保修”）。
2. 使用 useApplyCartLinesChange() 钩子。
3. 当用户点击扩展中的“添加”按钮时，调用该钩子，传入配件的 Variant ID。
4. Shopify 会重新计算结账上下文。你需要处理失败、库存不足、权限不足和接口延迟等情况，不要把追加销售做成阻塞付款的强依赖。

常见误区与处理方法

误区一：试图在 Checkout 扩展中注入外部的 Google Analytics 或 Facebook Pixel 代码

规避方法：不要把旧版 checkout.liquid 里的追踪脚本照搬到 Checkout UI extension。结账追踪应优先走 Web Pixels 或 Shopify 支持的客户事件机制。Web pixel app extension 运行在受控沙盒里，可以订阅客户事件，但不应该依赖抓取或改写 DOM。

误区二：非 Plus 商家尝试安装高级 Checkout 扩展

规避方法：不要在 App 介绍里笼统承诺“所有 Shopify 店铺都能自定义结账页”。Checkout、Thank you page、Order status page、Functions、Pixels 的可用范围并不完全相同，也会受店铺计划、市场、后台开关和 API 版本影响。开发前要在目标店铺里确认结账编辑器是否能看到你的扩展，并在 App 文档中写清楚适用范围。

误区三：在扩展中发起耗时的外部 API 请求阻塞结账渲染

规避方法：结账页上的外部请求要有超时、缓存和降级方案。比如地址校验服务不可用时，可以隐藏提示或显示保守文案，而不是阻止用户继续付款。结账扩展的原则是：有帮助时出现，异常时安静退场。

常见问题

学习「Shopify 结账页扩展 (Checkout Extensibility) 开发指南」前需要什么基础？

建议先熟悉 HTML、CSS、基础 JavaScript 和 Shopify 后台结构。涉及 Liquid、Section、Schema 或主题工作流的内容，可以边读边在测试主题里练习，不要直接改线上主题。

可以直接在正在使用的线上主题里操作吗？

不建议。主题开发和结构调整应先在复制主题、开发主题或本地环境中完成，确认移动端、产品页、购物车和关键模板正常后，再发布到线上主题。

修改主题前最应该备份什么？

至少保留当前主题副本，并用 Git 记录代码变化。如果文章涉及主题编辑器配置，还要注意模板 JSON 和 settings_data.json 这类配置文件是否需要同步。

遇到教程和后台界面不一致怎么办？

优先以当前 Shopify 后台、主题代码和官方文档为准。Shopify 后台和 CLI 会持续更新，旧截图可用于理解路径，但不能替代当前界面提示。

这类主题开发内容适合什么时候上线到正式店铺？

当改动已经在测试主题中完成移动端、桌面端、产品页、集合页、购物车和速度检查后，再安排上线。影响结账、价格、库存或应用兼容的改动要单独回归。

下一步阅读

• Shopify 主题开发
• 独立站诊断
• 上线检查清单