shopify CLI国内开发配置

  1. 主要问题
  2. 配置代理
    1. 1. 定位 Shopify CLI 安装目录
    2. 2. 修改运行脚本
    3. 3. 设置代理环境变量
  3. 替代 Tunneling 方案
  4. 结语

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 官方文档获取更多信息。

↑ TOP