shopify CLI国内开发配置

Shopify CLI 是开发 Shopify 应用和主题的重要工具,但在中国等网络受限地区使用时常遇到困难。
官方仓库有一些 issue 都提到了这些问题, 但是官方一直没有加对应的配置。
比如: [Bug]: Execute Shopify theme dev with error message: request to xxx.theme.json?xxx processing failed, reason: read ETIMEDOUT
本文将指导你如何正确配置 Shopify CLI,以便在中国顺利进行 Shopify 开发。

2025/05/18 更新 官方已经加入了 proxy 参数
参考: Release Note 3.78

Add HTTP proxy support with the environment variables SHOPIFY_HTTP_PROXY and SHOPIFY_HTTPS_PROXY

主要问题

  1. Shopify CLI 默认不支持配置代理
  2. 不读取系统环境变量
  3. 内置的 Cloudflare tunneling 在中国连接不稳定

本指南基于 Shopify CLI 3.67.1 版本。

配置代理

为全局安装的 Shopify CLI 配置代理需要修改其源代码。以下是详细步骤:

1. 定位 Shopify CLI 安装目录

根据安装方式,Shopify CLI 的位置可能如下:

  • 通过 npm 全局安装:
    • Windows: C:\Users\<username>\AppData\Roaming\npm\node_modules
    • Linux/Mac: /usr/local/lib/node_modules
  • 使用 NVM 安装 Node.js:
    • 在 NVM 目录下查找,如: F:\program\nvm\v20.12.0\node_modules\@shopify

2. 修改运行脚本

  1. 进入cli\bin目录
  2. 备份run.js文件
  3. 全局安装global-agent: npm install -g global-agent
  4. 编辑run.js,在文件顶部添加以下代码:
1
2
3
4
5
6
7
8
9
10
11
12
13
import { bootstrap } from "global-agent";
if (
  process.env.GLOBAL_AGENT_HTTP_PROXY ||
  process.env.GLOBAL_AGENT_HTTPS_PROXY
) {
  bootstrap();
  console.log(
    `Using proxy: ${
      process.env.GLOBAL_AGENT_HTTP_PROXY ||
      process.env.GLOBAL_AGENT_HTTPS_PROXY
    }`
  );
}

修改后的完整run.js文件内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
#!/usr/bin/env node

import { bootstrap } from "global-agent";
if (
  process.env.GLOBAL_AGENT_HTTP_PROXY ||
  process.env.GLOBAL_AGENT_HTTPS_PROXY
) {
  bootstrap();
  console.log(
    `Using proxy: ${
      process.env.GLOBAL_AGENT_HTTP_PROXY ||
      process.env.GLOBAL_AGENT_HTTPS_PROXY
    }`
  );
}

process.removeAllListeners("warning");

import runCLI from "../dist/index.js";

runCLI({ development: false });

3. 设置代理环境变量

在命令行中设置代理环境变量:

1
2
set GLOBAL_AGENT_HTTP_PROXY=http://your_proxy_host:your_proxy_port
set GLOBAL_AGENT_HTTPS_PROXY=http://your_proxy_host:your_proxy_port

PowerShell 中使用:

1
2
$env:GLOBAL_AGENT_HTTP_PROXY = "http://your_proxy_host:your_proxy_port"
$env:GLOBAL_AGENT_HTTPS_PROXY = "http://your_proxy_host:your_proxy_port"

替代 Tunneling 方案

Shopify CLI 默认使用 Cloudflare 进行 tunneling,但在中国可能连接不稳定。推荐使用 ngrok 作为替代方案:

  1. 安装 ngrok
  2. 按照Shopify 官方文档配置 ngrok

使用 ngrok 可以显著提高 tunneling 的稳定性,为中国开发者提供更流畅的 Shopify 开发体验。

结语

通过以上配置,你应该能够在中国顺利使用 Shopify CLI 进行开发。如果遇到任何问题,欢迎在评论区讨论或查阅 Shopify 官方文档获取更多信息。