diff --git a/README.md b/README.md index eb8e86e..9513a2f 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,6 @@ node -v `vfox search nodejs` lists every release, with the npm that comes with it and a mark on the ones of an LTS line. In an interactive terminal it lets you pick one. -Behavior that only exists on `main` and not in the latest release is marked -"Unreleased" in the pages below. [docs/changes.md](docs/changes.md) lists it, and -[docs/source-build.md](docs/source-build.md) gets you `main`. - ### Example: Ubuntu 26.04 ```bash @@ -70,9 +66,7 @@ The Node.js musl builds need `libstdc++`, and the ones of 26.8.0 and later need `libatomic` as well. A stock Alpine image has neither, and the plugin does not install system libraries. The install stops with a message that names the missing package and the command that installs it (`apk add libatomic`; OpenWrt -calls `libstdc++` the `libstdcpp` package). Unreleased: release 0.5.2 checks for -`libstdc++` only, and a missing `libatomic` shows when `node` fails with `Error -loading shared library libatomic.so.1`. musl builds exist for x64 and arm64 +calls `libstdc++` the `libstdcpp` package). musl builds exist for x64 and arm64 only. musl details (OpenWrt, tarball matrix, mirror fallback, which releases have a build): see [docs/musl.md](docs/musl.md). @@ -91,10 +85,9 @@ Node.js publishes packages for Linux (x64, arm64, ppc64le, s390x), macOS (x64 an arm64) and Windows (x64, arm64, and x86 up to 22.x). Not every release has every one of them: Windows on ARM starts at 19.9.0, Linux arm64 at 4.0.0, Apple silicon at 16.0.0 (older releases install the x64 package under Rosetta 2). 32-bit ARM -Linux has packages up to 23.11.1. Unreleased: release 0.5.2 cannot install them. -riscv64 and loong64 are not supported. `vfox search` lists every release -whatever your platform is. See [docs/platforms.md](docs/platforms.md) for the -table. +Linux has packages up to 23.11.1. riscv64 and loong64 are not supported. +`vfox search` lists every release whatever your platform is. See +[docs/platforms.md](docs/platforms.md) for the table. ## npm and global packages diff --git a/README_CN.md b/README_CN.md index 9f53574..26e7099 100644 --- a/README_CN.md +++ b/README_CN.md @@ -32,8 +32,6 @@ node -v `vfox search nodejs` 会列出每个版本及其自带的 npm,属于 LTS 版本线的版本带有标记。在交互式终端里可以从中选一个。 -只存在于 `main`、还没进入最新发布版的行为,在下面各页里标有“未发布”。[docs/zh-CN/changes.md](docs/zh-CN/changes.md) 里列出了这些行为,想直接用上 `main`,见 [docs/zh-CN/source-build.md](docs/zh-CN/source-build.md)。 - ### 示例:Ubuntu 26.04 ```bash @@ -54,7 +52,7 @@ vfox install nodejs@24 vfox use --global nodejs@24 ``` -Node.js 的 musl 构建需要 `libstdc++`,26.8.0 及以后的构建还需要 `libatomic`。原版 Alpine 镜像两者都没有,而插件不会安装系统库。安装会中止,并给出一条提示,写明缺少哪个包以及安装它的命令(`apk add libatomic`;OpenWrt 把 `libstdc++` 称为 `libstdcpp` 包)。未发布:0.5.2 只检查 `libstdc++`,缺少 `libatomic` 时,要到 `node` 运行失败、报 `Error loading shared library libatomic.so.1` 才能发现。musl 构建只提供 x64 和 arm64。musl 的详细情况(OpenWrt、压缩包对照表、镜像回退、哪些版本有构建)见 [docs/zh-CN/musl.md](docs/zh-CN/musl.md)。 +Node.js 的 musl 构建需要 `libstdc++`,26.8.0 及以后的构建还需要 `libatomic`。原版 Alpine 镜像两者都没有,而插件不会安装系统库。安装会中止,并给出一条提示,写明缺少哪个包以及安装它的命令(`apk add libatomic`;OpenWrt 把 `libstdc++` 称为 `libstdcpp` 包)。musl 构建只提供 x64 和 arm64。musl 的详细情况(OpenWrt、压缩包对照表、镜像回退、哪些版本有构建)见 [docs/zh-CN/musl.md](docs/zh-CN/musl.md)。 ## 版本与命名 @@ -62,7 +60,7 @@ Node.js 的 musl 构建需要 `libstdc++`,26.8.0 及以后的构建还需要 ` ## 平台 -Node.js 为 Linux(x64、arm64、ppc64le、s390x)、macOS(x64 和 arm64)和 Windows(x64、arm64,以及到 22.x 为止的 x86)发布包。并不是每个版本都有上面所有的包:Windows on ARM 从 19.9.0 起,Linux arm64 从 4.0.0 起,Apple silicon 从 16.0.0 起(更早的版本在 Rosetta 2 下安装 x64 的包)。32 位 ARM Linux 到 23.11.1 为止有包。未发布:0.5.2 无法安装它们。不支持 riscv64 和 loong64。不论你的平台是什么,`vfox search` 都会列出所有版本。表格见 [docs/zh-CN/platforms.md](docs/zh-CN/platforms.md)。 +Node.js 为 Linux(x64、arm64、ppc64le、s390x)、macOS(x64 和 arm64)和 Windows(x64、arm64,以及到 22.x 为止的 x86)发布包。并不是每个版本都有上面所有的包:Windows on ARM 从 19.9.0 起,Linux arm64 从 4.0.0 起,Apple silicon 从 16.0.0 起(更早的版本在 Rosetta 2 下安装 x64 的包)。32 位 ARM Linux 到 23.11.1 为止有包。不支持 riscv64 和 loong64。不论你的平台是什么,`vfox search` 都会列出所有版本。表格见 [docs/zh-CN/platforms.md](docs/zh-CN/platforms.md)。 ## npm 与全局包 diff --git a/docs/changes.md b/docs/changes.md index 66a12dd..7f16b9a 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -4,11 +4,9 @@ What changed in each release, as a user notices it. GitHub's [release pages](https://github.com/version-fox/vfox-nodejs/releases) list the -pull requests. The newest release at the time of writing is 0.5.2, and `main` is -ahead of it by everything under "Unreleased". -[source-build.md](source-build.md) gets you those changes now. +pull requests. -## Unreleased +## 0.5.3 (2026-10-20) - 32-bit ARM Linux installs the `linux-armv7l` package, which Node.js published up to 23.11.1: `vfox install nodejs@20` works there. vfox's `armv7` build @@ -16,7 +14,8 @@ ahead of it by everything under "Unreleased". every install on 32-bit ARM ends with `Node.js package node-v20.19.5-linux-arm.tar.gz is not listed in ...`. From 24 on there is no package, and the ARMv6 one is never chosen. See - [platforms.md](platforms.md#not-supported). + [platforms.md](platforms.md#not-supported) + ([#41](https://github.com/version-fox/vfox-nodejs/pull/41)). - On musl the install stops when the unpacked `node` cannot run for lack of a library. After the unpack the plugin runs `node --version` once, and the dynamic loader names what is missing. The musl packages of 26.8.0 and later need @@ -27,7 +26,8 @@ ahead of it by everything under "Unreleased". install succeeds and `node` fails with `Error loading shared library libatomic.so.1`. The message about `libstdc++` names its command too, where release 0.5.2 says `It is normally installed automatically`. See - [musl.md](musl.md#requirements). + [musl.md](musl.md#requirements) + ([#41](https://github.com/version-fox/vfox-nodejs/pull/41)). - `.nvmrc` and `.node-version` name a release by its numbers under `legacyVersionFile.strategy` `latest_installed` and `latest_available`. With 22.9.0 and 22.23.3 installed, `22` selects 22.23.3, where release 0.5.2 selects @@ -36,14 +36,28 @@ ahead of it by everything under "Unreleased". nothing for `22.x`. Only a leading `v` is dropped, so `lts/` works for a codename with a `v` in it. Text that is no release number (`node`, `(`, `22[`) is left alone, where release 0.5.2 fails with `unfinished capture at - EOS` and vfox hides the error. See [nvmrc.md](nvmrc.md#how-a-prefix-is-matched). + EOS` and vfox hides the error. See + [nvmrc.md](nvmrc.md#how-a-prefix-is-matched) + ([#41](https://github.com/version-fox/vfox-nodejs/pull/41)). - A failed request for `SHASUMS256.txt` says why: `get checksum failed: HTTP 404 from https://nodejs.org/dist/v24.99.0/SHASUMS256.txt`, or the network error, such as `x509: certificate signed by unknown authority`. Release 0.5.2 prints `get checksum failed` and nothing else. See - [troubleshooting.md](troubleshooting.md#messages-from-the-plugin). -- `VFOX_NODEJS_MIRROR` may end in several slashes. Release 0.5.2 strips one. -- The documentation has a Chinese version, see [README_CN.md](../README_CN.md). + [troubleshooting.md](troubleshooting.md#messages-from-the-plugin) + ([#41](https://github.com/version-fox/vfox-nodejs/pull/41)). +- `VFOX_NODEJS_MIRROR` may end in several slashes. Release 0.5.2 strips one + ([#41](https://github.com/version-fox/vfox-nodejs/pull/41)). +- The documentation has a page for versions and names, platforms, `.nvmrc` and + `.node-version`, npm, troubleshooting, development and the changes, and a + Chinese version, see [README_CN.md](../README_CN.md) + ([#41](https://github.com/version-fox/vfox-nodejs/pull/41)). +- The Windows e2e suite runs from the host through `tests/e2e/windows/run.ps1`, + which replaces the Docker Compose runner. The script fetches PowerShell, + PortableGit and Go into a cache that every combo container mounts read-only at + `C:\tools`, so no image runs the PowerShell MSI and the Git installer any + more, and CI starts all the Windows combos at once. See + [e2e.md](e2e.md#windows-11) + ([#40](https://github.com/version-fox/vfox-nodejs/pull/40)). ## 0.5.2 (2026-10-17) diff --git a/docs/development.md b/docs/development.md index 6f39ffb..96a749f 100644 --- a/docs/development.md +++ b/docs/development.md @@ -135,10 +135,6 @@ fallback when that finds nothing or the request fails. `vfox` then selects the answer if it is installed. User-facing rules and examples are in [nvmrc.md](nvmrc.md) and [lts.md](lts.md). -Unreleased: release 0.5.2 matches the query as a Lua pattern against the start of -each release, in the order vfox lists them, and takes the first one that matches. -See [nvmrc.md](nvmrc.md#how-a-prefix-is-matched). - ## When Node.js promotes a line to LTS Each October an even-numbered line gets a codename, see @@ -253,12 +249,18 @@ Afterwards `plugins/nodejs.json` in [vfox-plugins](https://github.com/version-fox/vfox-plugins) shows the version that `vfox add nodejs` serves. -The documentation marks what is newer than the last release with "Unreleased" -("未发布" in Chinese). After a release, move those entries in -[changes.md](changes.md) under the new version and take the remarks out, in both -languages: `grep -rn -i -e unreleased -e 未发布 docs README*`. Also search for -the number of the previous release: a few sentences compare against it without -saying "Unreleased". +While `main` is ahead of the last release, the documentation marks what is newer +with "Unreleased" ("未发布" in Chinese): the entries sit under an "Unreleased" +heading at the top of [changes.md](changes.md), a page that describes the new +behavior adds a remark that starts with "Unreleased: release X.Y.Z" and tells +what the last release does, and the README has a paragraph that explains the +mark and points at [changes.md](changes.md) and +[source-build.md](source-build.md). After a release, move the entries in +[changes.md](changes.md) under the new version, with the pull request of each, +and take the remarks and the README paragraph out, in both languages: +`grep -rn -i -e unreleased -e 未发布 docs README*`. Also search for the number of +the previous release: a few sentences compare against it without saying +"Unreleased". ## Writing the docs diff --git a/docs/mirror.md b/docs/mirror.md index 24958e6..01d3750 100644 --- a/docs/mirror.md +++ b/docs/mirror.md @@ -93,9 +93,8 @@ VFOX_NODEJS_MIRROR=https://example.invalid/dist vfox search nodejs ``` On the same mirror `vfox install nodejs@24.21.0` fails with `get checksum failed: -Get "https://example.invalid/dist/v24.21.0/SHASUMS256.txt": ...` (Unreleased: -release 0.5.2 leaves out what follows `failed`). A mirror that serves no -`index.json` at that address fails the search with +Get "https://example.invalid/dist/v24.21.0/SHASUMS256.txt": ...`. A mirror that +serves no `index.json` at that address fails the search with `Failed to fetch Node.js versions: HTTP 404`, see [troubleshooting.md](troubleshooting.md#network). vfox caches the search for 12 hours, so after a change run `vfox config cache.availableHookDuration 0` or diff --git a/docs/musl.md b/docs/musl.md index 2c26ca9..8bb5ad9 100644 --- a/docs/musl.md +++ b/docs/musl.md @@ -58,10 +58,11 @@ gets the message without a command. A symbol that the libraries lack, which the loader reports as `Error relocating ...: symbol not found`, ends in `Node.js (musl build) cannot run on this system: Error relocating ...`. -Unreleased: release 0.5.2 looks for `libstdc++` only, and its message says `It -is normally installed automatically; install it and reinstall.` instead of -naming the command. It does not look for `libatomic`: the install succeeds, and -`node` then fails. +The loader prints this for a missing `libatomic`, and the hook reads the name of +the library from it. Before 0.5.3 the plugin did not run `node` after the +unpack, so a release that an earlier version of the plugin installed fails with +these lines when you run it. Installing the library is all it needs, there is +nothing to reinstall: ```text Error loading shared library libatomic.so.1: No such file or directory (needed by /root/.vfox/cache/nodejs/v-26.12.0/nodejs-26.12.0/bin/node) diff --git a/docs/nvmrc.md b/docs/nvmrc.md index d90d949..b1b63b3 100644 --- a/docs/nvmrc.md +++ b/docs/nvmrc.md @@ -74,9 +74,6 @@ Before it looks at the text, the plugin removes all whitespace, drops a leading the newest release with that codename. A release number may end in `x`, `X` or `*` for the parts it leaves open: `22.x`, `22.x.x` and `22.*` all mean 22. -Unreleased: release 0.5.2 drops every `v` of the file, so a codename with a `v` -in it does not match, and it does not know `22.x`. - The results on 2026-10-21 with 20.20.2, 22.23.3, 24.21.0, 25.9.0 and 26.12.0 installed, when 24.22.0 is the newest 24.x and 22.23.3 the newest 22.x: @@ -126,13 +123,6 @@ starts with it: 22.3.0 and 22.23.3 installed, `22` selects 22.23.3 and `22.3` selects 22.3.0. `vfox use nodejs@22` compares numbers as well. -Unreleased: release 0.5.2 compares text, and takes the first installed release -that starts with it. `22.2` also matches `22.23.3`, and with 22.9.0 and 22.23.3 -installed `22` under `latest_installed` selects 22.9.0 (checked with 22.9.0, -22.3.0 and 22.23.3 installed). Keep one release per line installed, or write the -full release number, to get the same answer there. The text is also used as a -Lua pattern, so `22.*` happens to work and `22.x` does not. - ## Not finding it If the release does not switch: diff --git a/docs/platforms.md b/docs/platforms.md index 9485b61..f05bd27 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -39,7 +39,7 @@ in [development.md](development.md#refreshing-the-platform-table). | Linux ppc64le | `linux-ppc64le.tar.gz` | 4.3.2 and later, except 5.0.0 to 5.6.0 | | Linux s390x | `linux-s390x.tar.gz` | 6.6.0 and later | | Linux 386 | `linux-x86.tar.gz` | 0.8.6 to 9.11.2, except 0.9.0, 0.11.4 and 0.11.6 | -| Linux arm | `linux-armv7l.tar.gz` | 4.0.0 to 23.11.1, except 8.1.1. Unreleased: release 0.5.2 asks for `linux-arm`, which Node.js never published, so every install fails | +| Linux arm | `linux-armv7l.tar.gz` | 4.0.0 to 23.11.1, except 8.1.1 | | Linux amd64, musl | `linux-x64-musl.tar.gz` | see [musl.md](musl.md#which-releases-have-a-musl-build) | | Linux arm64, musl | `linux-arm64-musl.tar.gz` | see [musl.md](musl.md#which-releases-have-a-musl-build) | | macOS amd64 | `darwin-x64.tar.gz` | 0.8.6 and later, except 0.9.0, 0.11.4 and 0.11.6 | @@ -65,9 +65,7 @@ above, see [troubleshooting.md](troubleshooting.md#messages-from-the-plugin). Node.js published up to 23.11.1. From 24 on there is none, and the install ends with `Node.js package node-v26.12.0-linux-armv7l.tar.gz is not listed in ...`. The ARMv6 package (`linux-armv6l`, 4.0.0 to 11.15.0 on nodejs.org) is - never chosen. Unreleased: release 0.5.2 asks for `linux-arm`, which Node.js - never published, so every install on 32-bit ARM fails with `Node.js package - node-v20.19.5-linux-arm.tar.gz is not listed in ...`. + never chosen. - **Linux riscv64 and loong64.** nodejs.org has no packages for them. The [Unofficial Builds](https://github.com/nodejs/unofficial-builds) site has riscv64 (17.7.1 to 26.0.0) and loong64 (18.18.0 and later), but the plugin diff --git a/docs/source-build.md b/docs/source-build.md index d7bf053..ddac550 100644 --- a/docs/source-build.md +++ b/docs/source-build.md @@ -15,7 +15,7 @@ and `lib/` at its top level; that is the plugin package contract (see the [shared workflow documentation](https://github.com/version-fox/plugin-manifest-action)). A released plugin zip URL also works as `--source`, e.g. -`vfox add --source https://github.com/version-fox/vfox-nodejs/releases/download/v0.0.5/vfox-nodejs_0.0.5.zip`. +`vfox add --source https://github.com/version-fox/vfox-nodejs/releases/download/v0.5.3/vfox-nodejs-0.5.3.zip`. Prerequisites on all systems: [vfox](https://github.com/version-fox/vfox) itself plus `git`. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1c719a0..c785ccb 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -27,10 +27,6 @@ by unknown authority`, `... connection refused`, `... EOF`) means the server could not be reached: a mirror that is down, a proxy, a TLS problem. See [Network](#network). -Unreleased: release 0.5.2 prints `get checksum failed` and nothing else, so the -cause is hidden. `vfox search nodejs` asks the same server for the index and -prints the real error. - ### `Node.js package node-v19.8.1-win-arm64.zip is not listed in https://nodejs.org/dist/v19.8.1/SHASUMS256.txt` The release exists, and Node.js published no package for your platform under the @@ -73,16 +69,11 @@ The message names the package, and the command that installs it on Alpine after the unpack and nothing is registered. Install the library and run the install again. See [musl.md](musl.md#requirements). -Unreleased: release 0.5.2 looks for `libstdc++` only, and its message has no -command. A missing `libatomic` shows later, as an error of `node` itself, see -below. - ### `Node.js (musl build) cannot run on this system: Error relocating ...` The unpacked `node` needs a symbol that no library of the system provides. The -install fails after the unpack and nothing is registered. Unreleased: release -0.5.2 does not run `node` after the unpack, and the error shows when you run it. -See [musl.md](musl.md#requirements). +install fails after the unpack and nothing is registered. See +[musl.md](musl.md#requirements). ### `checksum error` @@ -142,12 +133,13 @@ These come from `node` after a successful install. - `Error loading shared library libatomic.so.1: No such file or directory`, followed by `Error relocating ...: __atomic_compare_exchange: symbol not found`, on Alpine. The musl packages of 26.8.0 and later need `libatomic`: - `apk add libatomic`. Unreleased: the install itself stops with the message - above, and release 0.5.2 gets this far. See [musl.md](musl.md#requirements). + `apk add libatomic`. Since 0.5.3 the install itself stops with the message + above, so this is a release that an earlier version installed. See + [musl.md](musl.md#requirements). - `Error relocating ... symbol not found` on a musl system, without the - `libatomic` line above. A library is missing or too old. Unreleased: the - install stops with `cannot run on this system`, and release 0.5.2 gets this - far. See [musl.md](musl.md#requirements). + `libatomic` line above. A library is missing or too old. Since 0.5.3 the + install stops with `cannot run on this system` when `node --version` fails + like this. See [musl.md](musl.md#requirements). ## Network @@ -175,8 +167,7 @@ While `proxy.enable` is `false`, the usual `HTTP_PROXY`, `HTTPS_PROXY` and as `proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused`. The usual failures of `vfox search nodejs`. `vfox install` reports the same cause -after `get checksum failed:`. Unreleased: release 0.5.2 leaves it out, and only -the search prints it: +after `get checksum failed:`: | After `Failed to fetch Node.js versions:` | Cause | | --- | --- | diff --git a/docs/versions.md b/docs/versions.md index c8e23b8..75ed5b5 100644 --- a/docs/versions.md +++ b/docs/versions.md @@ -39,10 +39,9 @@ checks it and unpacks it. These are the answers on 2026-10-21: builds, nightlies or four-part numbers. Those end in `version not found for provided version ...`. - A release number that does not exist (`24.99.0`) ends in `get checksum - failed: HTTP 404 from ...`, as nodejs.org has no directory for it - (Unreleased: release 0.5.2 leaves out what follows `failed`). A release that - exists but has no package for your platform ends in `Node.js package ... is - not listed in ...`. See + failed: HTTP 404 from ...`, as nodejs.org has no directory for it. A release + that exists but has no package for your platform ends in `Node.js package ... + is not listed in ...`. See [troubleshooting.md](troubleshooting.md#messages-from-the-plugin) and [platforms.md](platforms.md). - Every download is checked against the SHA-256 sum in the release's diff --git a/docs/zh-CN/changes.md b/docs/zh-CN/changes.md index 823ce4b..5d9a8ab 100644 --- a/docs/zh-CN/changes.md +++ b/docs/zh-CN/changes.md @@ -2,16 +2,17 @@ [中文](changes.md) | [English](../changes.md) -按发布版本列出用户能感受到的变化。GitHub 的 [Release 页面](https://github.com/version-fox/vfox-nodejs/releases)列出了对应的 PR。写这篇文档时最新的发布版是 0.5.2,`main` 比它多出“未发布”下面的所有内容。想现在就用上这些变化,见 [source-build.md](source-build.md)。 +按发布版本列出用户能感受到的变化。GitHub 的 [Release 页面](https://github.com/version-fox/vfox-nodejs/releases)列出了对应的 PR。 -## 未发布 +## 0.5.3(2026-10-20) -- 32 位 ARM 的 Linux 会安装 `linux-armv7l` 包,Node.js 到 23.11.1 为止都发布了这个包:`vfox install nodejs@20` 在那里可以用。vfox 的 `armv7` 构建报告的是 `arm`,而 0.5.2 请求 `linux-arm`,这个包并不存在,所以 32 位 ARM 上的每次安装都以 `Node.js package node-v20.19.5-linux-arm.tar.gz is not listed in ...` 告终。从 24 起没有这个包了,ARMv6 的包也永远不会被选中。见 [platforms.md](platforms.md#不支持的情况)。 -- 在 musl 上,解压出来的 `node` 因缺少库而无法运行时,安装会中止。解压之后,插件会运行一次 `node --version`,由动态加载器指出缺少什么。26.8.0 及以后的 musl 包需要 `libatomic`,原版 Alpine 没有它:安装会以 ``Node.js (musl build) requires the libatomic system package, which was not found on this system. Install it with `apk add libatomic` and reinstall.`` 结束,不会登记任何内容。0.5.2 只检查 `libstdc++`,所以安装能成功,而 `node` 会报 `Error loading shared library libatomic.so.1`。关于 `libstdc++` 的提示同样会给出命令,0.5.2 的提示则是 `It is normally installed automatically`。见 [musl.md](musl.md#依赖的系统库)。 -- 在 `legacyVersionFile.strategy` 为 `latest_installed` 和 `latest_available` 时,`.nvmrc` 和 `.node-version` 按版本号的数字匹配版本。已安装 22.9.0 和 22.23.3 时,`22` 选中 22.23.3,而 0.5.2 选中 22.9.0,因为 vfox 是按文本排列已安装版本的。`22.2` 不再匹配 22.23.3。`22.x`、`22.x.x` 和 `22.*` 都表示 22,0.5.2 对 `22.x` 什么也选不中。只会去掉开头的 `v`,所以代号里带 `v` 的 `lts/` 也能用。不是版本号的文本(`node`、`(`、`22[`)不做处理,0.5.2 对它们会报 `unfinished capture at EOS`,而 vfox 把这个错误藏了起来。见 [nvmrc.md](nvmrc.md#前缀怎样匹配)。 -- 获取 `SHASUMS256.txt` 的请求失败时会说明原因:`get checksum failed: HTTP 404 from https://nodejs.org/dist/v24.99.0/SHASUMS256.txt`,或者网络错误,比如 `x509: certificate signed by unknown authority`。0.5.2 只打印 `get checksum failed`,没有别的内容。见 [troubleshooting.md](troubleshooting.md#插件给出的提示)。 -- `VFOX_NODEJS_MIRROR` 的结尾可以有多个斜杠。0.5.2 只去掉一个。 -- 文档有了中文版,见 [README_CN.md](../../README_CN.md)。 +- 32 位 ARM 的 Linux 会安装 `linux-armv7l` 包,Node.js 到 23.11.1 为止都发布了这个包:`vfox install nodejs@20` 在那里可以用。vfox 的 `armv7` 构建报告的是 `arm`,而 0.5.2 请求 `linux-arm`,这个包并不存在,所以 32 位 ARM 上的每次安装都以 `Node.js package node-v20.19.5-linux-arm.tar.gz is not listed in ...` 告终。从 24 起没有这个包了,ARMv6 的包也永远不会被选中。见 [platforms.md](platforms.md#不支持的情况)([#41](https://github.com/version-fox/vfox-nodejs/pull/41))。 +- 在 musl 上,解压出来的 `node` 因缺少库而无法运行时,安装会中止。解压之后,插件会运行一次 `node --version`,由动态加载器指出缺少什么。26.8.0 及以后的 musl 包需要 `libatomic`,原版 Alpine 没有它:安装会以 ``Node.js (musl build) requires the libatomic system package, which was not found on this system. Install it with `apk add libatomic` and reinstall.`` 结束,不会登记任何内容。0.5.2 只检查 `libstdc++`,所以安装能成功,而 `node` 会报 `Error loading shared library libatomic.so.1`。关于 `libstdc++` 的提示同样会给出命令,0.5.2 的提示则是 `It is normally installed automatically`。见 [musl.md](musl.md#依赖的系统库)([#41](https://github.com/version-fox/vfox-nodejs/pull/41))。 +- 在 `legacyVersionFile.strategy` 为 `latest_installed` 和 `latest_available` 时,`.nvmrc` 和 `.node-version` 按版本号的数字匹配版本。已安装 22.9.0 和 22.23.3 时,`22` 选中 22.23.3,而 0.5.2 选中 22.9.0,因为 vfox 是按文本排列已安装版本的。`22.2` 不再匹配 22.23.3。`22.x`、`22.x.x` 和 `22.*` 都表示 22,0.5.2 对 `22.x` 什么也选不中。只会去掉开头的 `v`,所以代号里带 `v` 的 `lts/` 也能用。不是版本号的文本(`node`、`(`、`22[`)不做处理,0.5.2 对它们会报 `unfinished capture at EOS`,而 vfox 把这个错误藏了起来。见 [nvmrc.md](nvmrc.md#前缀怎样匹配)([#41](https://github.com/version-fox/vfox-nodejs/pull/41))。 +- 获取 `SHASUMS256.txt` 的请求失败时会说明原因:`get checksum failed: HTTP 404 from https://nodejs.org/dist/v24.99.0/SHASUMS256.txt`,或者网络错误,比如 `x509: certificate signed by unknown authority`。0.5.2 只打印 `get checksum failed`,没有别的内容。见 [troubleshooting.md](troubleshooting.md#插件给出的提示)([#41](https://github.com/version-fox/vfox-nodejs/pull/41))。 +- `VFOX_NODEJS_MIRROR` 的结尾可以有多个斜杠。0.5.2 只去掉一个([#41](https://github.com/version-fox/vfox-nodejs/pull/41))。 +- 文档新增了版本与命名、平台、`.nvmrc` 和 `.node-version`、npm、问题排查、开发和变更记录各页,并有了中文版,见 [README_CN.md](../../README_CN.md)([#41](https://github.com/version-fox/vfox-nodejs/pull/41))。 +- Windows 的 E2E 套件改为从宿主通过 `tests/e2e/windows/run.ps1` 运行,取代了 Docker Compose runner。脚本把 PowerShell、PortableGit 和 Go 取到一个缓存里,每个组合容器都以只读方式把它挂载到 `C:\tools`,所以不再有镜像去运行 PowerShell 的 MSI 和 Git 的安装程序,CI 也会同时启动所有 Windows 组合。见 [e2e.md](e2e.md#windows-11)([#40](https://github.com/version-fox/vfox-nodejs/pull/40))。 ## 0.5.2(2026-10-17) diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md index eff2d9d..4039d97 100644 --- a/docs/zh-CN/development.md +++ b/docs/zh-CN/development.md @@ -72,8 +72,6 @@ vfox 加载 `metadata.lua`,命令需要时调用相应的钩子,并向钩子 `vfox` 随后会选中这个结果,前提是它已安装。面向用户的规则和示例见 [nvmrc.md](nvmrc.md) 和 [lts.md](lts.md)。 -未发布:0.5.2 把查询当作 Lua 模式,去匹配每个版本的开头,按 vfox 列出它们的顺序逐个尝试,取第一个匹配的。见 [nvmrc.md](nvmrc.md#前缀怎样匹配)。 - ## Node.js 把一条版本线升为 LTS 时 每年十月,一条偶数版本线会得到代号,见 [lts.md](lts.md#nodejs-升级版本线时)。要让插件认识新的代号: @@ -143,7 +141,7 @@ curl -s https://nodejs.org/dist/index.json | jq -r ' 维护者在默认分支上执行 **Actions → Plugin → Run workflow**,填入不带 `v` 的版本号。共享工作流具体做什么,README 里有说明。发布之后,[vfox-plugins](https://github.com/version-fox/vfox-plugins) 里的 `plugins/nodejs.json` 会显示 `vfox add nodejs` 提供的是哪个版本。 -文档里用“未发布”(英文是“Unreleased”)标记比最近一次发布更新的内容。发布之后,把 [changes.md](changes.md) 里的这些条目移到新版本下面,并去掉这些标注,两种语言都要处理:`grep -rn -i -e unreleased -e 未发布 docs README*`。上一个版本的版本号也要搜一遍:有几句话是拿它做对比的,没有写“未发布”。 +在 `main` 比最近一次发布更靠前的这段时间里,文档用“未发布”(英文是“Unreleased”)标记更新的内容:条目放在 [changes.md](changes.md) 顶部的“未发布”标题下面,描述新行为的页面会加一句以“未发布:X.Y.Z”开头的话,说明最近一次发布的行为,README 里则有一段话,解释这个标记,并指向 [changes.md](changes.md) 和 [source-build.md](source-build.md)。发布之后,把 [changes.md](changes.md) 里的条目移到新版本下面,每条附上对应的 PR,并去掉这些标注和 README 里的那段话,两种语言都要处理:`grep -rn -i -e unreleased -e 未发布 docs README*`。上一个版本的版本号也要搜一遍:有几句话是拿它做对比的,没有写“未发布”。 ## 编写文档 diff --git a/docs/zh-CN/mirror.md b/docs/zh-CN/mirror.md index 641df8c..1e8cf9b 100644 --- a/docs/zh-CN/mirror.md +++ b/docs/zh-CN/mirror.md @@ -76,7 +76,7 @@ VFOX_NODEJS_MIRROR=https://example.invalid/dist vfox search nodejs # Failed to fetch Node.js versions: Get "https://example.invalid/dist/index.json": ... ``` -在同一个镜像上,`vfox install nodejs@24.21.0` 会失败,报 `get checksum failed: Get "https://example.invalid/dist/v24.21.0/SHASUMS256.txt": ...`(未发布:0.5.2 会省略 `failed` 后面的内容)。镜像在那个地址上没有提供 `index.json` 时,搜索会失败,报 `Failed to fetch Node.js versions: HTTP 404`,见 [troubleshooting.md](troubleshooting.md#网络)。vfox 会把搜索结果缓存 12 小时,所以改动之后请执行 `vfox config cache.availableHookDuration 0`,否则在一段时间内看到的还是旧列表。 +在同一个镜像上,`vfox install nodejs@24.21.0` 会失败,报 `get checksum failed: Get "https://example.invalid/dist/v24.21.0/SHASUMS256.txt": ...`。镜像在那个地址上没有提供 `index.json` 时,搜索会失败,报 `Failed to fetch Node.js versions: HTTP 404`,见 [troubleshooting.md](troubleshooting.md#网络)。vfox 会把搜索结果缓存 12 小时,所以改动之后请执行 `vfox config cache.availableHookDuration 0`,否则在一段时间内看到的还是旧列表。 代理是另一项设置,对镜像同样有效,见 [troubleshooting.md](troubleshooting.md#网络)。 diff --git a/docs/zh-CN/musl.md b/docs/zh-CN/musl.md index 5ca5978..97d13e4 100644 --- a/docs/zh-CN/musl.md +++ b/docs/zh-CN/musl.md @@ -40,7 +40,7 @@ failed to install nodejs 在 OpenWrt 上,命令是 `opkg install libstdcpp`。既不是 Alpine 也不是 OpenWrt 的系统,得到的信息里不带命令。库里缺少某个符号时,加载器会报 `Error relocating ...: symbol not found`,安装最终则报 `Node.js (musl build) cannot run on this system: Error relocating ...`。 -未发布:0.5.2 只查找 `libstdc++`,它的报错信息写的是 `It is normally installed automatically; install it and reinstall.`,没有给出命令。它不查找 `libatomic`:安装会成功,之后 `node` 运行失败。 +缺少 `libatomic` 时,动态加载器会打印下面的内容,钩子就是从中读出库的名字。0.5.3 之前,插件在解压之后不会运行 `node`,所以早期版本的插件装好的版本,一运行就会出现这几行。只要装上这个库就行,不需要重新安装: ```text Error loading shared library libatomic.so.1: No such file or directory (needed by /root/.vfox/cache/nodejs/v-26.12.0/nodejs-26.12.0/bin/node) diff --git a/docs/zh-CN/nvmrc.md b/docs/zh-CN/nvmrc.md index 22b88c8..92738d4 100644 --- a/docs/zh-CN/nvmrc.md +++ b/docs/zh-CN/nvmrc.md @@ -49,8 +49,6 @@ vfox config legacyVersionFile.strategy latest_installed 插件在处理文本之前,会先去掉所有空白,去掉开头的 `v`,把其余部分转成小写,并把 `lts-jod` 改成 `lts/jod`。所以 `v22.23.3`、CRLF 换行的文件,以及版本前后的空白,都没有问题。`lts/jod` 这样的名字,会按 [lts.md](lts.md) 里的表变成它所在版本线的大版本(22);`latest_available` 除外,它会向索引查询带有这个代号的最新版本。版本号末尾可以用 `x`、`X` 或 `*` 代替不作限定的部分:`22.x`、`22.x.x` 和 `22.*` 都表示 22。 -未发布:0.5.2 会去掉文件里所有的 `v`,所以带 `v` 的代号匹配不上,也不认识 `22.x`。 - 下面是 2026-10-21 在已安装 20.20.2、22.23.3、24.21.0、25.9.0 和 26.12.0 的情况下得到的结果,此时 24.22.0 是最新的 24.x,22.23.3 是最新的 22.x: | 文件里写 | `specified` | `latest_installed` | `latest_available` | @@ -84,8 +82,6 @@ vfox config legacyVersionFile.strategy latest_installed - `22.2` 匹配 22.2.x,不匹配 22.23.3。 - vfox 交给插件的已安装版本是按文本降序排列的,所以 `22.9.0` 排在 `22.23.3` 前面。插件不按这个顺序取:已安装 22.9.0、22.3.0 和 22.23.3 时,`22` 选中 22.23.3,`22.3` 选中 22.3.0。`vfox use nodejs@22` 同样按数字比较。 -未发布:0.5.2 比较的是文本,取第一个以它开头的已安装版本。`22.2` 也会匹配 `22.23.3`;已安装 22.9.0 和 22.23.3 时,`latest_installed` 下的 `22` 会选中 22.9.0(这是在已安装 22.9.0、22.3.0 和 22.23.3 的情况下验证过的)。想在它上面得到上面的结果,请每条版本线只装一个版本,或者写全版本号。这段文本还会被当作 Lua 模式使用,所以 `22.*` 碰巧能用,`22.x` 则不行。 - ## 没有生效 版本没有切换时: diff --git a/docs/zh-CN/platforms.md b/docs/zh-CN/platforms.md index 8f09d44..ab26d17 100644 --- a/docs/zh-CN/platforms.md +++ b/docs/zh-CN/platforms.md @@ -27,7 +27,7 @@ Node.js package node-v19.8.1-win-arm64.zip is not listed in https://nodejs.org/d | Linux ppc64le | `linux-ppc64le.tar.gz` | 4.3.2 及以后,5.0.0 到 5.6.0 除外 | | Linux s390x | `linux-s390x.tar.gz` | 6.6.0 及以后 | | Linux 386 | `linux-x86.tar.gz` | 0.8.6 到 9.11.2,0.9.0、0.11.4 和 0.11.6 除外 | -| Linux arm | `linux-armv7l.tar.gz` | 4.0.0 到 23.11.1,8.1.1 除外。未发布:0.5.2 请求的是 `linux-arm`,Node.js 从未发布过,所以每次安装都会失败 | +| Linux arm | `linux-armv7l.tar.gz` | 4.0.0 到 23.11.1,8.1.1 除外 | | Linux amd64,musl | `linux-x64-musl.tar.gz` | 见 [musl.md](musl.md#哪些版本有-musl-构建) | | Linux arm64,musl | `linux-arm64-musl.tar.gz` | 见 [musl.md](musl.md#哪些版本有-musl-构建) | | macOS amd64 | `darwin-x64.tar.gz` | 0.8.6 及以后,0.9.0、0.11.4 和 0.11.6 除外 | @@ -42,7 +42,7 @@ Node.js package node-v19.8.1-win-arm64.zip is not listed in https://nodejs.org/d ## 不支持的情况 -- **ARMv6,以及 24 起的 32 位 ARM。** vfox 提供一个 `armv7` 的二进制,它报告的是 `arm`,插件为它选 `linux-armv7l` 包,而这个包 Node.js 只发布到 23.11.1。24 起就没有了,安装最终会报 `Node.js package node-v26.12.0-linux-armv7l.tar.gz is not listed in ...`。ARMv6 的包(nodejs.org 上的 `linux-armv6l`,4.0.0 到 11.15.0)从不会被选中。未发布:0.5.2 请求的是 `linux-arm`,Node.js 从未发布过,所以 32 位 ARM 上每次安装都会失败,报 `Node.js package node-v20.19.5-linux-arm.tar.gz is not listed in ...`。 +- **ARMv6,以及 24 起的 32 位 ARM。** vfox 提供一个 `armv7` 的二进制,它报告的是 `arm`,插件为它选 `linux-armv7l` 包,而这个包 Node.js 只发布到 23.11.1。24 起就没有了,安装最终会报 `Node.js package node-v26.12.0-linux-armv7l.tar.gz is not listed in ...`。ARMv6 的包(nodejs.org 上的 `linux-armv6l`,4.0.0 到 11.15.0)从不会被选中。 - **Linux riscv64 和 loong64。** nodejs.org 没有它们的包。[Unofficial Builds](https://github.com/nodejs/unofficial-builds) 站点有 riscv64(17.7.1 到 26.0.0)和 loong64(18.18.0 及以后),但插件只在 musl 上使用那个站点。 ## Linux diff --git a/docs/zh-CN/source-build.md b/docs/zh-CN/source-build.md index d7f0bfe..906c2af 100644 --- a/docs/zh-CN/source-build.md +++ b/docs/zh-CN/source-build.md @@ -10,7 +10,7 @@ vfox add nodejs 需要尚未发布的内容(`main` 分支,或者检出的某个 PR)时,就从源码安装:把检出的代码打包成 zip,交给 `vfox add --source`。zip 的顶层必须有 `metadata.lua`、`hooks/` 和 `lib/`,这是插件包的约定(见[共享工作流文档](https://github.com/version-fox/plugin-manifest-action))。 -已发布的插件 zip 的 URL 也可以用作 `--source`,例如 `vfox add --source https://github.com/version-fox/vfox-nodejs/releases/download/v0.0.5/vfox-nodejs_0.0.5.zip`。 +已发布的插件 zip 的 URL 也可以用作 `--source`,例如 `vfox add --source https://github.com/version-fox/vfox-nodejs/releases/download/v0.5.3/vfox-nodejs-0.5.3.zip`。 所有系统都需要事先装好 [vfox](https://github.com/version-fox/vfox) 本身和 `git`。 diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 84a0ecc..f04ecdd 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -14,8 +14,6 @@ 插件读不到这个版本的 `SHASUMS256.txt`,原因写在冒号后面。`HTTP 404 from
` 表示服务器上没有这个文件:要么这个版本不存在(`24.99.0`),要么镜像里没有它。网络错误(`Get "
": tls: failed to verify certificate: x509: certificate signed by unknown authority`、`... connection refused`、`... EOF`)表示连不上服务器:镜像不可用、代理有问题,或者 TLS 出了问题。见[网络](#网络)。 -未发布:0.5.2 只打印 `get checksum failed`,没有别的内容,所以看不出原因。`vfox search nodejs` 向同一台服务器请求索引,会打印真正的错误。 - ### `Node.js package node-v19.8.1-win-arm64.zip is not listed in https://nodejs.org/dist/v19.8.1/SHASUMS256.txt` 这个版本是存在的,但 Node.js 没有以插件请求的名字为你的平台发布包。`vfox search nodejs` 列出的版本里,有的并没有你所在平台的包,因为索引里没有写明哪些版本有。提示里的文件名就是插件要找的那个。请对照 [platforms.md](platforms.md),它也列出了不支持的情况(ARMv6、24 起的 32 位 ARM、riscv64、loong64)。 @@ -38,11 +36,9 @@ vfox 没有告诉插件当前运行在哪种 CPU 上。这是不应该出现的 这个 musl 系统缺少 Node.js 的 musl 包所链接的库:所有 musl 包都链接 `libstdc++`,26.8.0 及以后的 musl 包还链接 `libatomic`。提示里写明了缺的是哪个包,以及在 Alpine(`apk add libatomic`)和 OpenWrt(`opkg install libatomic`)上安装它的命令。安装在解压之后失败,不会登记任何内容。请先安装这个库,再重新执行安装。见 [musl.md](musl.md#依赖的系统库)。 -未发布:0.5.2 只查找 `libstdc++`,提示里也没有命令。缺少 `libatomic` 要到后面才会暴露,表现为 `node` 自己报的错,见下文。 - ### `Node.js (musl build) cannot run on this system: Error relocating ...` -解压出来的 `node` 需要一个符号,而系统里没有任何库提供它。安装在解压之后失败,不会登记任何内容。未发布:0.5.2 在解压之后不会运行 `node`,这个错误要到你自己运行它的时候才会出现。见 [musl.md](musl.md#依赖的系统库)。 +解压出来的 `node` 需要一个符号,而系统里没有任何库提供它。安装在解压之后失败,不会登记任何内容。见 [musl.md](musl.md#依赖的系统库)。 ### `checksum error` @@ -81,8 +77,8 @@ vfox 会打印 `Verifying checksum ...`,拿下载的文件和这个校验 - `node: error while loading shared libraries: libatomic.so.1: cannot open shared object file`。Node.js 25 及以后的版本要链接 `libatomic`,而原版 Debian 和 Ubuntu 没有它:`sudo apt install --assume-yes libatomic1`。见 [platforms.md](platforms.md#linux)。 - 在 Alpine 上报 `node: not found`,尽管文件是存在的。这是把 glibc 的包安装到了 musl 系统上:要么插件没有检测到 musl,要么 `VFOX_NODEJS_LIBC` 的值是 `gnu` 或 `glibc`。见 [musl.md](musl.md#检测与覆盖)。 -- 在 Alpine 上先报 `Error loading shared library libatomic.so.1: No such file or directory`,接着报 `Error relocating ...: __atomic_compare_exchange: symbol not found`。26.8.0 及以后的 musl 包需要 `libatomic`:`apk add libatomic`。未发布:安装本身会以上面那条提示停下来,0.5.2 则要到这里才会报错。见 [musl.md](musl.md#依赖的系统库)。 -- 在 musl 系统上报 `Error relocating ... symbol not found`,而且前面没有上一条里关于 `libatomic` 的那一行。说明缺少某个库,或者库的版本太旧。未发布:安装会以 `cannot run on this system` 停下来,0.5.2 则要到这里才会报错。见 [musl.md](musl.md#依赖的系统库)。 +- 在 Alpine 上先报 `Error loading shared library libatomic.so.1: No such file or directory`,接着报 `Error relocating ...: __atomic_compare_exchange: symbol not found`。26.8.0 及以后的 musl 包需要 `libatomic`:`apk add libatomic`。从 0.5.3 起,安装本身就会以上面那条提示停下来,所以遇到这个错误的,是早期版本的插件装好的版本。见 [musl.md](musl.md#依赖的系统库)。 +- 在 musl 系统上报 `Error relocating ... symbol not found`,而且前面没有上一条里关于 `libatomic` 的那一行。说明缺少某个库,或者库的版本太旧。从 0.5.3 起,`node --version` 这样失败时,安装会以 `cannot run on this system` 停下来。见 [musl.md](musl.md#依赖的系统库)。 ## 网络 @@ -105,7 +101,7 @@ vfox config proxy.url http://127.0.0.1:7890 `proxy.enable` 为 `false` 时,通常的 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` 环境变量依然有效。代理不可用时,搜索会显示 `proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused`。 -`vfox search nodejs` 的常见失败原因如下。`vfox install` 会在 `get checksum failed:` 之后报告同样的原因。未发布:0.5.2 会省略它,只有搜索会打印: +`vfox search nodejs` 的常见失败原因如下。`vfox install` 会在 `get checksum failed:` 之后报告同样的原因: | `Failed to fetch Node.js versions:` 之后 | 原因 | | --- | --- | diff --git a/docs/zh-CN/versions.md b/docs/zh-CN/versions.md index a69b2ff..eea1f1e 100644 --- a/docs/zh-CN/versions.md +++ b/docs/zh-CN/versions.md @@ -28,7 +28,7 @@ vfox install nodejs@latest # 所有版本线中最新的版本 - “最新”指索引里列出的所有版本中数字最大的那个,不论是否属于 LTS。尚未进入长期支持的版本线(比如现在的 26)可以比最新的 LTS 版本线更新,所以 `latest` 并不等于 LTS 版本。 - `24` 和 `24.21` 是在索引里查找的,不是在已安装的版本里查找。`vfox install nodejs@24` 会装上比你已有的更新的 24.x;已经是最新版本时,则打印 `nodejs@24.22.0 is already installed`。 - 索引里只列出由三段数字组成的版本,别的一概没有:没有 `-rc` 构建、每日构建,也没有四段数字的版本号。这些写法最终都会报 `version not found for provided version ...`。 -- 不存在的版本号(`24.99.0`)最终会报 `get checksum failed: HTTP 404 from ...`,因为 nodejs.org 上没有对应的目录(未发布:0.5.2 省略了 `failed` 后面的部分)。版本存在但没有你所在平台的包时,最终会报 `Node.js package ... is not listed in ...`。见 [troubleshooting.md](troubleshooting.md#插件给出的提示) 和 [platforms.md](platforms.md)。 +- 不存在的版本号(`24.99.0`)最终会报 `get checksum failed: HTTP 404 from ...`,因为 nodejs.org 上没有对应的目录。版本存在但没有你所在平台的包时,最终会报 `Node.js package ... is not listed in ...`。见 [troubleshooting.md](troubleshooting.md#插件给出的提示) 和 [platforms.md](platforms.md)。 - 每次下载都会对照该版本 `SHASUMS256.txt` 里的 SHA-256 校验和进行检查。vfox 会打印 `Verifying checksum ...`,校验和不一致时会报 `checksum error` 并停止,什么也不会安装。 - 安装时如果发现同名的版本已经存在,就不会下载任何东西。