Unity Switch 开发/打包/移植教程

*`本文仅作技术研究，因为合规原因，本文不提供任何法律敏感和版权相关的诸如SDK的文件`。

##前言和声明
-----
Unity Switch 开发打包移植相关的一系列教程，by 皓月狩魂(sin365) axibug.com
初版分享：

声明：
*文章和开源代码仓库，仅作技术研究，因为合规原因，不包含也提供任何法律敏感和版权相关的诸如SDK的文件。
*请自行获取，建议您使用官方授权的开发套件。
*谢绝讨论任何技术外的，诸如NS移植游戏开发的性质等无意义问题，我只是技术爱好者。相互尊重，相互学习。

文章：

1.Unity Switch 开发/打包/移植教程（包含如何重新Repack NSP,让捣鼓后的零售机运行）
http://note.axibug.com/blog/post/akiragatsu/UnitySwitchDev

2.Unity下Switch开发文件存储踩坑，以及解决方案范例 （Unity Switch下不能用System.IO,只能用nn.fs）
http://note.axibug.com/blog/post/akiragatsu/UnitySwitchDevForIO

3.Switch系统错误码，方便排查问题 （我AxiNSApi中也提供了转换打印，方便排查）
http://note.axibug.com/blog/post/akiragatsu/SwitchErrCode

4.Switch TitleID规则
http://note.axibug.com/blog/post/akiragatsu/SwitchTitleID

工具仓库：

1. AxibugNSPTools Unity用自动化打包工具（自动完成NSP打包并Repack）
https://github.com/sin365/AxibugNSPTools

2. AxiNSApi 已经封装好的Unity下Switch的用户访问，存储挂载，读写API，直接可用
https://github.com/sin365/AxiNSApi

再次申明，以上文章和仓库，不提供不包含任何敏感和版权文件，和授权开发者一样，仅讨论和演示上层使用经验交流。

祝君愉快，我爱Switch

— 皓月 2025.4.8
-----

## 1. 前置准备和概念了解

### **1.1 Nintendo SDK**

> 这个我不会提供任何文件，或者建议您使用任天堂官方授权的开发套件（笑）

准备好Nintendo SDK之后，配置如下环境变量：

NINTENDO_SDK_ROOT -> 你的路径\NintendoSDK
    NINTENDO_SDK_NEX_ROOT -> 你的路径\NintendoSDK-NEX
    NINTENDO_SDK_NPLN_ROOT -> 你的路径\NintendoSDK-NPLN
    NINTENDO_SDK_PIA_ROOT -> 你的路径\NintendoSDK-Pia6

### **1.2 安装dotnet SDK**

> 因为Nintendo SDK依赖donetsdk的，在Nintendo Sdk中也直接包含dotnet sdk的安装文件（是doNet6).您也可以自行安装

202607014补充：如果你的SDK版本是 NXAddon21.4+ 好像是doNet 10了，他们升级了doNet版本
请访问https://aka.ms/dotnet-core-applaunch?framework=Microsoft.NETCore.App&framework_version=10.0.0&arch=x64&rid=win-x64&os=win10安装，当然你输出nsp包下面，也会看得到这个xin'x

这个`建议一定要安装`，缺少这个也是Unity打包异常的原因之一，否则你难以查找原因。

### **1.3 Unity Switch Support**

> 同样，这个我不会提供任何文件，或者建议您使用任天堂官方授权的开发套件

准备和SDK对应版本的Unity Switch Support

安装Unity-AAAA版本
安装UnitySetup-Nintendo-Switch-Support-for-Editor-AAAA-SDK-BBBB-xxxxxxx.exe

> 占位符：
> AAAA是Unity版本号 
> BBBB是Nintendo SDK版本号

### **1.4 关于Unity License**

Nintendo Switch 并不需要特殊License或Unity Pro License，有一个License 就行

### **1.5 Unity 开发过程**

这个就和其他常见Unity游戏开发方式，忽略……

有一些，平台差异的踩坑，类似正常的PC，IOS，Android的unity开发过程中一样，不同平台开发，有一些特定的平台兼容问题，或必须的差异做法。
 Switch也一样，有一些不同的兼容情况需要处理，后续踩坑，会详细讲述。但这个是游戏本身内容开发方面的，**本文不在此赘述**。

