Add musl libc support (Alpine/OpenWrt) with Alpine E2E

Author: linghengqian

.github/workflows/e2e.yml

@@ -42,6 +42,21 @@ jobs:
           persist-credentials: false
       - run: docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
 
+  e2e-linux-musl:
+    if: github.repository == 'version-fox/vfox-nodejs'
+    name: Linux musl container (${{ matrix.runs-on }})
+    strategy:
+      fail-fast: false
+      matrix:
+        runs-on: [ubuntu-latest, ubuntu-26.04-arm]
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - run: docker compose -f tests/e2e/linux/compose.alpine.yaml run --rm e2e
+
   e2e-windows:
     if: github.repository == 'version-fox/vfox-nodejs'
     name: Windows container (${{ matrix.runs-on }})

README.md

@@ -19,12 +19,23 @@ sudo apt install --assume-yes libatomic1
 vfox use --global nodejs@26.10.0
 ```
 
+### Example: Alpine / musl
+
+```bash
+apk add libstdc++
+vfox add nodejs
+vfox install nodejs@22.23.3
+vfox use --global nodejs@22.23.3
+```
+
 You can verify this using the following command:
 
 ```bash
 node -v
 ```
 
+musl details (OpenWrt, tarball matrix, mirror fallback): see [docs/musl.md](docs/musl.md).
+
 ## Mirror
 
 See [docs/mirror.md](docs/mirror.md) for details.

docs/e2e.md

@@ -52,6 +52,7 @@ pin `VFOX_VERSION` and `MIRROR` explicitly to widen or narrow the matrix.
 | `NODE_VERSION`      | `22.23.3`          | Pinned Node.js release installed by the suite                           |
 | `E2E_MAX_JOBS`      | `3` (Linux), `2` (Windows) | Parallel containers per host                                     |
 | `E2E_RETRY_ATTEMPTS`| `3`                | Attempts per network-touching exec (linear 10s backoff)                 |
+| `E2E_LINUX_BASE`    | `ubuntu`           | Linux userland: `ubuntu` (glibc) or `alpine` (musl, see docs/musl.md)   |
 
 ## Ubuntu
 
@@ -81,6 +82,22 @@ cd ./vfox-nodejs/
 DOCKER_SOCK="$XDG_RUNTIME_DIR/docker.sock" docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
 ```
 
