Unity 7 升級準備:依序升版並預先改寫 C# 腳本,讓 2022 與 Unity 6 專案在 Unity 7 直接開啟

摘要

Unity 7 把腳本的執行環境從 Mono 換成 CoreCLR,並停用 Built-in Render Pipeline,因此從 Unity 2022 或 Unity 6 帶上來的專案,可能有腳本在舊版正常、到了 Unity 7 卻會出錯。只要依序升版,在 Unity 6 先改寫這些腳本並轉成 URP,升到 Unity 7 時就不必一次處理所有問題。

文章目錄

Unity 7 把腳本的執行環境從 Mono 換成 CoreCLR,也不再支援 Built-in Render Pipeline。我們從 Unity 2022 或 Unity 6 帶上來的專案,即使腳本在舊版能正常編譯與執行,到了 Unity 7 仍可能在進入 Play Mode 時沿用上一輪的 static 值、讀不到 Assembly 的檔案路徑,或因為前置處理符號不再定義而少編譯一段程式。這些寫法在 Unity 6 大多已有對應的新 API,只要依序升版,並在 Unity 6 先找出有問題的腳本改寫,升到 Unity 7 時就不必一次處理所有問題。

Unity 7 目前還在公開 alpha,最新版是 2026-11-19 釋出的 7000.0.0a20。Unity 在 Unite Seoul 2026 公布的時程是 12 月進入 Beta、2027 年第一季正式發行,而 Unity 7.0 手冊寫明升級指南會在 Beta 結束後發佈。以下內容以 7000.0.0a20 的手冊與 release notes 為準,正式版前仍可能調整。

判斷專案要改哪些地方

既有腳本到了 Unity 7 最常出錯或改變行為的情況有八種。表格最後一欄是最早能改寫的 Unity 版本,在這個版本改好的程式,到了 Unity 7 就不用再修改:

情況 在 Unity 7 的結果 處理方式 最早可改的版本
用 static 欄位或 static 事件保存遊戲狀態 關閉程式碼重新載入時,Play Mode 會沿用上一輪的值 用 RuntimeInitializeOnLoadMethod 或 [AutoStaticsCleanup] 重設 任何版本
用 AppDomain、Assembly.Location 或 Assembly.LoadFile GetAssemblies() 會列出正在卸載的 Assembly,Location 回傳空字串,LoadFile 載入的 Assembly 無法隨程式碼卸載 改用 CurrentAssemblies 與 GetLoadedAssemblyPath() 6.5
用 BinaryFormatter 存檔 不再支援 改用 JsonUtility 或 Unity 序列化 任何版本
用 Environment.Exit() 結束遊戲 丟出 PlatformNotSupportedException 改用 Application.Quit() 任何版本
用 #if DEVELOPMENT_BUILD 或 #if UNITY_64 符號不再定義,區塊裡的程式不會編譯 改用 UNITY_ENABLE_CHECKS、Debug.isDebugBuild 或 IntPtr.Size 6.6
2022 寫法的 FindObjectOfType、.rigidbody、GetInstanceID Unity 6.0 到 6.6 已陸續過時或移除,無法編譯 改用對應的新 API 6.0 到 6.6
專案用 Built-in Render Pipeline 畫面全黑,Surface Shader 停用 轉換成 URP 6.7
外掛 DLL 編譯的目標不是 .NET Standard 2.1 可能無法載入 改用以 .NET Standard 2.1 編譯的版本 任何版本

C# 語言版本在 7.0 alpha 仍是 C# 9.0。Unity 在 2026 年 10 月的 CoreCLR 進度更新也表示,7.0 alpha 仍以 C# 9 與 .NET Standard 2.1 為目標,但改用 .NET 10 與 C# 14 的時間還無法公布。舊的 Input Manager 在手冊標為 deprecated,但 Input.GetKey 這類寫法在 7.0 alpha 仍能使用,官方也還沒公布移除的版本。

規劃升級路線

