linghengqian · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/README.md b/README.md
@@ -1,7 +1,15 @@
 # vfox-nodejs
 
+[中文](README_CN.md) | [English](README.md)
+
 Node.js plugin for [vfox](https://vfox.dev/).
 
+It installs the Node.js release archives published on
+[nodejs.org](https://nodejs.org/dist/), or on a [mirror](docs/mirror.md) of it,
+and checks every download against the SHA-256 sums published next to it. Each
+release comes with its own npm. On Alpine, OpenWrt and other musl systems it
+installs the musl builds. vfox reads `.nvmrc` and `.node-version` through it.
+
 ## Install
 
 After installing [vfox](https://github.com/version-fox/vfox), install the plugin by running:
@@ -10,6 +18,30 @@ After installing [vfox](https://github.com/version-fox/vfox), install the plugin
 vfox add nodejs
 ```
 
+vfox has to be hooked into your shell for `node` to be on the `PATH`, see its
+[quick start](https://vfox.dev/guides/quick-start.html).
+
+### Example
+
+```bash
+vfox add nodejs
+vfox install nodejs@24
+vfox use --global nodejs@24
+```
+
+You can verify this using the following command:
+
+```bash
+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
@@ -28,40 +60,85 @@ not install them.
 ### Example: Alpine / musl
 
 ```bash
+apk add bash libstdc++ libatomic
 vfox add nodejs
-vfox install nodejs@26.11.1
-vfox use --global nodejs@26.11.1
+vfox install nodejs@24
+vfox use --global nodejs@24
 ```
 
-You can verify this using the following command:
+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
+only. musl details (OpenWrt, tarball matrix, mirror fallback, which releases
+have a build): see [docs/musl.md](docs/musl.md).
+
+## Versions and names
+
+A version is a release number: `24.21.0`, or the start of one, `24.21` and `24`,
+which install the newest release of that line. `latest` is the newest release of
+any line, LTS or not. There is no `lts` alias, name the line (`nodejs@24`). The
+name of an install is the release number, `24.21.0`, and `vfox uninstall` needs
+it whole. See [docs/versions.md](docs/versions.md) for details, including what
+`vfox use` and `vfox search` do with them.
+
+## Platforms
+
+Node.js publishes packages for Linux (x64, arm64, ppc64le, s390x), macOS (x64 and
+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.
+
+## npm and global packages
+
+Packages installed with `npm install -g` belong to the Node.js release that was in
+use, and are gone from the others. Node.js 25 and later does not ship Corepack.
+See [docs/npm.md](docs/npm.md).
 
-```bash
-node -v
-```
+## Mirror
 
-musl details (OpenWrt, tarball matrix, mirror fallback): see [docs/musl.md](docs/musl.md).
+Set `VFOX_NODEJS_MIRROR` to use a mirror of `nodejs.org/dist`, for example
+`https://npmmirror.com/mirrors/node`. See [docs/mirror.md](docs/mirror.md) for
+details and for mirrors that were checked.
 
-## Mirror
+## `.nvmrc` and `.node-version`
 
-See [docs/mirror.md](docs/mirror.md) for details.
+vfox reads these files when you enter a directory, and selects the release they
+name if it is installed. What a file can say depends on vfox's
+`legacyVersionFile.strategy`: with the default, `specified`, only a full release
+number selects something. See [docs/nvmrc.md](docs/nvmrc.md) for details.
 
-## FAQ
+## LTS
 
-### Install from source
+See [docs/lts.md](docs/lts.md) for the LTS lines, how to install one and how
+`lts/<codename>` is resolved.
 
-See [docs/source-build.md](docs/source-build.md) for details.
+## pnpm
 
-### LTS
+pnpm as a package manager works next to this plugin. A `node` that pnpm installs
+itself can shadow vfox's. See [docs/pnpm.md](docs/pnpm.md).
 
-See [docs/lts.md](docs/lts.md) for details.
+## Troubleshooting
 
-### pnpm
+See [docs/troubleshooting.md](docs/troubleshooting.md) for the messages the
+plugin prints, proxies and where Node.js is.
 
-See [docs/pnpm.md](docs/pnpm.md) for details.
+## Install from source
 
-### Testing
+See [docs/source-build.md](docs/source-build.md) for details.
 
-See [docs/e2e.md](docs/e2e.md) for details.
+## Development
+
+See [docs/development.md](docs/development.md) for how the plugin works and how
+to change it, [docs/e2e.md](docs/e2e.md) for the container tests, and
+[docs/changes.md](docs/changes.md) for what changed in each release.
 
 ## Releasing this plugin
 
@@ -77,3 +154,10 @@ the tag. If publication fails, re-run the original failed job to resume it.
 The workflow follows the shared `@v1` release-tool version. Updating the tool does
 not release this plugin. See the [shared workflow documentation](https://github.com/version-fox/plugin-manifest-action)
 for the package contract and first-rollout requirements.
+
+## Thanks
+
+- [Node.js](https://nodejs.org/), whose release archives, checksums and version
+  index the plugin installs from
+- [Node.js Unofficial Builds](https://github.com/nodejs/unofficial-builds), where
+  the musl builds that nodejs.org lacks come from
diff --git a/README_CN.md b/README_CN.md
@@ -0,0 +1,110 @@
+# vfox-nodejs
+
+[中文](README_CN.md) | [English](README.md)
+
+[vfox](https://vfox.dev/) 的 Node.js 插件。
+
+它安装 [nodejs.org](https://nodejs.org/dist/) 或其[镜像](docs/zh-CN/mirror.md)上发布的 Node.js 版本压缩包，并对照一同发布的 SHA-256 校验和检查每次下载。每个版本都自带自己的 npm。在 Alpine、OpenWrt 和其他 musl 系统上，安装的是 musl 构建。vfox 通过它读取 `.nvmrc` 和 `.node-version`。
+
+## 安装
+
+先安装 [vfox](https://github.com/version-fox/vfox)，然后执行下面的命令安装插件：
+
+```bash
+vfox add nodejs
+```
+
+要让 `node` 出现在 `PATH` 里，需要先把 vfox 挂载到 Shell，见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。
+
+### 示例
+
+```bash
+vfox add nodejs
+vfox install nodejs@24
+vfox use --global nodejs@24
+```
+
+可以用下面的命令验证：
+
+```bash
+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
+vfox add nodejs
+vfox install nodejs@26.11.1
+sudo apt install --assume-yes libatomic1
+vfox use --global nodejs@26.11.1
+```
+
+注意：`libatomic1` 这一步是为了绕开 Node.js 上游的一个打包缺陷（[nodejs/node#60790](https://github.com/nodejs/node/issues/60790)，目前仍未关闭）：Node 25 及以上版本会链接 `libatomic.so.1`，而原版 Debian/Ubuntu 镜像不自带这个库。系统库由用户自己负责，插件不会安装它们。
+
+### 示例：Alpine / musl
+
+```bash
+apk add bash libstdc++ libatomic
+vfox add nodejs
+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)。
+
+## 版本与命名
+
+版本就是版本号：`24.21.0`，也可以只写开头的部分，如 `24.21` 和 `24`，它们安装对应版本线的最新版本。`latest` 是所有版本线中最新的版本，不论是否属于 LTS。这里没有 `lts` 别名，请写明版本线（`nodejs@24`）。安装后的版本名就是版本号 `24.21.0`，`vfox uninstall` 需要写完整。`vfox use` 和 `vfox search` 怎样处理这些写法，详见 [docs/zh-CN/versions.md](docs/zh-CN/versions.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 为止有包。未发布：0.5.2 无法安装它们。不支持 riscv64 和 loong64。不论你的平台是什么，`vfox search` 都会列出所有版本。表格见 [docs/zh-CN/platforms.md](docs/zh-CN/platforms.md)。
+
+## npm 与全局包
+
+用 `npm install -g` 安装的包属于当时正在使用的那个 Node.js 版本，其他版本里没有它们。Node.js 25 及以后的版本不自带 Corepack。见 [docs/zh-CN/npm.md](docs/zh-CN/npm.md)。
+
+## 镜像
+
+设置 `VFOX_NODEJS_MIRROR` 即可使用 `nodejs.org/dist` 的镜像，例如 `https://npmmirror.com/mirrors/node`。详细说明和检查过的镜像见 [docs/zh-CN/mirror.md](docs/zh-CN/mirror.md)。
+
+## `.nvmrc` 和 `.node-version`
+
+进入目录时，vfox 会读取这些文件，并选中其中指定的版本（前提是已经安装）。文件里能写什么取决于 vfox 的 `legacyVersionFile.strategy`：默认值 `specified` 下，只有完整的版本号才能选中某个版本。详见 [docs/zh-CN/nvmrc.md](docs/zh-CN/nvmrc.md)。
+
+## LTS
+
+LTS 版本线有哪些、怎样安装其中一条，以及 `lts/<codename>` 如何解析，见 [docs/zh-CN/lts.md](docs/zh-CN/lts.md)。
+
+## pnpm
+
+pnpm 作为包管理器，可以和这个插件并存。不过 pnpm 自己安装的 `node` 可能遮蔽 vfox 的。见 [docs/zh-CN/pnpm.md](docs/zh-CN/pnpm.md)。
+
+## 问题排查
+
+插件打印的各种提示、代理设置，以及 Node.js 的位置，见 [docs/zh-CN/troubleshooting.md](docs/zh-CN/troubleshooting.md)。
+
+## 从源码安装
+
+详见 [docs/zh-CN/source-build.md](docs/zh-CN/source-build.md)。
+
+## 开发
+
+插件怎样工作、怎样修改，见 [docs/zh-CN/development.md](docs/zh-CN/development.md)；容器测试见 [docs/zh-CN/e2e.md](docs/zh-CN/e2e.md)；每个版本改了什么，见 [docs/zh-CN/changes.md](docs/zh-CN/changes.md)。
+
+## 发布这个插件
+
+维护者在默认分支上执行 **Actions → Plugin → Run workflow**，填入不带 `v` 前缀的稳定版插件版本号即可发布。共享工作流会更新 `metadata.lua`，创建版本提交和标签，并把 ZIP 包和 manifest 发布到本仓库；不需要在本地打标签，也不需要额外的发布令牌。PR 只运行检查，PR 标题不再触发发布。
+
+仍然支持直接推送版本标签来发布，前提是 `PLUGIN.version` 已经与标签一致。发布失败时，重新运行失败的那个作业即可接着发布。
+
+工作流引用的是共享的 `@v1` 发布工具，升级这个工具不会发布本插件。包的约定和首次接入的要求，见[共享工作流的文档](https://github.com/version-fox/plugin-manifest-action)。
+
+## 致谢
+
+- [Node.js](https://nodejs.org/)，插件安装用的版本压缩包、校验和与版本索引都来自它
+- [Node.js Unofficial Builds](https://github.com/nodejs/unofficial-builds)，nodejs.org 没有的 musl 构建来自这里