+## Alpine (musl)
+
+Same host requirement. The Alpine suite builds
+`tests/e2e/linux/Dockerfile.alpine` (musl userland with `libstdc++`) and
+asserts the musl userland before running the standard flow, proving the
+plugin selects the `*-musl` tarballs
+([issue #29](https://github.com/version-fox/vfox-nodejs/issues/29)).
+See [docs/musl.md](musl.md) for the tarball matrix.
+
+```bash
+docker compose -f tests/e2e/linux/compose.alpine.yaml run --rm e2e
+```
+
+Scope it down locally the same way, e.g.
+`VFOX_VERSION=latest MIRROR=default E2E_MAX_JOBS=1` in front of the command.
+
 ## Windows 11 Pro
 
 Windows containers cannot be emulated across architectures, so the ARM64

docs/musl.md

@@ -0,0 +1,81 @@
+# musl libc support (Alpine, OpenWrt/ImmortalWrt)
+
+Node.js official Linux tarballs link glibc (`ld-linux-*`). On musl systems
+there is no glibc loader, so the stock download fails with `not found` /
+`Error loading shared library ld-linux-aarch64.so.1`.
+See [issue #29](https://github.com/version-fox/vfox-nodejs/issues/29).
+
+This plugin detects musl and installs a musl tarball instead.
+
+## Requirements
+
+On musl systems the Node.js binary additionally needs `libstdc++`
+(per [nodejs/unofficial-builds](https://github.com/nodejs/unofficial-builds)):
+
+```sh
+# Alpine
+apk add libstdc++
+
+# OpenWrt/ImmortalWrt (opkg)
+opkg update && opkg install libstdcpp
+```
+
+Without it `node --version` fails with
+`Error relocating ... symbol not found` even when the musl tarball is used.
+The plugin checks this in its `PostInstall` hook: on musl Linux without
+`libstdc++.so.6` at a well-known location the install fails fast with the
+matching command (`apk add libstdc++` on Alpine,
+`opkg update && opkg install libstdcpp` on OpenWrt) instead of failing later
+with the cryptic relocation error.
+
+## Which tarball is installed
+
+| Host | Tarball | Source |
+| ---- | ------- | ------ |
+| Linux glibc, x64/arm64 | `node-v<V>-linux-x64.tar.gz` etc. | `nodejs.org/dist` (or `$VFOX_NODEJS_MIRROR`) |
+| Linux musl, x64 | `node-v<V>-linux-x64-musl.tar.gz` | official index when present, else unofficial |
+| Linux musl, arm64 | `node-v<V>-linux-arm64-musl.tar.gz` | `unofficial-builds.nodejs.org` (official never ships it) |
+
+Notes:
+
+- Official `nodejs.org/dist` only carries `linux-x64-musl` for recent
+  releases (roughly `26.8+`, `24.20+`, `22.23.3+`) and never carries
+  `linux-arm64-musl`. Older releases and all `arm64-musl` installs fall back
+  to `https://unofficial-builds.nodejs.org/download/release` automatically.
+- A mirror set via `$VFOX_NODEJS_MIRROR` (see [mirror](mirror.md)) is tried
+  first. A `SHASUMS256.txt` fetch failure still errors (bogus mirrors stay
+  rejected); only a missing musl filename falls back to unofficial.
+- musl builds exist only for `x64` and `arm64`. Other Linux architectures
+  (e.g. `x86`) error out with a pointer to the README.
+- After install the plugin returns a note pointing at the README so the
+  `libstdc++` requirement is visible in normal `vfox install` output.
+
+## Detection and override
+
+Detection order in `lib/util.lua`:
+
+1. `$VFOX_NODEJS_LIBC`: `musl` forces musl, `gnu`/`glibc` forces glibc.
+   Useful on exotic userlands and in tests.
+2. `RUNTIME.envType` when a future vfox core provides it (`musl`/`gnu`).
+3. File probes readable from Lua: `/etc/alpine-release`,
+   `/lib`/`/usr/lib`/`/lib64` `ld-musl-*.so.1`. musl wins when both linkers
+   exist (e.g. `gcompat` shims). Non-Linux is never musl.
+
+```sh
+# Force musl selection (debugging only)
+VFOX_NODEJS_LIBC=musl vfox install nodejs@22.23.3
+```
+
+## E2E coverage
+
+The musl path runs in Docker, never against a local musl host:
+
+```sh
+docker compose -f tests/e2e/linux/compose.alpine.yaml run --rm e2e
+```
+
+The suite asserts the Alpine userland (`ld-musl-*` present, no `ld-linux-*`,
+`ldd` reports musl) and then runs the standard flow
+(install with checksum, `node`/`npm`, shorthands, legacy files, search).
+See [e2e](e2e.md) for the shared knobs (`VFOX_VERSION`, `MIRROR`,
+`NODE_VERSION`, `E2E_MAX_JOBS`, `E2E_RETRY_ATTEMPTS`).

hooks/post_install.lua

@@ -0,0 +1,34 @@
+-- Copyright 2026 Han Li and contributors
+--
+-- Licensed under the Apache License, Version 2.0 (the "License");
+-- you may not use this file except in compliance with the License.
+-- You may obtain a copy of the License at
+--
+--   http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+
+local util = require("util")
+
+--- Fail fast when the musl Node.js binary cannot run: it needs libstdc++,
+--- which musl distributions do not install by default. Without this check
+--- the install looks successful and only `node --version` fails later with
+--- `Error relocating ... symbol not found`.
+--- See https://github.com/version-fox/vfox-nodejs/issues/29
+--- @param ctx table Context information
+function PLUGIN:PostInstall(ctx)
+    if RUNTIME.osType ~= "linux" then
+        return
+    end
+    if not util.is_musl() then
+        return
+    end
+    if util.has_libstdcxx() then
+        return
+    end
+    error("Node.js (musl build) requires libstdc++, which was not found on this system. Run `" .. util.libstdcxx_hint() .. "` (possibly as root), then reinstall. See " .. util.ReadmeUrl)
+end

hooks/pre_install.lua

@@ -65,8 +65,33 @@ function PLUGIN:PreInstall(ctx)
         end
     end
 
-    local filename = util.FileName:format(version, osType, arch_type, ext)
+    local filename = nil
     local baseUrl = util.getBaseUrl() .. util.NodeBaseUrl:format(version)
+    local is_musl = false
+    local musl_note = nil
+    if RUNTIME.osType == "linux" then
+        is_musl = util.is_musl()
+        if is_musl then
+            if arch_type == "x64" then
+                arch_type = "x64-musl"
+            elseif arch_type == "arm64" then
+                arch_type = "arm64-musl"
+            else
+                error(
+                    "Node.js musl builds are only available for x64 and arm64, got "
+                        .. tostring(arch_type)
+                        .. ". See "
+                        .. util.ReadmeUrl
+                )
+            end
+            filename = util.FileName:format(version, osType, arch_type, ext)
+            musl_note = "musl libc detected, installed " .. filename .. ". See " .. util.ReadmeUrl
+            print("Note: " .. musl_note)
+        end
+    end
+    if filename == nil then
+        filename = util.FileName:format(version, osType, arch_type, ext)
+    end
 
     local resp, err = http.get({
         url = baseUrl .. "SHASUMS256.txt",
@@ -75,12 +100,41 @@ function PLUGIN:PreInstall(ctx)
         error("get checksum failed")
     end
     local checksum = util.get_checksum(resp.body, filename)
-    if checksum == nil then
-        error("Node.js package " .. filename .. " is not listed in " .. baseUrl .. "SHASUMS256.txt")
+    if checksum ~= nil then
+        local result = {
+            version = version,
+            url = baseUrl .. filename,
+            sha256 = checksum,
+        }
+        if musl_note ~= nil then
+            result.note = musl_note
+        end
+        return result
+    end
+
+    -- musl fallback to unofficial builds: official nodejs.org/dist only ships
+    -- linux-x64-musl for recent releases and never ships linux-arm64-musl,
+    -- while unofficial-builds covers both (including older releases).
+    -- A SHASUMS fetch failure still errors (bogus mirrors must stay rejected);
+    -- only a missing filename falls through here.
+    -- See https://github.com/version-fox/vfox-nodejs/issues/29
+    if is_musl then
+        local unofficialBase = util.UnofficialBaseUrl .. util.NodeBaseUrl:format(version)
+        local uresp, uerr = http.get({
+            url = unofficialBase .. "SHASUMS256.txt",
+        })
+        if uerr == nil and uresp.status_code == 200 then
+            local uchecksum = util.get_checksum(uresp.body, filename)
+            if uchecksum ~= nil then
+                print("Note: " .. filename .. " is not listed in " .. baseUrl .. ", using unofficial musl build")
+                return {
+                    version = version,
+                    url = unofficialBase .. filename,
+                    sha256 = uchecksum,
+                    note = musl_note,
+                }
+            end
+        end
     end
-    return {
-        version = version,
-        url = baseUrl .. filename,
-        sha256 = checksum,
-    }
+    error("Node.js package " .. filename .. " is not listed in " .. baseUrl .. "SHASUMS256.txt")
 end

lib/util.lua

@@ -17,6 +17,8 @@ local UTIL = {}
 UTIL.NodeBaseUrl = "/v%s/"
 UTIL.FileName = "node-v%s-%s-%s%s"
 UTIL.VersionSourceUrl = "/index.json"
+UTIL.UnofficialBaseUrl = "https://unofficial-builds.nodejs.org/download/release"
+UTIL.ReadmeUrl = "https://github.com/version-fox/vfox-nodejs/blob/main/README.md"
 
 function UTIL.getBaseUrl()
     local mirror = os.getenv("VFOX_NODEJS_MIRROR")
@@ -27,6 +29,93 @@ function UTIL.getBaseUrl()
     return mirror:gsub("/$", "")
 end
 
+function UTIL.file_exists(path)
+    local f = io.open(path, "rb")
+    if f then
+        f:close()
+        return true
+    end
+    return false
+end
+
+--- Detect musl libc on Linux (Alpine, OpenWrt/ImmortalWrt, ...).
+--- Order: explicit $VFOX_NODEJS_LIBC override, future RUNTIME.envType,
+--- then well-known linker/marker files. musl wins when both linkers exist
+--- (e.g. gcompat shims on Alpine). Non-Linux is never musl.
+--- See https://github.com/version-fox/vfox-nodejs/issues/29
+function UTIL.is_musl()
+    local override = os.getenv("VFOX_NODEJS_LIBC")
+    if override == "musl" then
+        return true
+    end
+    if override == "gnu" or override == "glibc" then
+        return false
+    end
+    if RUNTIME ~= nil and RUNTIME.envType ~= nil then
+        return RUNTIME.envType == "musl"
+    end
+    if RUNTIME ~= nil and RUNTIME.osType ~= nil and RUNTIME.osType ~= "linux" then
+        return false
+    end
+    if UTIL.file_exists("/etc/alpine-release") then
+        return true
+    end
+    local musl_paths = {
+        "/lib/ld-musl-x86_64.so.1",
+        "/usr/lib/ld-musl-x86_64.so.1",
+        "/lib64/ld-musl-x86_64.so.1",
+        "/lib/ld-musl-aarch64.so.1",
+        "/usr/lib/ld-musl-aarch64.so.1",
+        "/lib64/ld-musl-aarch64.so.1",
+        "/lib/ld-musl-armhf.so.1",
+        "/usr/lib/ld-musl-armhf.so.1",
+        "/lib/ld-musl-x86.so.1",
+        "/usr/lib/ld-musl-x86.so.1",
+    }
+    for _, p in ipairs(musl_paths) do
+        if UTIL.file_exists(p) then
+            return true
+        end
+    end
+    return false
+end
+
+--- Whether libstdc++.so.6 is visible at a well-known location.
+--- Node.js musl tarballs fail with `Error relocating ... symbol not found`
+--- when it is missing.
+function UTIL.has_libstdcxx()
+    local lib_paths = {
+        "/usr/lib/libstdc++.so.6",
+        "/lib/libstdc++.so.6",
+        "/usr/lib64/libstdc++.so.6",
+        "/lib64/libstdc++.so.6",
+        "/usr/lib/x86_64-linux-gnu/libstdc++.so.6",
+        "/lib/x86_64-linux-gnu/libstdc++.so.6",
+        "/usr/lib/aarch64-linux-gnu/libstdc++.so.6",
+        "/lib/aarch64-linux-gnu/libstdc++.so.6",
+        "/usr/lib/arm-linux-gnueabihf/libstdc++.so.6",
+        "/lib/arm-linux-gnueabihf/libstdc++.so.6",
+    }
+    for _, p in ipairs(lib_paths) do
+        if UTIL.file_exists(p) then
+            return true
+        end
+    end
+    return false
+end
+
+--- Install command for the missing libstdc++ runtime, picked by probing
+--- the system package manager (Alpine apk, OpenWrt opkg).
+function UTIL.libstdcxx_hint()
+    if UTIL.file_exists("/etc/alpine-release") or UTIL.file_exists("/sbin/apk") or UTIL.file_exists("/usr/bin/apk") then
+        return "apk add libstdc++"
+    end
+    if UTIL.file_exists("/etc/openwrt_release") or UTIL.file_exists("/bin/opkg") or UTIL.file_exists("/usr/bin/opkg") then
+        return "opkg update && opkg install libstdcpp"
+    end
+    return "install libstdc++ with the system package manager (Alpine: apk add libstdc++, OpenWrt: opkg install libstdcpp)"
+end
+
 function UTIL.compare_versions(v1o, v2o)
     local v1 = v1o.version
     local v2 = v2o.version