Unity 的升級手冊建議一次只升級一個大版本,因此 2022 LTS 的專案要先升到 Unity 6,再升到 Unity 7,中間每個版本的升級指南也依發行順序閱讀。Unity 6 之內有兩個不能跳過的停留點:

  • 從 6.3 起已移除 URP 的 Compatibility Mode,因此還沒有啟用 Render Graph、仍在用這個模式的 URP 專案,要先在 6.0 到 6.2 改成 Render Graph,再往上升級。
  • 6.7 LTS 是最後一個支援 Mono 與 Built-in Render Pipeline 的版本,因此 Unity 在單一渲染管線的說明建議先在 6.7 把專案轉成 URP,再用 Unity 7 開啟。

升級路線:2022.3 LTS 先升到 6.0 LTS 處理過時 API 與 Render Graph,再到 6.3 LTS 關閉 Domain Reload 改寫 static 欄位,接著到 6.7 LTS 改用新 API、轉成 URP 並用 Project Auditor 檢查 CoreCLR,最後用 Unity 7 開啟升級路線:2022.3 LTS 先升到 6.0 LTS 處理過時 API 與 Render Graph,再到 6.3 LTS 關閉 Domain Reload 改寫 static 欄位,接著到 6.7 LTS 改用新 API、轉成 URP 並用 Project Auditor 檢查 CoreCLR,最後用 Unity 7 開啟

Unity 6.0 LTS 的支援已在 2026 年 10 月結束,6.3 LTS 支援到 2027 年 12 月,而 6.7 LTS 目前還在 Beta(6000.7.0b10)。6.1、6.2 與 6.4 到 6.6 是更新版,只支援到下一版推出,因此專案適合停留的是 6.3 LTS 與之後的 6.7 LTS,表格裡標 6.5 與 6.6 的改寫,要等升到 6.7 LTS 時一起做:

  • 停在 6.3 LTS 時:改寫 6.0 與 6.3 移除的 API,用 RuntimeInitializeOnLoadMethod 重設 static 欄位,換掉 BinaryFormatter 與 Environment.Exit(),並更換外掛 DLL。
  • 升到 6.7 LTS 後:改用 6.5 與 6.6 的新 API,替換 DEVELOPMENT_BUILD 與 UNITY_64,轉換成 URP,再用 Project Auditor 檢查 CoreCLR 相容性。

每次升級前先把變更都 Commit。升級時 Unity 的 API Updater 會詢問是否自動改寫過時的 API,如果自動改寫出錯,就能還原到改寫前的版本。

改寫 Unity 6 移除的舊 API

2022 的專案升到 Unity 6 後,最先遇到的是 Unity 6.0 到 6.6 陸續過時或移除的 API。標成過時的 API 會在 Console 出現警告,用到已移除的 API 時,腳本則會直接編譯失敗。腳本裡最常出現的是這幾個:

舊寫法 新寫法 版本
FindObjectOfType<T>() FindAnyObjectByType<T>() 6.0
FindObjectsOfType<T>() FindObjectsByType<T>() 6.0
[SerializeField] int Hp { get; set; } [field: SerializeField] int Hp { get; set; } 6.3
int id = go.GetInstanceID(); EntityId id = go.GetEntityId(); 6.5
gameObject.rigidbody GetComponent<Rigidbody>() 6.5
AddComponent("Rigidbody") AddComponent<Rigidbody>() 6.5
UxmlFactory、UxmlTraits [UxmlElement]、[UxmlAttribute] 6.6

gameObject.renderer、gameObject.collider、gameObject.audio 這類取得元件的捷徑屬性也在 6.5 一起移除,要全部改用 GetComponent<T>()。

改寫時有三個地方會影響執行結果:

  • FindObjectsByType 回傳的陣列不會排序,原本依賴 FindObjectsOfType 回傳順序的程式要自己排序(6.0 升級指南)。
  • EntityId 是 8 bytes,存成 int 或當成 Dictionary 的 int Key 時會遺失一半的資料,要把相關的程式整段改用 EntityId 型別(6.5 升級指南)。
  • 從 6.4 起,Object.Destroy 會對所有子孫物件的元件呼叫 OnDisable。如果專案自己補呼叫過深層子物件的 OnDisable,升級後會變成呼叫兩次,要把補呼叫的程式拿掉(6.4 升級指南)。

關閉 Domain Reload,找出要重設的 static 欄位

