feat(release): add Windows ARM64 and Linux musl prebuilt binary support

Add aarch64-pc-windows-msvc, x86_64-unknown-linux-musl, and
aarch64-unknown-linux-musl as build targets in the release pipeline,
NAPI config, and publish scripts. Add libc field to CLI platform
packages for correct npm resolution on musl vs glibc systems. Add
install test jobs for Windows ARM64, Linux musl x64 (Docker), and
Linux musl arm64 (QEMU). Document supported platforms in the getting
started guide.

Author: fengmk2

.github/actions/build-upstream/action.yml

@@ -58,22 +58,48 @@ runs:
         pnpm --filter "@voidzero-dev/*" build
         pnpm --filter vite-plus build-ts
 
+    # Musl targets need Zig as the C/C++ cross-compiler (via cargo-zigbuild)
+    # GNU targets use napi-cross which bundles its own cross toolchain
+    - name: Setup Zig
+      if: contains(inputs.target, 'musl')
+      uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2.2.1
+      with:
+        version: 0.14.1
+
+    - name: Install cargo-zigbuild
+      if: contains(inputs.target, 'musl')
+      uses: taiki-e/install-action@f92912fad184299a31e22ad070a5059fd07d4f59 # v2.68.7
+      with:
+        tool: cargo-zigbuild
+
+    # Determine cross-compile flag: musl uses Zig (-x), GNU uses napi-cross
+    - name: Determine cross-compile strategy
+      id: cross
+      if: contains(inputs.target, 'linux')
+      shell: bash
+      run: |
+        if [[ "${{ inputs.target }}" == *"musl"* ]]; then
+          echo "napi-flag=-x" >> $GITHUB_OUTPUT
+        else
+          echo "napi-flag=--use-napi-cross" >> $GITHUB_OUTPUT
+        fi
+
     # NAPI builds - only run on cache miss (slow, especially on Windows)
     # Must run before vite-plus TypeScript builds which depend on the bindings
     - name: Build NAPI bindings (x86_64-linux)
       shell: bash
-      if: steps.cache-restore.outputs.cache-hit != 'true' && inputs.target == 'x86_64-unknown-linux-gnu'
+      if: steps.cache-restore.outputs.cache-hit != 'true' && startsWith(inputs.target, 'x86_64-unknown-linux')
       run: |
-        pnpm --filter=vite-plus build-native --target ${{ inputs.target }} --use-napi-cross
+        pnpm --filter=vite-plus build-native --target ${{ inputs.target }} ${{ steps.cross.outputs.napi-flag }}
       env:
         TARGET_CC: clang
         DEBUG: napi:*
 
     - name: Build NAPI bindings (aarch64-linux)
       shell: bash
-      if: steps.cache-restore.outputs.cache-hit != 'true' && inputs.target == 'aarch64-unknown-linux-gnu'
+      if: steps.cache-restore.outputs.cache-hit != 'true' && startsWith(inputs.target, 'aarch64-unknown-linux')
       run: |
-        pnpm --filter=vite-plus build-native --target ${{ inputs.target }} --use-napi-cross
+        pnpm --filter=vite-plus build-native --target ${{ inputs.target }} ${{ steps.cross.outputs.napi-flag }}
       env:
         TARGET_CC: clang
         TARGET_CFLAGS: '-D_BSD_SOURCE'
@@ -88,19 +114,19 @@ runs:
         DEBUG: napi:*
 
     - name: Build Rust CLI binary (x86_64-linux)
-      if: steps.cache-restore.outputs.cache-hit != 'true' && inputs.target == 'x86_64-unknown-linux-gnu'
+      if: steps.cache-restore.outputs.cache-hit != 'true' && startsWith(inputs.target, 'x86_64-unknown-linux')
       shell: bash
       run: |
-        pnpm exec napi build --use-napi-cross --target ${{ inputs.target }} --release -p vite_global_cli
+        pnpm exec napi build ${{ steps.cross.outputs.napi-flag }} --target ${{ inputs.target }} --release -p vite_global_cli
       env:
         TARGET_CC: clang
         DEBUG: napi:*
 
     - name: Build Rust CLI binary (aarch64-linux)
-      if: steps.cache-restore.outputs.cache-hit != 'true' && inputs.target == 'aarch64-unknown-linux-gnu'
+      if: steps.cache-restore.outputs.cache-hit != 'true' && startsWith(inputs.target, 'aarch64-unknown-linux')
       shell: bash
       run: |
-        pnpm exec napi build --use-napi-cross --target ${{ inputs.target }} --release -p vite_global_cli
+        pnpm exec napi build ${{ steps.cross.outputs.napi-flag }} --target ${{ inputs.target }} --release -p vite_global_cli
       env:
         TARGET_CC: clang
         TARGET_CFLAGS: '-D_BSD_SOURCE'

.github/workflows/release.yml

