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

@@ -62,7 +62,7 @@ runs:
     # 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
       env:
@@ -71,7 +71,7 @@ runs:
 
     - 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
       env:
@@ -88,7 +88,7 @@ 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
@@ -97,7 +97,7 @@ runs:
         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

.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": {

packages/cli/publish-native-addons.ts

@@ -46,6 +46,8 @@ const RUST_TARGETS: Record<string, string> = {
   'darwin-x64': 'x86_64-apple-darwin',
   'linux-arm64-gnu': 'aarch64-unknown-linux-gnu',
   'linux-x64-gnu': 'x86_64-unknown-linux-gnu',
+  'linux-x64-musl': 'x86_64-unknown-linux-musl',
+  'linux-arm64-musl': 'aarch64-unknown-linux-musl',
   'win32-arm64-msvc': 'aarch64-pc-windows-msvc',
   'win32-x64-msvc': 'x86_64-pc-windows-msvc',
 };
@@ -63,11 +65,13 @@ for (const file of platformDirs) {
 }
 
 // Platform metadata for CLI packages
-const PLATFORM_META: Record<string, { os: string; cpu: string }> = {
+const PLATFORM_META: Record<string, { os: string; cpu: string; libc?: string }> = {
   'darwin-arm64': { os: 'darwin', cpu: 'arm64' },
   'darwin-x64': { os: 'darwin', cpu: 'x64' },
-  'linux-arm64-gnu': { os: 'linux', cpu: 'arm64' },
-  'linux-x64-gnu': { os: 'linux', cpu: 'x64' },
+  'linux-arm64-gnu': { os: 'linux', cpu: 'arm64', libc: 'glibc' },
+  'linux-x64-gnu': { os: 'linux', cpu: 'x64', libc: 'glibc' },
+  'linux-x64-musl': { os: 'linux', cpu: 'x64', libc: 'musl' },
+  'linux-arm64-musl': { os: 'linux', cpu: 'arm64', libc: 'musl' },
   'win32-arm64-msvc': { os: 'win32', cpu: 'arm64' },
   'win32-x64-msvc': { os: 'win32', cpu: 'x64' },
 };
@@ -109,14 +113,17 @@ for (const [platform, rustTarget] of Object.entries(RUST_TARGETS)) {
   }
 
   // Generate package.json
-  const cliPackage = {
+  const cliPackage: Record<string, unknown> = {
     name: `@voidzero-dev/vite-plus-cli-${platform}`,
     version: cliVersion,
     os: [meta.os],
     cpu: [meta.cpu],
     files: [binaryName],
     description: `Vite+ CLI binary for ${platform}`,
   };
+  if (meta.libc) {
+    cliPackage.libc = [meta.libc];
+  }
   writeFileSync(join(platformCliDir, 'package.json'), JSON.stringify(cliPackage, null, 2) + '\n');
 
   // Publish CLI package