linghengqian · Oct 20, 2026 · Oct 20, 2026
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -40,6 +40,7 @@ jobs:
           go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_use_test.lua
           go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/parse_legacy_file_test.lua
           go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/loongnix_test.lua
+          go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/github_mirror_test.lua
       - name: Test macOS Java home normalization
         run: go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/post_install_test.lua
   macos-layout:

diff --git a/README.md b/README.md
@@ -86,6 +86,12 @@ Zulu, Liberica, Liberica NIK and Corretto (Java 8 only) have builds with JavaFX
 
 vfox reads the `java=` line of SDKMAN's `.sdkmanrc` through this plugin and selects a JDK that is already installed. See [docs/sdkmanrc.md](docs/sdkmanrc.md) for details.
 
+## GitHub mirror
+
+Most distributions download from GitHub. If that is slow where you are, `export VFOX_JAVA_GITHUB_MIRROR=https://gh-proxy.org/` sends these downloads through a mirror. See [docs/mirror.md](docs/mirror.md) for details.
+
+Unreleased: release 0.6.2 has no mirror setting.
+
 ## Querying Foojay
 
 To see which JDKs exist for your platform, ask Foojay yourself. [docs/foojay.md](docs/foojay.md) has the Swagger UI and the commands.

diff --git a/README_CN.md b/README_CN.md
@@ -86,6 +86,12 @@ Zulu、Liberica、Liberica NIK 和 Corretto（只有 Java 8）提供内置 JavaF
 
 vfox 通过这个插件读取 SDKMAN 的 `.sdkmanrc` 里的 `java=` 一行，并选中已经安装的 JDK。详见 [docs/zh-CN/sdkmanrc.md](docs/zh-CN/sdkmanrc.md)。
 
+## GitHub 镜像
+
+大多数发行版从 GitHub 下载。如果你那里下载很慢，执行 `export VFOX_JAVA_GITHUB_MIRROR=https://gh-proxy.org/`，这些下载就会经过镜像。详见 [docs/zh-CN/mirror.md](docs/zh-CN/mirror.md)。
+
+未发布：0.6.2 没有镜像设置。
+
 ## 查询 Foojay
 
 想知道你的平台上有哪些 JDK，可以自己去问 Foojay。[docs/zh-CN/foojay.md](docs/zh-CN/foojay.md) 里有 Swagger UI 和查询命令。