### **1.6 打包为Switch平台**（另需要处理NAP的问题）

**重点，你直接输出的NSP，非开发机（即广大玩家手里的零售机）`是没办法运行的`**

因为Unity是针对官方授权开发而来，NSP是提交给Nintendo，由Nintendo审核签名后分发，才会是一个完整带NCA头文件信息的可安装NSP。

**并不是Android那样，输出.apk就万事大吉。**
 
 你大概率是没有Nintendo官方授权的开发套件的，按照官方套件，你打包出来的程序，只能在官方提供的开发机和测试机上运行，零售机是无法运行的。

要安装到零售机，切是已经折腾过的零售机（Hacked）
 而且先决条件是，你提供的NSP是没有NCA签名等基本信息的，解决这个之后，才有安装的可能。
 
 不解决的话，通过MTP之类的安装方式，都会报错，无法安装：
 > Invalid NCA Magic
 
### **1.7确保你准备就绪**

在此之前，请你先确保你Unity开发环境，能够选择Switch平台，成功Build出文件。

勾选 Create NSP File 是输入.nsp文件

不勾选 则是输出的文件夹形式的你的程序文件

注意，`Switch打包请一定勾选Explicit Null Checks`，即可IL2CPP是否添加空检查，避免崩溃
（按理说确保代码没有空判断遗漏和数组越界的情况下，就不需要对吧？但经我实测MonoBehavior很简单的常见代码都很容易出问题，可能是非官方Unity开发，可能内部会有某些异常的可能，勾上就好了）

#2 正片开始

若Unity并不能选择Switch平台，请检查你的Switch Support是否准备好并安装，
若打包的时候并不能找到SDK，请检查你的Nintendo SDK是否准备好，并配置好环境变量。
若IL2CPP问题，请按照Nintendo SDK解决。
还有先解决基本问题，比如你的代码，在Build上不要报错，或者Switch的一些宏之类的。
能输出文件，好，现在才可以往下看。

# 打包使其让零售机（已折腾的）可以安装和运行，有如下手段完成：

##2.1 准备构建NCA用于重构NSP的前置

为了让你的NSP包，零售机可以直接安装和运行，你需要做如下前置工作：

### **2.1.1 前置1.提取固件Key**

> 这是敏感操作，本文只是表示我自己的操作，对于操作的影响，本文不负任何责任。

你需要提取你SysNADA的key，这个固件密钥，是构建NCA等信息的关键。
请不要在网络上寻找key，即便找到也是不可用的。
请自行提取，方法范例：

下载 lockpick_rcm.bin，复制到TF卡\bootloader\payloads
（如果你的折腾机已经整合，可以不下载）

hekate界面，选择PayLoad（有些中文汉化了，叫有效载荷）
PayLoad中选择lockpick_rcm
进入lockpick_rcm之后，音量加减按钮是菜单上下选择，电源键是确定。
我们选择 Dump from SysNADA，很快会将你的key保存到SDK上。
退出Lockpick

在SDK中会有这三个文件，将他拷贝到你的电脑上。
sd:/switch/prod.keys
sd:/switch/title.keys
sd:/switch/dev.keys
> 你可以使用它，因为你合法拥有你的switch设备，但请仅自己提取使用，不要再网上分享或传播你的文件。避免一些法律风险，和避免您的设备敏感信息被泄露。

### **2.1.2 前置2.确定一个titleid**

自己定一个titleid，确保和现有所有已发行的游戏或者自制游戏的TitleID不一样，
可以去GBAtemp之类的论坛，查重。

并在Unity PlayerSetting中设置TitleID

如果你不知道如何选择TitleID，想详细了解其规则，请看我另一篇文章：http://note.axibug.com/blog/post/akiragatsu/SwitchTitleID

## 2.2 重新构建NSP包，并解决NCA问题

## 2.2.1 **重构NSP包方法①:**
### **使用 AxibugNSPTools 重新打包NSP（推荐）**

- 这工具由我编写提供，**工具内不提供也不包含任何Nintendo SDK版权相关的任何内容。**只是当你合法拥有Nintendo SDK时，本工具全自动化帮你调用。
 - **即本工具调用和操作的任何文件，都是您提供的合法文件，本工具不包含。给合法授权的开发者使用的。请遵守相关规定。**