@@ -50,8 +50,14 @@ jobs:
             os: ubuntu-latest
           - target: x86_64-unknown-linux-gnu
             os: ubuntu-latest
+          - target: x86_64-unknown-linux-musl
+            os: ubuntu-latest
+          - target: aarch64-unknown-linux-musl
+            os: ubuntu-latest
           - target: x86_64-pc-windows-msvc
             os: windows-latest
+          - target: aarch64-pc-windows-msvc
+            os: windows-latest
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - uses: ./.github/actions/clone
@@ -64,14 +70,6 @@ jobs:
       - name: Rustup Adds Target
         run: rustup target add ${{ matrix.settings.target }}
 
-      - name: Add musl target (x86_64)
-        if: ${{ matrix.settings.target == 'x86_64-unknown-linux-gnu' }}
-        run: rustup target add x86_64-unknown-linux-musl
-
-      - name: Add musl target (aarch64)
-        if: ${{ matrix.settings.target == 'aarch64-unknown-linux-gnu' }}
-        run: rustup target add aarch64-unknown-linux-musl
-
       - uses: oxc-project/setup-node@fdbf0dfd334c4e6d56ceeb77d91c76339c2a0885 # v1.0.4
 
       - name: Set binding version

.github/workflows/test-standalone-install.yml

@@ -178,6 +178,119 @@ jobs:
               # cd hello && vp run build
             "
 
