Shopify结账扩展network_access权限配置无效求助

问题描述 #

开发Shopify结账自定义应用，包含ui_extension类型扩展，需要调用API，已在extensions.toml中设置network_access = true，但仍触发以下错误：

20fa7b5ad880a85d8f39cf44d7b100f6.js:19537 Error fetching banner config: ExtensionUsageError: permission to use fetch() must be specified under [capabilities] with flag "network_access = true"; this can be done within your extension's configuration. View the docs for more information:

当前extensions.toml配置：

api_version = "2025-01"

[[extensions]]
name = "custom-message-block"
handle = "custom-message-block"
type = "ui_extension"

[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "purchase.checkout.block.render"

[extensions.capabilities]
api_access = true
network_access = true

已尝试删除.shopify文件夹并重启应用，问题未解决。

排查思路 #

• 校验TOML配置层级细节
  确认[extensions.capabilities]完全嵌套在[[extensions]]数组块内，避免因换行、空格或隐形字符导致解析异常。建议手动重新输入配置代码，排除复制粘贴带来的格式问题。

• 核对API版本兼容性
  尝试将api_version降级至稳定版本（如2024-10），排查是否是2025-01预览版本的权限配置逻辑变更导致问题。

• 确认扩展点权限支持
  检查purchase.checkout.block.render扩展点的官方权限说明，确认该位置是否允许启用network_access权限，部分结账扩展点可能存在权限限制。

• 更新Shopify CLI版本
  旧版本CLI可能存在配置解析bug，执行对应命令更新CLI：

  npm update -g @shopify/cli
  

  更新后重新构建并启动开发服务。

• 重新部署并清空缓存
  执行shopify app deploy同步配置到Shopify后台；本地开发时重启shopify app dev，同时强制清空浏览器缓存（Ctrl+Shift+R），确保新配置生效。

内容的提问来源于stack exchange，提问作者Dave Clydesdale