本工具自动化调用您提供的合法Nintendo SDK获取包的详细信息，并基于您提供的合法prod.keys，生成NAC，帮助您调用hacpack，最终repack一个新的NSP，使其可以在已经被折腾的Switch上，成功安装NSP文件。

- **拷贝keys**

AxibugNSPTools 是编写给Unity的工具插件，AxibugNSPTools，到您的项目目录.

将您合法提取的prod.keys、title.keys、dev.keys拷贝到Assets/AxiProjectTools/AxiNSPack/switch_keys目录中。
(注：您的项目若有提交git等公开仓库时，请忽略Assets/AxiProjectTools/AxiNSPack/switch_keys/*.keys , 以免泄露由您设备提取的key）

* **若没有prod.keys,程序repack时会提示您**。

· 确保先前配置的Nintendo_SDK_ROOT环境变量

*若没有Nintendo_SDK_ROOT环境变量,程序repack时会提示您。

#### **功能1.** ：RepackNSP(仅重新构建NPS）

这个是把现有的Unity 输出的NSP（且无其他任何修改），重新构建，使其repack一个新的NSP，折腾后的零售Switch可以直接安装。

Unity Editor菜单上选择：Axibug移植工具/Switch/AxibugNSPTools/RepackNSP(仅重新构建NPS）

等待执行完毕

通过MTP等方式安装到Switch测试

#### **功能2.** ：Build With RepackNSP(打包NSP并重新构建NPS）

这个是自动调用Unity Build一个NSP之后，再自动调用RepackNSP，重新构建，使其repack一个新的NSP，折腾后的零售Switch可以直接安装。

Unity Editor菜单上选择：Axibug移植工具/Switch/AxibugNSPTools/Build With RepackNSP(打包NSP并重新构建NPS）

等待执行完毕

通过MTP等方式安装到Switch测试

## 2.2.2 **重构NSP包方法②:**
### **使用 Repack + hacpack 重新打包NSP**

创建C:\Users\<用户名>\.switch 目录
将prod.keys、title.keys、dev.keys拷贝到C:\Users\<用户名>\.switch目录中。
将hacpack目录添加到环境变量Path中,便于Repack调用

将unity勾选Create NSP File输出的.nsp包 重命名，保证包含TitleID，
如demo_01004b9000490000.nsp

启动Repack，拖放demo_01004b9000490000.nsp到控制台中，
敲回车，
等待执行完毕（很快）。
如果你的keys是正确可用的。
会得到一个demo_01004b9000490000_repacked.nsp的新NSP。

通过MTP等方式安装到Switch测试

# 至此 以上两种方式，您NSP已经可以在零售机（hacked）上安装和运行。

## 3 其他，开发踩坑介绍

## 3.1 Unity下Switch开发，文件系统

晴天霹雳，Switch的平台开发在Unity中，并不能使用C#自带的System.IO.File 或 System.IO.Directory 等任何方式访问文件，使用则立即崩溃。
文件存储需求，我已经踩坑，请访问我另一篇文章，有专门的解决方案：

《Unity下Switch开发文件存储踩坑，以及解决方案范例》[http://note.axibug.com/blog/post/akiragatsu/UnitySwitchDevForIO ](http://note.axibug.com/blog/post/akiragatsu/UnitySwitchDevForIO)

## 3.2 NMETA文件

NMETE 是Switch程序的详细文件

比如程序图标，嘿，没错，你在ProjectSettings中设置的图标是没用的，

需要在NMETA里设置，

如果你配置好了NintendoSDk的环境变量，可以呼出SDK里的Nintendo.Authoring.AuthoringEditor编辑文件。

在Project Settings > Player > Other Setting > NMETA里创建一个文件
![title](/api/file/getImage?fileId=67f33386452a51f668001120)
然后就可以编辑了
![title](/api/file/getImage?fileId=67f27d57452a51f6680010f5)
点击编辑后，Nintendo.Authoring.AuthoringEditor中可以设置Icon等内容
![title](/api/file/getImage?fileId=67f27d7c452a51f6680010f6)

## 3.3 待补充

Navigation

Recent Posts

Friend Links