diff --git a/docs/changes.md b/docs/changes.md
@@ -14,6 +14,7 @@ What changed in each release, as a user notices it. GitHub's release pages list
 - A 25.0 name that release 0.6.2 installed after Foojay's change can hold a feature release: `25.0.4.1-graal` is GraalVM 25.4.4.1.1, `25.0.4-graal` is 25.2.4 and `25.0.3-graal` is 25.1.3, and the same goes for these names with `-graalce`. vfox does not install a name it already has, so if the GraalVM version that `java -version` prints differs from the name, `vfox uninstall` it and install it again. `25.0.4.1-graalce`, `25.0.4-graalce` and `25.0.3-graalce` no longer install at all, as GraalVM Community's 25.0 line ends with `25.0.2`.
 - A bare major such as `java@21-tem` asks Foojay what `vfox search` asks and installs the newest release of the major that the search lists. Release 0.6.2 has Foojay pick it (`latest=available`), and as Foojay caches each question on its own, for half an hour after a release that can install a build `vfox search` does not list yet. Dragonwell 11 on Windows x64 and on Linux x64 with musl now installs the Extended build of 11.0.32, as `java@11.0.32-albba` does, where 0.6.2 installs the Standard one for `java@11-albba` ([#113](https://github.com/version-fox/vfox-java/issues/113)).
 - `vfox use java@25-graal` and a `.sdkmanrc` holding `java=25-graal` select the newest installed build of Oracle GraalVM's 25.0 line, the build `vfox install java@25-graal` installs. Release 0.6.2 selects the newest installed release of 25, which is a monthly feature release as soon as one is installed: with `25.0.5-graal` and `25.4.4.1.1-graal` installed, `vfox use java@25-graal` selected the second, while `vfox install java@25-graal` reported the first as installed. A feature release is selected by its full version (`java@25.4.4.1.1-graal`), or by the bare major where nothing else of 25 is installed. A `.sdkmanrc` naming a 25.0 release that is not installed, such as `java=25.0.3-graal`, falls back the same way. `java=25.4.4+1-graal`, which names a feature release as SDKMAN does, still takes the newest installed release of 25. GraalVM Community is not affected, as its feature releases are what it still ships ([#110](https://github.com/version-fox/vfox-java/issues/110)).
+- `VFOX_JAVA_GITHUB_MIRROR` sends the downloads from GitHub through a mirror, as in `export VFOX_JAVA_GITHUB_MIRROR=https://gh-proxy.org/`. Foojay links the JDKs of most distributions to GitHub Releases (Temurin, Liberica and GraalVM Community among them). github.com is slow or out of reach in some regions. The value is a prefix that goes in front of the GitHub URL. Downloads from other hosts do not change. See [mirror.md](mirror.md).
 
 ## 0.6.2 (2026-10-18)
 

diff --git a/docs/development.md b/docs/development.md
@@ -14,6 +14,7 @@ hooks/pre_use.lua               vfox use: map what was typed to an installed nam
 hooks/parse_legacy_file.lua     .sdkmanrc
 lib/distribution_version.lua    distribution names, parsing of specs, GraalVM feature releases
 lib/foojay.lua                  the Foojay request, and fixes to what it answers
+lib/github_mirror.lua           the mirror of the downloads from GitHub
 lib/installed_version.lua       matching against installed names
 lib/loongnix.lua                the Loongnix archive
 tests/*_test.lua                offline hook tests
@@ -37,6 +38,7 @@ vfox loads `metadata.lua`, calls a hook when a command needs it, and puts `PLUGI
 A few contracts that cost time to find:
 
 - `PreInstall` returns `url`, `version` and `note`. `version` becomes the name of the install, which is why it carries the build number. The package's checksum is not passed on yet (`TODO: checksum` in `hooks/pre_install.lua`), and vfox prints a warning for that.
+- For a package from Foojay, `url` is its `direct_download_uri`, behind `$VFOX_JAVA_GITHUB_MIRROR` when it is on GitHub (`lib/github_mirror.lua`, [mirror.md](mirror.md)). vfox downloads from `http://` and `https://` addresses and takes anything else for a file on disk. It names the download after the last part of the URL's path and unpacks it by the extension of that name, which a prefix in front of the URL does not change.
 - `PreUse` returns a table or `nil`. For a bare major it returns `nil` so that vfox matches it itself. vfox 1.0.13 and later reject a bare string such as `""`.
 - `ParseLegacyFile` calls `ctx.getInstalledVersions()` with no argument. vfox 1.x binds it as a Go `func() []string` and rejects the extra argument that `ctx:getInstalledVersions()` adds. vfox ignores errors from this hook, so the failure is silent.
 - vfox hands over the installed versions sorted as strings, descending: `21.0.8+9-tem`, `21.0.12+8-tem`, `21.0.1+12-tem`. The first one that starts with a release is not the right one, so `lib/installed_version.lua` compares numbers one by one.
@@ -71,10 +73,11 @@ go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_install_test.lua
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_use_test.lua
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/parse_legacy_file_test.lua
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/loongnix_test.lua
+go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/github_mirror_test.lua
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/post_install_test.lua
 ```
 
-Run them from the repository root. All five load `tests/support.lua`, which stubs `vfox.strings`, and `tests/pre_install_test.lua` and `tests/loongnix_test.lua` stub `http` and `json` themselves. `tests/pre_install_test.lua` keeps Foojay's answers in a table at the top, keyed by `<distribution> [<version>]`, with `windows` or `macos` in front for those systems. Add the answer a new case needs there, and note the day you observed it. Lint, license headers and the container tests are in [e2e.md](e2e.md#local-checks).
+Run them from the repository root. All six load `tests/support.lua`, which stubs `vfox.strings`, and `tests/pre_install_test.lua` and `tests/loongnix_test.lua` stub `http` and `json` themselves. `tests/pre_install_test.lua` keeps Foojay's answers in a table at the top, keyed by `<distribution> [<version>]`, with `windows` or `macos` in front for those systems. Add the answer a new case needs there, and note the day you observed it. Lint, license headers and the container tests are in [e2e.md](e2e.md#local-checks).
 
 To call a single hook against the real Foojay, vfox 1.0.13 and later has `vfox plugin run`. It does not register the plugin, and `--os` and `--arch` answer for another platform:
 

diff --git a/docs/e2e.md b/docs/e2e.md
@@ -81,6 +81,14 @@ JDK, so `java` can only come from what vfox installs:
    (`<version>+99`, e.g. `21.0.8+99-tem`), proving the lookup keeps the
    build number: Foojay reads an unencoded `+` as a space and drops the
    build, and the release's newest build would install instead.
+
+   On the Temurin rows an install through a mirror that does not exist must
+   fail too. With `VFOX_JAVA_GITHUB_MIRROR=https://invalid.example.invalid`
+   the mirror goes in front of Temurin's GitHub URL, so `vfox install` fails on
+   the download, and its error must name the URL it asked for: the mirror, a
+   slash and the GitHub URL. Before the plugin read the variable, it downloaded
+   the JDK from github.com and the install succeeded. Nothing is downloaded,
+   and no mirror that works is run.
 3. On the GraalVM Community rows, Oracle GraalVM's bare major `25-graal`
    installs the newest build of its 25.0 line (`25.0.5-graal` on
    2026-10-20), the line Oracle's own `25/latest` download follows, not one
@@ -204,13 +212,13 @@ JDK, so `java` can only come from what vfox installs:
 The default matrix runs every distribution against both vfox channels
 (`latest`, `main`):
 
-| Distribution | Release | Covers                                                                                         | amd64 | arm64 |
-| ------------ | ------- | ---------------------------------------------------------------------------------------------- | ----- | ----- |
-| `open`       | 25.0.2  | the default distribution, versions without a suffix                                            | ✓     |       |
-| `tem`        | 21.0.8  | the common path (tar.gz on Linux, zip on Windows); the name and number checks of items 4 and 6 | ✓     | ✓     |
-| `librca-fx`  | 25.0.4  | JavaFX bundled builds (`-fx`)                                                                  | ✓     | ✓     |
-| `jb`         | 21.0.5  | the tar.gz path on Windows, which has no zip for it                                            | ✓     | ✓     |
-| `graalce`    | 25.0.2  | a `GRAALVM_HOME` set beforehand keeps its value; Oracle GraalVM's `25-graal`                   | ✓     |       |
+| Distribution | Release | Covers                                                                                                    | amd64 | arm64 |
+| ------------ | ------- | --------------------------------------------------------------------------------------------------------- | ----- | ----- |
+| `open`       | 25.0.2  | the default distribution, versions without a suffix                                                       | ✓     |       |
+| `tem`        | 21.0.8  | the common path (tar.gz on Linux, zip on Windows); the mirror, name and number checks of items 2, 4 and 6 | ✓     | ✓     |
+| `librca-fx`  | 25.0.4  | JavaFX bundled builds (`-fx`)                                                                             | ✓     | ✓     |
+| `jb`         | 21.0.5  | the tar.gz path on Windows, which has no zip for it                                                       | ✓     | ✓     |
+| `graalce`    | 25.0.2  | a `GRAALVM_HOME` set beforehand keeps its value; Oracle GraalVM's `25-graal`                              | ✓     |       |
 
 Every pinned release is published through Foojay for each platform its row
 runs on. OpenJDK and GraalVM Community ship no `windows-aarch64` build, so
@@ -388,6 +396,7 @@ go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_install_test.lua
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_use_test.lua
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/parse_legacy_file_test.lua
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/loongnix_test.lua
+go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/github_mirror_test.lua
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/post_install_test.lua
 ```
 

diff --git a/docs/foojay.md b/docs/foojay.md
@@ -35,7 +35,7 @@ For a bare major such as `21` the answer lists every release, and the plugin tak
 
 A bare major asks what searching asks so that installing sees the builds `vfox search` lists. Foojay's answers are cached per question, and two questions can get answers of different ages: half an hour after Oracle GraalVM 25.0.5 reached Foojay on 2026-10-20, GitHub's runners got it from a lookup with `distribution_version=25` but not from a search, and `vfox install java@25-graal` took a build that `vfox search java graal` did not list ([#113](https://github.com/version-fox/vfox-java/issues/113)).
 
-The answer is a list of packages. The plugin names a release after `java_version` (Mandrel and Liberica NIK after `distribution_version`, Oracle GraalVM and GraalVM Community after GraalVM's own version), adds `-fx` where `javafx_bundled` is true, marks it LTS where `term_of_support` is `lts`, and prefers a `zip` over a `tar.gz` of the same version on Windows. It leaves out the JREs, installer bundles and RHEL 6 builds that Foojay lists among OJDKBuild's Windows JDKs, and the JDK 11 builds of Gluon GraalVM's 22.x releases, see [distributions.md](distributions.md). For the install it then fetches the package's `links.pkg_info_uri` and downloads its `direct_download_uri`, which is a vendor's own server (GitHub Releases for Temurin). That record also holds a `checksum`. The plugin does not pass it on, so vfox prints `WARNING: Checksum is not provided, skip verify...` and does not verify the download.
+The answer is a list of packages. The plugin names a release after `java_version` (Mandrel and Liberica NIK after `distribution_version`, Oracle GraalVM and GraalVM Community after GraalVM's own version), adds `-fx` where `javafx_bundled` is true, marks it LTS where `term_of_support` is `lts`, and prefers a `zip` over a `tar.gz` of the same version on Windows. It leaves out the JREs, installer bundles and RHEL 6 builds that Foojay lists among OJDKBuild's Windows JDKs, and the JDK 11 builds of Gluon GraalVM's 22.x releases, see [distributions.md](distributions.md). For the install it then fetches the package's `links.pkg_info_uri` and downloads its `direct_download_uri`, which is a vendor's own server (GitHub Releases for Temurin). That record also holds a `checksum`. The plugin does not pass it on, so vfox prints `WARNING: Checksum is not provided, skip verify...` and does not verify the download. Unreleased: a download from GitHub can go through a mirror, see [mirror.md](mirror.md).
 
 `vfox search` differs from the raw list in a few ways. It lists a name once where Foojay has two records for it, and it leaves the LTS note off GraalVM's feature releases (see [distributions.md](distributions.md#behavior-of-oracle-graalvm-and-graalvm-community)). It only lists GA releases.
 

diff --git a/docs/mirror.md b/docs/mirror.md
@@ -0,0 +1,70 @@
+# GitHub mirror
+
+[中文](zh-CN/mirror.md) | [English](mirror.md)
+
+Unreleased: release 0.6.2 has no mirror setting.
+
+Foojay links the JDKs of most distributions to GitHub Releases, so `vfox install java@21-tem` downloads from `github.com`. If github.com is slow or unreachable where you are, set `VFOX_JAVA_GITHUB_MIRROR` and the plugin sends these downloads through a GitHub mirror.
+
+The value is a URL prefix. The plugin puts it in front of the GitHub URL, and adds a `/` if the value does not end in one. For Temurin 21.0.8 on Linux x64:
+
+| `VFOX_JAVA_GITHUB_MIRROR` | vfox downloads |
+| --- | --- |
+| not set | `https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.8%2B9/OpenJDK21U-jdk_x64_linux_hotspot_21.0.8_9.tar.gz` |
+| `https://gh-proxy.org/` | `https://gh-proxy.org/https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.8%2B9/OpenJDK21U-jdk_x64_linux_hotspot_21.0.8_9.tar.gz` |
+
+[gh-proxy](https://gh-proxy.org/) takes URLs in this form, and so does any service that takes the GitHub URL after its own address. The plugin does not run any of them and cannot vouch for them. The value must start with `http://` or `https://`. vfox takes any other address for a file on disk, so a download from GitHub stops with `VFOX_JAVA_GITHUB_MIRROR must start with http:// or https://` instead.
+
+## Set it
+
+In bash or zsh, for the current shell:
+
+```bash
+export VFOX_JAVA_GITHUB_MIRROR=https://gh-proxy.org/
+```
+
+Put the same line in `~/.bashrc` or `~/.zshrc` to keep it. In PowerShell:
+
+```powershell
+$env:VFOX_JAVA_GITHUB_MIRROR = "https://gh-proxy.org/"
+```
+
+To set it for every terminal opened afterwards:
+
+```powershell
+[Environment]::SetEnvironmentVariable('VFOX_JAVA_GITHUB_MIRROR', 'https://gh-proxy.org/', 'User')
+```
+
+Then install as usual, `vfox install java@21-tem`. To go back to github.com, unset the variable.
+
+## What goes through the mirror
+
+Only downloads from `https://github.com/`. A JDK on any other host downloads from there as before, and the requests to Foojay do not change.
+
+Where Foojay links each distribution (2026-10-21):
+
+| Short names | Download from |
+| --- | --- |
+| `tem`, `librca`, `sem`, `semcrt`, `sapmchn`, `kona`, `albba`, `mandrel`, `trava`, `adpt`, `adptj9`, `eliya`, `ojdkbld`, `gln`, `grl8`, `grl11`, `grl16`, `grl17`, `grl19` | GitHub |
+| `graalce` | GitHub, except the monthly feature releases that `java@25-graalce` installs, which come from Oracle's GraalVM Download Service. `java@25.4.4.1-graalce` is the same file from GitHub |
+| `nik` | GitHub for the newer releases, BellSoft's server for the older ones |
+| `open` | jdk.java.net, except JDK 8 and most 11.x builds, which come from GitHub |
+| `zulu`, `amzn`, `ms`, `oracle`, `graal`, `jb`, `bsg`, `opnlgc`, `rdht` | the vendor's server or a CDN, not GitHub |
+
+Loongnix (`lnxabi1`, `lnxabi2`) downloads from ftp.loongnix.cn and is not mirrored.
+
+To see where one release downloads from, ask Foojay for its package and read `direct_download_uri`. It is mirrored if it starts with `https://github.com/`. [foojay.md](foojay.md) has the queries for other platforms.
+
+```bash
+curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&version=21.0.8&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \
+  | jq -r '.result[0].links.pkg_info_uri' | xargs curl -s | jq -r '.result[0].direct_download_uri'
+```
+
+```
+https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.8%2B9/OpenJDK21U-jdk_x64_linux_hotspot_21.0.8_9.tar.gz
+```
+
+## Notes
+
+- The plugin gives vfox no checksum, so vfox does not verify the download (`WARNING: Checksum is not provided, skip verify...`, see [foojay.md](foojay.md#what-the-plugin-asks)). Through a mirror, the archive is whatever the mirror serves. Use one you trust.
+- The variable only changes where `vfox install` downloads a JDK from. `vfox add java` does not use it. For a proxy that covers all of vfox, see [Network](troubleshooting.md#network).