在 Windows 10/11 上自建带 Google Apps 与 Magisk/KernelSU 的 WSA:MagiskOnWSA 完整构建与安装指南
在 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 |
除此之外:
- 使用 Python3 库
requests(见 MagiskOnWSA/scripts/requirements.txt,实际还包含packaging); - Python 版本要求 ≥ 3.7.2。
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 向导,依次询问以下选择:
- Build arch(构建架构):
x64(默认)/arm64; - 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);
- 是否 Root(Do you want to Root WSA?):
- 选择"是"后继续选择 Root solution:
magisk(默认)/kernelsu;
- 选择"是"后继续选择 Root solution:
- Magisk version(若选择 Magisk):
stable(默认)/beta/canary/debug(Canary 调试构建); - 是否安装 GApps(Do you want to install GApps?):原文档明确——目前可选变体只有 MindTheGapps;
- 是否移除 Amazon Appstore(默认否);
- 是否压缩输出(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 的整合环节非常直观,值得展开:
- 下载阶段:调用 MagiskOnWSA/scripts/generateWSALinks.py(基于 StoreLib API 风格生成下载清单,仓库 Credits 中即引用了 StoreLib)、
generateMagiskLink.py、generateGappsLink.py、generateKernelSULink.py生成download.list,随后用aria2c以-x16 -s16 -j5多线程下载并校验完整性; - 解包阶段:
extractWSA.py解压 WSA 固件,extractMagisk.py解压 Magisk; - 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/ 下的同名资源); - KernelSU 集成:下载与内核版本匹配的 KernelSU 包,解压后把
bzImage(x64)或Image(arm64)重命名为kernel,替换 WSATools/kernel,原内核保留为kernel_origin; - GApps 集成:再次通过
magiskboot cpio向initrd.img注入overlay.d/gapps.rc与overlay.d/sbin/lsp_gapps.img; - 移除 Amazon:删除
apex/下的mado*.apex; - 签名清理与脚本注入:删除
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,它对应原文档的"无人值守安装"与"自动开启开发者模式"特性:
- 自动提权:检测到非管理员权限时,以
RunAs重新启动自身,全程无需手工操作; - 合并语言包:若存在
MakePri.ps1与makepri.exe,先执行资源合并(失败仅警告"WSA Settings 将始终为英文",不中断安装); - 开启开发者模式:写入注册表
HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock的AllowDevelopmentWithoutDevLicense=1; - 启用虚拟化平台:检测
VirtualMachinePlatform功能未启用时自动开启,并提示重启后重新运行脚本(这正是 FAQ 中"Virtualization is not enabled?"的答案来源——脚本会自动开启虚拟化,重启后重跑Install.ps1即可,若仍失败则需到 BIOS 中开启虚拟化); - 依赖检查:解析
AppxManifest.xml中的依赖声明,对版本不足的 VCLibs / XAML 依赖自动Add-AppxPackage安装(构建时已拷入同目录的.appx); - 旧版处理:检测已安装的 WSA,若非开发模式(官方版)则提示先卸载;MagiskOnWSA 自身安装则直接以注册方式覆盖更新;
- 注册安装:执行
Add-AppxPackage -Register .\AppxManifest.xml;若更新失败,会保留用户数据(Remove-AppxPackage -PreserveApplicationData)卸载旧版后重装; - 安装完成:自动启动 Magisk 与 Play Store(
wsa://com.topjohnwu.magisk与wsa://com.android.vending)。
4.3 弹窗消失、未装成功的兜底方案
原文档特别指出:如果弹窗没有请求管理员权限就消失、且 WSA 未安装成功,应手动以管理员身份运行 Install.ps1:
- 按
Win+x,选择 Windows Terminal (Admin); - 输入
cd "{X:\path\to\your\extracted\folder}"并回车(记得把{X:\path\to\your\extracted\folder}整体替换为实际路径,例如cd "D:\wsa"); - 输入
PowerShell.exe -ExecutionPolicy Bypass -File .\Install.ps1并回车; - 脚本将运行并完成 WSA 安装;
- 若此方法仍无效,则说明你的 PC 不受 WSA 支持。
4.4 安装后使用
安装完成后 Magisk / Play Store 会被自动启动。原文档建议安装 LSPosed 模块:
- 开启 Zygisk 后安装 LSPosed-Zygisk;
- 或使用 Riru + LSPosed-Riru。
5. 日常更新与维护
原文档 FAQ 给出了三个高频运维问题的官方答案:
5.1 如何更新 WSA 到新版本?
-
更新构建脚本:
git pull -
重新运行构建脚本,用新产物替换上一次安装的内容后重新运行
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,怎么办?
- 确保 WSA 中开发者模式已开启;
- 若问题依旧,到 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,其步骤为:
-
先不带 GApps 构建一次,让脚本下载所需文件:
./build.sh --gapps-brand none -
放入自定义包并重命名:
- OpenGApps:放入
download目录,命名为OpenGApps-{arch}-{variant}.zip(例如OpenGApps-x64-pico.zip); - MindTheGapps:放入
download目录,命名为MindTheGapps-{arch}.zip(例如MindTheGapps-x64.zip);
- OpenGApps:放入
-
离线重新构建:
./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,其完整流程为:
- 安装 KernelSU Manager:下载 manager 构建产物(名为
manager的 artifact),解压后得到形如KernelSU_vx.x.x-xx-.....apk的 APK,用adb install <apkname>.apk安装; - 安装内核:下载与相同架构匹配的 WSA 预编译内核,解压后得到
bzImage,用其替换 WSA 目录下Tools文件夹中的kernel; - 重启 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/scripts/run.sh、MagiskOnWSA/scripts/build.sh
- 依赖安装:MagiskOnWSA/scripts/install_deps.sh
- Windows 安装脚本:MagiskOnWSA/installer/Install.ps1、MagiskOnWSA/installer/Run.bat
- 配套教程:自定义 GApps、KernelSU 安装、仓库文档区 WSABuilds/Documentation/WSABuilds/FAQ.md 与 Troubleshooting
总结而言,MagiskOnWSA 提供了一条高度自动化的 WSA 定制链路:run.sh 交互选型 → build.sh 下载、解包、注入(Magisk/KernelSU/GApps)并产出可分发包 → Windows 端 Run.bat/Install.ps1 无人值守安装 → git pull + 重跑脚本实现保留数据的增量升级。理解这条链路上的每一环(initrd 注入、内核替换、注册表开发者模式、-PreserveApplicationData 数据保留机制),你就拥有了完全掌控 WSA 定制与维护的能力。