+  test-install-sh-musl-x64:
+    name: Test install.sh (Linux x64 musl via Docker)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Run install.sh in Alpine container
+        run: |
+          docker run --rm --platform linux/amd64 \
+            -v "${{ github.workspace }}:/workspace" \
+            -e VITE_PLUS_VERSION=test \
+            alpine:3.21 sh -c "
+              apk add --no-cache curl bash ca-certificates
+              cat /workspace/packages/cli/install.sh | bash
+              if [ -f ~/.profile ]; then
+                source ~/.profile
+              elif [ -f ~/.bashrc ]; then
+                source ~/.bashrc
+              else
+                export PATH=\"\$HOME/.vite-plus/bin:\$PATH\"
+              fi
+
+              vp --version
+              vp --help
+              vp dlx print-current-version
+
+              # Verify bin setup
+              BIN_PATH=\"\$HOME/.vite-plus/bin\"
+              if [ ! -d \"\$BIN_PATH\" ]; then
+                echo \"Error: Bin directory not found: \$BIN_PATH\"
+                exit 1
+              fi
+              for shim in node npm npx; do
+                if [ ! -f \"\$BIN_PATH/\$shim\" ]; then
+                  echo \"Error: Shim not found: \$BIN_PATH/\$shim\"
+                  exit 1
+                fi
+                echo \"Found shim: \$BIN_PATH/\$shim\"
+              done
+              vp env doctor
+
+              export VITE_LOG=trace
+              vp env run --node 24 -- node -p \"process.versions\"
+
+              # Verify upgrade
+              vp upgrade --check
+              vp upgrade 0.0.0-f74442ad.20260222-0755
+              vp --version
+              vp upgrade --rollback
+              vp --version
+            "
+
+  test-install-sh-musl-arm64:
+    name: Test install.sh (Linux ARM64 musl via QEMU)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3.6.0
+        with:
+          platforms: arm64
+
+      - name: Run install.sh in ARM64 Alpine container
+        run: |
+          docker run --rm --platform linux/arm64 \
+            -v "${{ github.workspace }}:/workspace" \
+            -e VITE_PLUS_VERSION=test \
+            alpine:3.21 sh -c "
+              apk add --no-cache curl bash ca-certificates
+              cat /workspace/packages/cli/install.sh | bash
+              if [ -f ~/.profile ]; then
+                source ~/.profile
+              elif [ -f ~/.bashrc ]; then
+                source ~/.bashrc
+              else
+                export PATH=\"\$HOME/.vite-plus/bin:\$PATH\"
+              fi
+
+              vp --version
+              vp --help
+              vp dlx print-current-version
+
+              # Verify bin setup
+              BIN_PATH=\"\$HOME/.vite-plus/bin\"
+              if [ ! -d \"\$BIN_PATH\" ]; then
+                echo \"Error: Bin directory not found: \$BIN_PATH\"
+                exit 1
+              fi
+              for shim in node npm npx; do
+                if [ ! -f \"\$BIN_PATH/\$shim\" ]; then
+                  echo \"Error: Shim not found: \$BIN_PATH/\$shim\"
+                  exit 1
+                fi
+                echo \"Found shim: \$BIN_PATH/\$shim\"
+              done
+              vp env doctor
+
+              export VITE_LOG=trace
+              vp env run --node 24 -- node -p \"process.versions\"
+
+              # Verify upgrade
+              vp upgrade --check
+              vp upgrade 0.0.0-f74442ad.20260222-0755
+              vp --version
+              vp upgrade --rollback
+              vp --version
+            "
+
   test-install-ps1-v5:
     name: Test install.ps1 (Windows x64, PowerShell 5.1)
     runs-on: windows-latest
@@ -254,6 +367,73 @@ jobs:
           vp upgrade --rollback
           vp --version
 
+  test-install-ps1-arm64:
+    name: Test install.ps1 (Windows ARM64)
+    runs-on: windows-11-arm
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Run install.ps1
+        shell: pwsh
+        run: |
+          & ./packages/cli/install.ps1
+
+      - name: Set PATH
+        shell: bash
+        run: |
+          echo "$USERPROFILE\.vite-plus\bin" >> $GITHUB_PATH
+
+      - name: Verify installation
+        shell: pwsh
+        working-directory: ${{ runner.temp }}
+        run: |
+          Write-Host "PATH: $env:Path"
+          vp --version
+          vp --help
+          vp create vite --no-interactive --no-agent -- hello --no-interactive -t vanilla
+          cd hello
+          vp run build
+          vp --version
+
+      - name: Verify bin setup
+        shell: pwsh
+        run: |
+          $binPath = "$env:USERPROFILE\.vite-plus\bin"
+          Get-ChildItem -Force $binPath
+          if (-not (Test-Path $binPath)) {
+            Write-Error "Bin directory not found: $binPath"
+            exit 1
+          }
+
+          $expectedShims = @("node.cmd", "npm.cmd", "npx.cmd")
+          foreach ($shim in $expectedShims) {
+            $shimFile = Join-Path $binPath $shim
+            if (-not (Test-Path $shimFile)) {
+              Write-Error "Shim not found: $shimFile"
+              exit 1
+            }
+            Write-Host "Found shim: $shimFile"
+          }
+          where.exe node
+          where.exe npm
+          where.exe npx
+          where.exe vp
+
+          $env:Path = "$env:USERPROFILE\.vite-plus\bin;$env:Path"
+          vp env doctor
+          vp env run --node 24 -- node -p "process.versions"
+
+      - name: Verify upgrade
+        shell: pwsh
+        run: |
+          vp upgrade --check
+          vp upgrade 0.0.0-f74442ad.20260222-0755
+          vp --version
+          vp upgrade --rollback
+          vp --version
+
   test-install-ps1:
     name: Test install.ps1 (Windows x64)
     runs-on: windows-latest

crates/vite_global_cli/src/commands/upgrade/registry.rs

@@ -99,6 +99,8 @@ mod tests {
             "darwin-x64",
             "linux-arm64-gnu",
             "linux-x64-gnu",
+            "linux-x64-musl",
+            "linux-arm64-musl",
             "win32-arm64-msvc",
             "win32-x64-msvc",
         ];
@@ -123,10 +125,6 @@ mod tests {
         for suffix in &detection_suffixes {
             let package_name =
                 format!("{PLATFORM_PACKAGE_SCOPE}/{CLI_PACKAGE_NAME_PREFIX}-{suffix}");
-            // musl variants are not published, so skip them
-            if suffix.contains("musl") {
-                continue;
-            }
             assert!(
                 published_packages.contains(&package_name),
                 "Platform suffix '{suffix}' produces CLI package name '{package_name}' \

docs/vite/guide/index.md

@@ -32,6 +32,25 @@ For Windows:
 irm https://staging.viteplus.dev/install.ps1 | iex
 ```
 
+::: details Supported platforms
+
+Prebuilt binaries are distributed for the following platforms (grouped by [Node.js v24 platform support tier](https://github.com/nodejs/node/blob/v24.x/BUILDING.md#platform-list)):
+
+- Tier 1
+  - Linux x64 glibc (`x86_64-unknown-linux-gnu`)
+  - Linux arm64 glibc (`aarch64-unknown-linux-gnu`)
+  - Windows x64 (`x86_64-pc-windows-msvc`)
+  - macOS x64 (`x86_64-apple-darwin`)
+  - macOS arm64 (`aarch64-apple-darwin`)
+- Tier 2
+  - Windows arm64 (`aarch64-pc-windows-msvc`)
+- Experimental
+  - Linux x64 musl (`x86_64-unknown-linux-musl`)
+- Other
+  - Linux arm64 musl (`aarch64-unknown-linux-musl`)
+
+:::
+
 ## Node.js Version Manager
 
 Vite+ includes a built-in Node.js version manager. During installation, you can opt-in to let Vite+ manage your Node.js versions.

packages/cli/package.json

@@ -339,7 +339,10 @@
       "x86_64-apple-darwin",
       "aarch64-unknown-linux-gnu",
       "x86_64-unknown-linux-gnu",
-      "x86_64-pc-windows-msvc"
+      "x86_64-unknown-linux-musl",
+      "aarch64-unknown-linux-musl",
+      "x86_64-pc-windows-msvc",
+      "aarch64-pc-windows-msvc"
     ]
   },
   "engines": {