我們在 Unity 6 先關閉 Domain Reload,就能在升級前找出哪些腳本依賴每次進入 Play Mode 時重新載入程式碼。Unity 7 的 Editor 進入 Play Mode 時,預設只重新載入場景、不重新載入程式碼,這時 static 欄位、static 事件的訂閱者與非序列化欄位,都會保留上一輪 Play Mode 的值。根據 7.0 alpha 的 release notes,已有 Editor 設定檔的舊專案升級後會保留原本的設定,新專案則預設使用這個設定,因此舊專案只有改用這個設定時才會遇到 static 值殘留。官方也建議維持這個設定,因為可以縮短進入 Play Mode 的等待時間。

關閉的位置在「Edit > Project Settings > Editor」的「Enter Play Mode Settings」:

  • Unity 6:在「When entering Play Mode」選單選「Reload Scene only」。
  • Unity 2022:勾選「Enter Play Mode Options」,再取消勾選「Reload Domain」。

用 Unity 6.7 Beta 新建的專案,這個選單已經預設為「Reload Scene only」:

Project Settings 的 Editor 頁,「Enter Play Mode Settings」底下的「When entering Play Mode」選單為「Reload Scene only」

設定完成後連續按兩次 Play,如果分數、敵人清單或單例在第二次進入時仍是上一輪的值,保存這些資料的 static 欄位就要在進入 Play Mode 時重設。從 Unity 6.6 起,關閉 Domain Reload 的專案會自動啟用分析器,Console 會顯示 UAL0010、UAL0013 警告,標示還沒處理的 static 成員。

Unity 6.6 以上可以用 [AutoStaticsCleanup] 讓 Unity 在每次進入 Play Mode 時自動重設欄位。類別要宣告成 partial,Unity 才能替它產生重設的程式碼:

1using System.Collections.Generic;
2using Unity.Scripting.LifecycleManagement;
3using UnityEngine;
4
5public partial class EnemyRegistry : MonoBehaviour
6{
7    // 每次進入 Play Mode 都重新執行初始值,回到 0
8    [AutoStaticsCleanup]
9    static int s_DefeatedCount = 0;
10
11    // readonly 的集合會被呼叫 Clear(),清單變回空的
12    [AutoStaticsCleanup]
13    static readonly List<EnemyRegistry> s_Enemies = new();
14
15    void OnEnable() => s_Enemies.Add(this);
16    void OnDisable() => s_Enemies.Remove(this);
17}

官方說明列出三個限制:類別少了 partial 時分析器會回報 UAL0012,類別有明確寫出的 static 建構子時回報 UAL0014,而 static 建構子本身在每次進入 Play Mode 時不會重新執行。像 ID 產生器這類要跨 Play Mode 保持唯一的計數器,則要改加 [NoAutoStaticsCleanup] 保留原本的值。

Unity 6.3 LTS 還沒有這兩個屬性,專案停在 6.3 LTS 時,就用 RuntimeInitializeOnLoadMethod 在進入 Play Mode 時自行重設欄位,這個寫法在 Unity 7 仍然有效:

1using UnityEngine;
2
3public class ScoreBoard : MonoBehaviour
4{
5    static int s_TotalScore;
6
7    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
8    static void ResetStatics()
9    {
10        s_TotalScore = 0;
11    }
12}

升到 6.5 以上後,也可以改用 UnityEngine 命名空間的 [OnEnteringPlayMode] 與 [OnExitingPlayMode] 屬性,取代訂閱 EditorApplication.playModeStateChanged。這兩個屬性在 Player 也會執行,不用再用 #if UNITY_EDITOR 把程式包起來(生命週期 API 對照)。

改寫 CoreCLR 不相容的 .NET API

專案裡如果有讀取 Assembly 清單、檔案路徑或動態載入 Assembly 的程式,到了 Unity 7 就要把這些 .NET API 改用 Unity 提供的版本。Unity 7 的 Editor,以及 Windows、macOS、Linux 的 Player 都改用 CoreCLR 執行腳本,IL2CPP 的平台則改用 .NET 10 的基礎類別庫。Unity 會從記憶體載入 Assembly,並在程式碼重新載入時卸載。不相容 API 對照表列出的替代寫法如下:

舊寫法 新寫法 命名空間
AppDomain.CurrentDomain.GetAssemblies() CurrentAssemblies.GetLoadedAssemblies() UnityEngine.Assemblies
AppDomain.CurrentDomain.DomainUnload [OnAssemblyUnloading] Unity.Scripting.LifecycleManagement
assembly.Location assembly.GetLoadedAssemblyPath() UnityEngine
Assembly.LoadFile(path) CurrentAssemblies.LoadFromPath(path) UnityEngine.Assemblies
BinaryFormatter JsonUtility 或 Unity 序列化 UnityEngine

CurrentAssemblies 與 GetLoadedAssemblyPath() 從 Unity 6.5 起才提供,專案還在 6.3 LTS 時先保留原本的寫法,升到 6.7 LTS 再一起換掉。BinaryFormatter 則不必等到特定版本,現在就可以把存檔改成 JsonUtility。舊格式的存檔要另外寫一段轉換程式,因此遊戲越早改用新的存檔格式,玩家手上需要轉換的舊存檔就越少。

另外兩個執行期的差異不會出現在編譯錯誤裡:

  • 根據 7.0 alpha 的 release notes,Environment.Exit() 在 CoreCLR 會丟出 PlatformNotSupportedException,結束遊戲要改用 Application.Quit()。
  • Unity 的 CoreCLR 升級指南指出,CoreCLR 預設只註冊 ASCII 與 Unicode 系列的編碼,因此用 Encoding.GetEncoding(950) 讀取 Big5 檔案前,要先呼叫 Encoding.RegisterProvider(CodePagesEncodingProvider.Instance) 註冊字碼頁編碼。

Plugins 資料夾裡預先編譯好的 DLL 也要檢查編譯目標。.NET 相容性表寫明 CoreCLR 只支援 .NET Standard 的 API 相容等級,以 .NET Core 編譯的 DLL 不支援,以 .NET Framework 編譯的 DLL 只有部分支援,NuGet 套件則要選 .NET Standard 2.1 的版本放進專案。

替換 DEVELOPMENT_BUILD 與 UNITY_64

7.0 alpha 建置任何平台時都不再定義 DEVELOPMENT_BUILD 與 UNITY_64,因此寫在 #if DEVELOPMENT_BUILD 裡的除錯程式不會出現在 Development Build,也不會出現任何錯誤訊息。從 Unity 6.6 起,使用這兩個符號會出現 UAC0009 與 UAC0008 警告,6.6 升級指南依程式的用途給了三種改法:

  • 安全檢查與斷言:改成 #if UNITY_ENABLE_CHECKS。Editor 一定會定義這個符號,因此原本的 #if UNITY_EDITOR || DEVELOPMENT_BUILD 可以直接改成 #if UNITY_ENABLE_CHECKS。
  • Profiler 標記與診斷 Log:改成 #if UNITY_INCLUDE_INSTRUMENTATION,或放在 [Conditional("UNITY_INCLUDE_INSTRUMENTATION")]。
  • 只想在 Development Build 執行、不能進正式版的程式,例如會印出 Token 的 Log:改用執行期的 Debug.isDebugBuild 判斷,因為正式版也可能用含檢查的設定建置。

兩個新符號由「Edit > Project Settings > Player > Other Settings」的「Managed Code Variant」決定。預設的 Release 不會定義任何診斷符號,因此開發時如果要執行除錯程式,就在要建置 Development Build 的平台改選 Checked 或 Debug。只在 Development Build 執行的 Log,改寫前後如下:

1// 改寫前
2#if UNITY_EDITOR || DEVELOPMENT_BUILD
3    Debug.LogError($"Rejecting connection: {payload}");
4#endif
5
6// 改寫後
7if (Debug.isDebugBuild)
8    Debug.LogError($"Rejecting connection: {payload}");

Unity 在編譯腳本時還無法得知執行檔是幾位元,因此原本用 UNITY_64 判斷的程式,要改成在執行期判斷 IntPtr.Size,這個值為 8 時代表 64 位元,為 4 時代表 32 位元。

把 Built-in Render Pipeline 專案轉成 URP

