Add proxy support for downloads via SPC_PROXY environment variable

config/env.ini

@@ -55,6 +55,8 @@ SPC_ENABLE_LOG_FILE="yes"
 SPC_LOGS_DIR="${WORKING_DIR}/log"
 ; Preserve old logs when running new builds (code checks SPC_PRESERVE_LOG, not SPC_PRESERVE_LOGS)
 SPC_PRESERVE_LOG="no"
+; Proxy for download, example: 'SPC_PROXY=socks5h://127.0.0.1:1080', disabled by default
+SPC_PROXY=""
 
 ; EXTENSION_DIR where the built php will look for extension when a .ini instructs to load them
 ; only useful for builds targeting not pure-static linking

docs/deps-craft-yml.md

@@ -85,4 +85,6 @@ craft-options:
 extra-env:
   # e.g. Use github token to avoid rate limit
   GITHUB_TOKEN: your-github-token
+  # e.g. Route all network operations through a proxy
+  SPC_PROXY: ""
 ```

docs/en/guide/troubleshooting.md

@@ -19,6 +19,30 @@ To fix this, [create](https://github.com/settings/tokens) a personal access toke
 If you confirm that the address is indeed inaccessible,
 you can submit an Issue or PR to update the url or download type.
 
+## Download Through a Proxy
+
+If your network requires a proxy to reach the download sources, you can either set `ALL_PROXY`
+directly, or use `SPC_PROXY`:
+
+```shell
+# curl and git already honour ALL_PROXY by themselves
+ALL_PROXY="socks5h://127.0.0.1:1080" spc download --for-extensions="curl,openssl"
+
+# SPC_PROXY additionally covers the Go toolchain (FrankenPHP), which ignores ALL_PROXY
+SPC_PROXY="socks5h://127.0.0.1:1080" spc build:php "curl" --build-cli
+```
+
+`socks5h` resolves hostnames on the proxy side, which is usually what you want.
+StaticPHP passes the value to curl and git as `ALL_PROXY`, and to Go as `HTTP_PROXY`/`HTTPS_PROXY`
+(rewriting `socks5h://` to `socks5://`, the only SOCKS form Go understands).
+
+To make the setting permanent, add it to `config/env.ini` or `config/env.custom.ini`:
+
+```ini
+[global]
+SPC_PROXY="socks5h://127.0.0.1:1080"
+```
+
 ## Doctor Can't Fix Something
 
 In most cases, the doctor module can automatically repair and install missing system environments,

docs/zh/guide/troubleshooting.md

@@ -14,6 +14,29 @@
 
 如果确认地址确实无法正常访问，可以提交 Issue 或 PR 更新地址或下载类型。
 
+## 通过代理下载
+
+如果你的网络需要通过代理才能访问下载源，可以直接设置 `ALL_PROXY`，也可以使用 `SPC_PROXY`：
+
+```shell
+# curl 和 git 本来就会读取 ALL_PROXY
+ALL_PROXY="socks5h://127.0.0.1:1080" spc download --for-extensions="curl,openssl"
+
+# SPC_PROXY 额外覆盖 Go 工具链（FrankenPHP），因为 Go 会忽略 ALL_PROXY
+SPC_PROXY="socks5h://127.0.0.1:1080" spc build:php "curl" --build-cli
+```
+
+`socks5h` 表示由代理端解析域名，通常这是你需要的模式。
+StaticPHP 会把它作为 `ALL_PROXY` 传给 curl 和 git，并作为 `HTTP_PROXY`/`HTTPS_PROXY` 传给 Go
+（把 `socks5h://` 改写为 `socks5://`，这是 Go 唯一支持的 SOCKS 形式）。
+
+如需长期生效，可将其写入 `config/env.ini` 或 `config/env.custom.ini`：
+
+```ini
+[global]
+SPC_PROXY="socks5h://127.0.0.1:1080"
+```
+
 ## Doctor 无法修复某些问题
 
 在绝大部分情况下，doctor 模块都可以对缺失的系统环境进行自动修复和安装，但也存在特殊的环境无法正常使用自动修复功能。

src/StaticPHP/Util/GlobalEnvManager.php

@@ -72,6 +72,8 @@ public static function init(): void
             }
         }
 
+        self::applyProxy();
+
         ToolchainManager::initToolchain();
 
         // apply second time
@@ -143,6 +145,32 @@ public static function afterInit(): void
         }
     }
 
+    /**
+     * Apply the proxy settings from the environment variable `SPC_PROXY` to the appropriate environment variables for different tools (curl, git, Go toolchain).
+     */
+    private static function applyProxy(): void
+    {
+        $proxy = trim(getenv('SPC_PROXY') ?: '');
+        if ($proxy === '') {
+            return;
+        }
+
+        foreach (['ALL_PROXY', 'all_proxy'] as $name) {
+            self::putenv("{$name}={$proxy}");
+        }
+
+        // apply go proxy
+        $goproxy = preg_replace('#^socks5h://#i', 'socks5://', $proxy);
+        foreach (['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy'] as $name) {
+            self::putenv("{$name}={$goproxy}");
+        }
+
+        spc_add_log_filter($proxy);
+        spc_add_log_filter($goproxy);
+
+        logger()->debug('Detected SPC_PROXY, applied to ALL_PROXY, all_proxy, HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy');
+    }
+
     private static function readIniFile(): array
     {
         // Init env.ini file, read order: