在 Windows 10/11 上自建带 Google Apps 与 Magisk/KernelSU 的 WSA:MagiskOnWSA 完整构建与安装指南

原创2026-09-13 13:38:061,917 阅读
文章标签:构建工具虚拟化操作系统

在 Windows 10/11 上自建带 Google Apps 与 Magisk/KernelSU 的 WSA:MagiskOnWSA 完整构建与安装指南

MagiskOnWSA(仓库内位于 MagiskOnWSA 目录)是一套面向开发者的本地构建工具链:你在 Linux(或 WSL2)环境中运行一个脚本,即可在几分钟内把 Windows Subsystem for Android(WSA)官方固件与 Magisk、KernelSU、MindTheGapps 等组件整合成一个可直接双击安装的 Appx 包,随后在 Windows 10/11 上完成无人值守安装。本文以 MagiskOnWSA/docs/README.md 为主干,结合仓库内 scripts、installer 等源码,完整讲解从环境准备、交互式/命令行构建、Windows 端安装到日常更新与 FAQ 排障的全过程,读完即可复现一条"构建→安装→使用→升级"的完整流水线。

注意:原文档明确标注,Magisk on WSA 将于 2025 年 3 月 5 日之后不再可用(Microsoft 已终止 WSA 支持)。本文内容基于仓库当前代码与文档,供研究、学习与存量环境维护参考。


1. 项目定位与核心能力

MagiskOnWSA 的本质是一个"一键整合器":它自动完成官方 WSA 固件下载、Magisk(或 KernelSU)集成、GApps 注入、Amazon Appstore 移除、签名清理与安装脚本生成等全部环节。原文档(MagiskOnWSA/docs/README.md)列出的特性如下:

  • 一键集成 Magisk 与 GApps:几分钟内完成整合,全程交互式选择;
  • 随时跟进新版本:重新运行构建脚本即可拉取最新的 WSA / Magisk 并产出新包;
  • 同时支持 ARM64 与 x64 两种目标架构;
  • 支持 MindTheGapps 作为 Google Apps 方案;
  • 可移除 Amazon Appstore;
  • 修复 VPN 弹窗不显示的问题(借助 VpnDialogs 应用);
  • 增加设备管理(device administration)能力;
  • 无人值守安装(unattended installation);
  • 自动开启 Windows 11 开发者模式;
  • 一键脚本更新到新版本且保留用户数据;
  • 合并全部语言包(构建时通过 MakePri 完成资源合并)。

仓库内另有配套的构建产物说明文档,例如 WSABuilds/Documentation/WSABuilds/Information.md、安装指南 与 升级指南,可与本文互相参照。


2. 构建环境要求

2.1 支持的系统

原文档规定构建主机必须为 Linux(x86_64 或 arm64)。其中推荐使用开箱即用的发行版:

  • Ubuntu(可用 WSL2 运行)
  • Debian(可用 WSL2 运行)
  • openSUSE Tumbleweed(可用 WSL2 运行)

也就是说,纯 Windows 用户不需要独立 Linux 机器——直接在 Windows 上装一个 WSL2 发行版即可满足构建环境。

2.2 依赖清单

发行版 基础包 对话框工具 Python 虚拟环境 Python pip 压缩工具
Debian python3 aria2 unzip sudo whiptail python3-venv python3-pip p7zip-full
openSUSE Tumbleweed 同上 dialog python3-venvctrl 同上 同上
Arch 同 Debian libnewt 同 Debian python-pip p7zip

除此之外:

2.3 依赖安装的源码机制

按原文档,run.sh 会自动处理全部依赖,无需手工敲命令。其底层逻辑在 MagiskOnWSA/scripts/install_deps.sh 中:

  • 检测 whiptail / dialog、pip、aria2c、7z、unzip 是否已安装(对应函数 check_dependencies);
  • 依据 /etc/os-release 中的 ID_LIKE 与各发行版特征文件(如 /etc/debian_version、/etc/arch-release、/etc/SuSE-release)自动选择包管理器(apt-get / pacman / zypper / emerge);
  • 检测到缺失依赖后自动调用对应包管理器安装,并做发行版之间的包名映射(例如 Arch 下 whiptail→libnewt、p7zip-full→p7zip);
  • Python ≥ 3.11 时自动创建虚拟环境 python3-env,再通过 requirements.txt 安装 Python 依赖。

这也解释了原文档"Ready to use right out of the box"的说法:Ubuntu / Debian / openSUSE Tumbleweed 上直接运行脚本即可完成一切准备工作。


3. 完整构建流程(原文档 Text Guide 全文展开)

3.1 克隆仓库并进入目录

git clone https://github.com/LSPosed/MagiskOnWSALocal.git --depth 1
cd MagiskOnWSALocal

说明:以上为原文档中的克隆地址(--depth 1 只拉取最新一次提交,速度更快)。若你使用的是本文所在仓库的工作副本,进入对应目录并保证其中包含 MagiskOnWSA/scripts/ 与 MagiskOnWSA/installer/ 即可。

3.2 运行交互式构建脚本

./scripts/run.sh

MagiskOnWSA/scripts/run.sh 会先自动调用 install_deps.sh 检查依赖,然后基于 whiptail(Debian/Ubuntu)或 dialog(openSUSE)渲染 TUI 向导,依次询问以下选择:

  1. Build arch(构建架构):x64(默认)/ arm64;
  2. WSA release type(WSA 发布通道):
    • retail(Stable 稳定版,默认)
    • release preview(Release Preview)
    • insider slow(Beta 通道)
    • insider fast(Dev 通道)
    • 脚本内部会将其映射为 retail / RP / WIS / WIF(见 run.sh 中的 RELEASE_TYPE_MAP);
  3. 是否 Root(Do you want to Root WSA?):
    • 选择"是"后继续选择 Root solution:magisk(默认)/ kernelsu;
  4. Magisk version(若选择 Magisk):stable(默认)/ beta / canary / debug(Canary 调试构建);
  5. 是否安装 GApps(Do you want to install GApps?):原文档明确——目前可选变体只有 MindTheGapps;
  6. 是否移除 Amazon Appstore(默认否);
  7. 是否压缩输出(Do you want to compress the output?):若选"是",再选择压缩格式 7z(默认)或 zip。

向导结束后,run.sh 会把上述选择拼装成命令行参数并转交 MagiskOnWSA/scripts/build.sh 执行(脚本末尾会打印 COMMAND_LINE=... 便于你核对选项)。

3.3 底层构建:build.sh 的完整参数表

若不使用交互向导,也可以直接调用 build.sh。从 MagiskOnWSA/scripts/build.sh 的 usage() 可得到全部参数:

参数 含义 可选值 默认值
--arch WSA 目标架构 x64, arm64 x64
--release-type WSA 发布通道(RP=Release Preview,WIS=Insider Slow,WIF=Insider Fast) retail, RP, WIS, WIF retail
--magisk-ver Magisk 版本 stable, beta, canary, debug, release stable
--root-sol Root 方案,none 表示不 Root magisk, kernelsu, none magisk
--compress-format 输出压缩格式 7z, zip, none none
--offline 离线构建(不下载) — 关
--magisk-custom 使用自定义 Magisk — 关
--skip-download-wsa 跳过下载 WSA 主体 — 关
--install-gapps 注入 GApps — 关
--remove-amazon 移除 Amazon Appstore — 关
--debug 开启 shell 调试输出(set -x) — 关
--help 显示帮助 — —

官方示例:

./build.sh --release-type RP --magisk-ver beta
./build.sh --arch arm64 --release-type WIF
./build.sh --release-type WIS
./build.sh --offline --magisk-custom
./build.sh --release-type WIF --magisk-custom --magisk-ver release

几个值得注意的源码级行为:

  • 参数白名单校验:check_list 函数会对 ARCH、RELEASE_TYPE、MAGISK_VER、ROOT_SOL、COMPRESS_FORMAT 逐一校验,非法值直接报错退出;
  • GApps 与 Root 方案的约束:当指定 --install-gapps 时,若 ROOT_SOL=none,会强制改为 magisk 并提示 "Force install Magisk since GApps needs it to mount the file";若 ROOT_SOL=kernelsu 则直接 abort("Unsupported combination: Install GApps and KernelSU")——即 GApps 注入依赖 Magisk 的挂载机制;
  • Android API 级别自适应:脚本默认 ANDROID_API=33(Android 13),但当检测到 WSA 主版本号小于 2211 时自动回退到 32(Android 12.1);
  • Magisk 最低版本要求:若 Magisk 版本号 < 26000 且非 stable 通道,会提示 "Please install Magisk 26.0+"。

3.4 构建产物与目录结构

首次运行构建脚本时耗时较长,完成后会在仓库根目录下生成两个新文件夹:

  • download/:存放下载的 WSA 固件、Magisk、GApps、VCLibs 等中间文件(对应 build.sh 中的 DOWNLOAD_DIR=../download);
  • output/:存放最终产物。