根據 7000.0.0a20 的 release notes,用 7.0 alpha 開啟 Built-in Render Pipeline 的專案時,畫面會全部渲染成黑色,主視窗會出現錯誤橫幅,Surface Shader 也已停用。腳本裡用 Camera.AddCommandBuffer 與 CameraEvent 插入渲染指令的寫法也已標為過時,在 URP 下不會執行,要改寫成 URP 的 Renderer Feature。

專案升到 6.7 後再轉換成 URP。Unity 6.7 的 Project Auditor 可以從「Window > Analysis > Project Auditor」開啟,Home 頁的「Migrate to URP」分頁會列出不相容的 Shader、材質與腳本,再交給 Render Pipeline Converter 轉換材質。完整步驟可以參考官方的 Built-in 轉 URP 流程。

用 Project Auditor 檢查整個專案

前面幾節的問題分散在各個腳本裡,專案升到 6.7 後,就可以用 Project Auditor 一次列出。除了上一節的「Migrate to URP」,Home 頁還有「Upgrade」與「Migrate to CoreCLR」兩個分頁,用法在 Project Auditor 的升級與遷移頁。「Upgrade」在選定目標版本後會列出專案用到的過時 API,「Migrate to CoreCLR」則會列出在 CoreCLR 無法載入或執行的程式碼與 DLL。

使用「Migrate to CoreCLR」前要先安裝 Project Auditor Rules 套件。選好平台後按下「Start Analysis」,結果頁會顯示目前與目標的執行環境、各嚴重程度的問題數,以及最常見的十個問題:

Migrate to CoreCLR 的分析結果,執行環境從 Mono 換成 CoreCLR (.NET 10),共 8 個問題,Top Ten Issues 列出 BinaryFormatter usage、Lifecycle API issue 與 AppDomain 等項目

展開問題後,「Details」會說明原因,「Recommendation」會寫出建議的改法,選「More Details」則會列出每一處用到這個寫法的程式碼。可以自動修正的問題還會多一個修正按鈕:

展開 BinaryFormatter usage 與 Lifecycle API issue,Recommendation 分別建議改用 JsonUtility 等序列化工具,以及替 static 成員加上 AutoStaticsCleanup

分析結果不會列出前面幾節提到的所有寫法。在本文的測試專案裡,Assembly.Location、Assembly.LoadFile、Environment.Exit() 與 #if DEVELOPMENT_BUILD 都沒有出現在結果裡,因此這幾種寫法仍要自己搜尋程式碼。修改完成後回到 Home 再分析一次,確認沒有剩下的問題。

實測紀錄

截圖與分析結果來自 Unity 6.7 Beta(6000.7.0b10)新建的專案。專案安裝 Project Auditor Rules 3.2.0,再放入三個腳本,分別用 BinaryFormatter 存檔、用 AppDomain 與 Assembly 的 API 載入 Assembly,以及用 static 欄位、static 事件、#if DEVELOPMENT_BUILD、#if UNITY_64 與 Environment.Exit() 管理遊戲狀態。「Migrate to CoreCLR」在 Windows 平台、Player 程式碼的分析結果如下:

寫法 分析結果
BinaryFormatter 的序列化與反序列化 列出,嚴重程度為 Major
static 欄位與 static 事件 列出,歸在「Lifecycle API issue」
AppDomain.CurrentDomain.GetAssemblies() 列出
AppDomain.CurrentDomain.DomainUnload 列出
Assembly.Location、Assembly.LoadFile 沒有列出
Environment.Exit() 沒有列出
#if DEVELOPMENT_BUILD、#if UNITY_64 沒有列出
依賴套件 com.unity.ext.nunit 附帶的 nunit.framework.dll 列出,歸在「Precompiled assembly not built for .NET Standard」

總結

升級到 Unity 7 前,先在 Unity 6 依序升版,關閉 Domain Reload 並重設 static 欄位,再把 CoreCLR 不相容的 .NET API、舊的前置處理符號與 Built-in Render Pipeline 換掉。最後用 Project Auditor 的「Migrate to CoreCLR」分析,並自己搜尋它沒有列出的寫法,確認沒有剩下的問題再升到 Unity 7。

延伸閱讀

Ted Liou

Ted Liou

現役軟體工程師,分享 Unity 與 AI 的技術開發經驗。

留言