原文档说明:若在 run.sh 中选择了"压缩输出",则 output 目录下会出现一个压缩包,命名形如 WSA-with-magisk-stable-MindTheGapps_2207.40000.8.0_x64_Release-Nightly;否则是同名文件夹。具体名称取决于你在运行 ./run.sh 时做出的选择。

从源码看(MagiskOnWSA/scripts/build.sh 第 580-596 行),当前版本的命名规则为:

WSA_{WSA_VER}_{ARCH}_{WSA_REL}{-with-magisk-{版本名}({版本号})-{通道}}{-GApps-{Android版本}}{-NoAmazon}

例如带 Magisk stable、GApps、移除 Amazon 的产物形如 WSA_2311.40000.5.0_x64_Retail-with-magisk-26.1(26101)-stable-GApps-13.0-NoAmazon(旧版命名见原文档示例,命名会随版本迭代变化)。

3.5 构建背后的整合原理(源码级)

build.sh 的整合环节非常直观,值得展开:

  1. 下载阶段:调用 MagiskOnWSA/scripts/generateWSALinks.py(基于 StoreLib API 风格生成下载清单,仓库 Credits 中即引用了 StoreLib)、generateMagiskLink.py、generateGappsLink.py、generateKernelSULink.py 生成 download.list,随后用 aria2c 以 -x16 -s16 -j5 多线程下载并校验完整性;
  2. 解包阶段:extractWSA.py 解压 WSA 固件,extractMagisk.py 解压 Magisk;
  3. Magisk 集成:核心是一条 magiskboot cpio 命令(第 513-529 行),它把 initrd.img 中的 /init 改名为 /wsainit,加入 lspinit、magiskinit,并在 overlay.d/sbin 下注入 magisk64.xz/magisk32.xz/stub.xz、init.lsp.magisk.rc 与 post-fs-data.sh(这些文件即仓库 MagiskOnWSA/scripts/ 下的同名资源);
  4. KernelSU 集成:下载与内核版本匹配的 KernelSU 包,解压后把 bzImage(x64)或 Image(arm64)重命名为 kernel,替换 WSA Tools/kernel,原内核保留为 kernel_origin;
  5. GApps 集成:再次通过 magiskboot cpio 向 initrd.img 注入 overlay.d/gapps.rc 与 overlay.d/sbin/lsp_gapps.img;
  6. 移除 Amazon:删除 apex/ 下的 mado*.apex;
  7. 签名清理与脚本注入:删除 AppxSignature.p7x、AppxBlockMap.xml、<a href="https://link.gitcode.com/i/24484db798beff794a1ba35e34cd5d8e" target="_blank">Content_Types].xml、AppxMetadata 等签名/元数据文件,然后拷入 VCLibs、XAML 依赖、makepri.exe、priconfig.xml 以及 [installer 目录 下的 MakePri.ps1、Install.ps1、Run.bat,并生成 filelist.txt 供安装脚本校验文件完整性。

这也是为什么原文档 FAQ 会说"系统分区被 Hyper-V 以只读方式挂载、无法直接 remount"——所有系统级改动都必须发生在构建阶段(打进 initrd.img 与 overlay),而不是安装后。


4. 在 Windows 上安装

4.1 解压并运行 Run.bat

将 output 中的压缩包解压(或直接使用未压缩的产物文件夹),进入该文件夹后找到 Run.bat 并运行:

  • 如果之前已有 MagiskOnWSA 安装:脚本会自动卸载旧版,同时完整保留所有用户数据并安装新版,无需担心数据丢失;
  • 如果之前安装的是官方 WSA:应先卸载官方版。(若想保留数据,可在卸载前备份 %LOCALAPPDATA%\Packages\MicrosoftCorporationII.WindowsSubsystemForAndroid_8wekyb3d8bbwe\LocalCache\userdata.vhdx,安装完成后再恢复。)

Run.bat 的实现非常简单(见 MagiskOnWSA/installer/Run.bat):切换到自身所在目录,校验 Install.ps1 存在后,调用 powershell.exe -ExecutionPolicy Bypass -File .\Install.ps1 并立即退出。

4.2 Install.ps1 做了什么

真正的安装逻辑在 MagiskOnWSA/installer/Install.ps1,它对应原文档的"无人值守安装"与"自动开启开发者模式"特性:

  1. 自动提权:检测到非管理员权限时,以 RunAs 重新启动自身,全程无需手工操作;
  2. 合并语言包:若存在 MakePri.ps1 与 makepri.exe,先执行资源合并(失败仅警告"WSA Settings 将始终为英文",不中断安装);
  3. 开启开发者模式:写入注册表 HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock 的 AllowDevelopmentWithoutDevLicense=1;
  4. 启用虚拟化平台:检测 VirtualMachinePlatform 功能未启用时自动开启,并提示重启后重新运行脚本(这正是 FAQ 中"Virtualization is not enabled?"的答案来源——脚本会自动开启虚拟化,重启后重跑 Install.ps1 即可,若仍失败则需到 BIOS 中开启虚拟化);
  5. 依赖检查:解析 AppxManifest.xml 中的依赖声明,对版本不足的 VCLibs / XAML 依赖自动 Add-AppxPackage 安装(构建时已拷入同目录的 .appx);
  6. 旧版处理:检测已安装的 WSA,若非开发模式(官方版)则提示先卸载;MagiskOnWSA 自身安装则直接以注册方式覆盖更新;
  7. 注册安装:执行 Add-AppxPackage -Register .\AppxManifest.xml;若更新失败,会保留用户数据(Remove-AppxPackage -PreserveApplicationData)卸载旧版后重装;
  8. 安装完成:自动启动 Magisk 与 Play Store(wsa://com.topjohnwu.magisk 与 wsa://com.android.vending)。

4.3 弹窗消失、未装成功的兜底方案

原文档特别指出:如果弹窗没有请求管理员权限就消失、且 WSA 未安装成功,应手动以管理员身份运行 Install.ps1:

  1. 按 Win+x,选择 Windows Terminal (Admin);
  2. 输入 cd "{X:\path\to\your\extracted\folder}" 并回车(记得把 {X:\path\to\your\extracted\folder} 整体替换为实际路径,例如 cd "D:\wsa");
  3. 输入 PowerShell.exe -ExecutionPolicy Bypass -File .\Install.ps1 并回车;
  4. 脚本将运行并完成 WSA 安装;
  5. 若此方法仍无效,则说明你的 PC 不受 WSA 支持。

4.4 安装后使用

安装完成后 Magisk / Play Store 会被自动启动。原文档建议安装 LSPosed 模块:

  • 开启 Zygisk 后安装 LSPosed-Zygisk;
  • 或使用 Riru + LSPosed-Riru。

5. 日常更新与维护

原文档 FAQ 给出了三个高频运维问题的官方答案:

5.1 如何更新 WSA 到新版本?

  1. 更新构建脚本:

    git pull
    
  2. 重新运行构建脚本,用新产物替换上一次安装的内容后重新运行 Install.ps1。不用担心,用户数据会被保留。

(仓库文档区还有一份独立的 WSABuilds/Documentation/WSABuilds/Updating.md 可对照阅读。)

5.2 如何更新 Magisk 到新版本?

做法与更新 WSA 完全相同(重新构建 → 重新运行 Install.ps1)。

5.3 如何获取 WSA 的 logcat?

日志目录为:

%LOCALAPPDATA%\Packages\MicrosoftCorporationII.WindowsSubsystemForAndroid_8wekyb3d8bbwe\LocalState\diagnostics\logcat

6. FAQ 精讲(含源码依据)

以下逐条覆盖原文档 FAQ 中的其余问答,并结合仓库代码给出依据。

6.1 安装完的文件夹可以删除吗?

不可以。 该文件夹是 WSA 的安装来源(包含 Install.ps1、AppxManifest.xml、依赖 .appx 等),删除后你将无法再注册/更新安装,建议保留以备后续升级。

6.2 如何通过 Play Integrity(原 SafetyNet)?

原文档答案非常直接:和所有其他模拟器一样,没有办法通过。

6.3 如何将系统分区重新挂载为可读写?

WSA 中没有办法——系统分区被 Hyper-V 以只读方式挂载。可行的替代路径:

  • 通过制作 Magisk 模块来修改系统;
  • 或直接修改 system.img。

6.4 无法 adb connect localhost:58526,怎么办?

  1. 确保 WSA 中开发者模式已开启;
  2. 若问题依旧,到 WSA 设置页查看其 IP 地址,改用 adb connect ip:5555。

6.5 为什么 Magisk 在线模块仓库是空的?

Magisk 主动移除了在线模块仓库。你可以本地安装模块,或通过 adb 推送安装:

adb push module.zip /data/local/tmp
adb shell su -c magisk --install-module /data/local/tmp/module.zip

6.6 可以使用 Magisk v23.0 stable 或更低版本吗?

不可以。 Magisk 旧版本存在阻止其在 WSA 上运行的 bug,v24+ 才修复,因此必须使用 Magisk v24 或更高版本(构建脚本对非 stable 通道还额外要求 26.0+,见上文 3.3 节)。

6.7 如何去掉 Magisk(不想 Root)?

在 run.sh 的 Root solution 中选择 none 即可(命令行等价于 --root-sol none),构建出的 WSA 将不含任何 Root 方案。

6.8 如何安装自定义 GApps?

原文档指向独立教程 MagiskOnWSA/docs/Custom-GApps.md,其步骤为:

  1. 先不带 GApps 构建一次,让脚本下载所需文件:

    ./build.sh --gapps-brand none
    
  2. 放入自定义包并重命名:

    • OpenGApps:放入 download 目录,命名为 OpenGApps-{arch}-{variant}.zip(例如 OpenGApps-x64-pico.zip);
    • MindTheGapps:放入 download 目录,命名为 MindTheGapps-{arch}.zip(例如 MindTheGapps-x64.zip);
  3. 离线重新构建:

    ./build.sh --offline --gapps-brand {brand} --gapps-variant {variant}
    

(注:当前仓库版本中 GApps 品牌选择通过 --install-gapps 与 GApps 镜像注入实现,旧版教程中的 --gapps-brand/--gapps-variant 参数为历史版本用法,以你实际使用的构建脚本 ./build.sh --help 输出为准。)

6.9 到哪里下载 MindTheGapps?

  • MindTheGapps 官方提供 AndroidFileHost 下载与镜像站;
  • 注意:官方没有 x86_64 预编译包,需要自行构建(对应 vendor_gapps 仓库);
  • 也可以从面向 WSA 的 x86_64 预编译发布页下载 12.1 与 13 的现成包。

6.10 能否把数据从旧版本(如 2305)迁移到新版本?

可以。 Microsoft 在 2305 起把只读分区从 EROFS 改为只读 EXT4,但这只影响只读系统分区,不影响用户数据分区。若迁移后启动失败,请检查日志。

6.11 如何安装 KernelSU?

原文档指向独立教程 MagiskOnWSA/docs/KernelSU.md,其完整流程为:

  1. 安装 KernelSU Manager:下载 manager 构建产物(名为 manager 的 artifact),解压后得到形如 KernelSU_vx.x.x-xx-.....apk 的 APK,用 adb install <apkname>.apk 安装;
  2. 安装内核:下载与相同架构匹配的 WSA 预编译内核,解压后得到 bzImage,用其替换 WSA 目录下 Tools 文件夹中的 kernel;
  3. 重启 WSA 即可生效。

当然,更省事的方式是在 run.sh 的 Root solution 中选择 kernelsu,让构建脚本自动下载、匹配并替换内核(见 3.5 节)。


7. 注意事项与结语

7.1 项目状态与 Fork 提醒

  • EOL 声明:原文档顶部明确警告,Magisk on WSA 在 2025 年 3 月 5 日之后将不再可用,请据此规划你的使用场景;
  • 对 Fork 开发者的特别提醒:请不要使用 GitHub Actions 进行构建——大量 Fork 的 Actions 用量会计入上游仓库配额,可能导致上游仓库被 GitHub 封禁(历史上 MagiskOnWSA 上游即因此被处理过)。

7.2 致谢与许可

原文档 Credits 部分列出了本项目所依赖的关键组件:StoreLib(WSA 下载 API)、Magisk(Android 最著名的 Root 方案)、WSA-Kernel-SU 与 kernel-assisted-superuser(内核级 su,用于调试 Magisk 集成)等。仓库同时以 CC-BY-NC-ND 等许可证发布(见仓库根目录 LICENSE 与 LICENSE-CC-BY-NC-ND),构建脚本本身采用 AGPL-3.0(见各脚本文件头注释)。

7.3 进一步阅读

总结而言,MagiskOnWSA 提供了一条高度自动化的 WSA 定制链路:run.sh 交互选型 → build.sh 下载、解包、注入(Magisk/KernelSU/GApps)并产出可分发包 → Windows 端 Run.bat/Install.ps1 无人值守安装 → git pull + 重跑脚本实现保留数据的增量升级。理解这条链路上的每一环(initrd 注入、内核替换、注册表开发者模式、-PreserveApplicationData 数据保留机制),你就拥有了完全掌控 WSA 定制与维护的能力。

登录后查看全文
WSABuilds