文章目錄

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 這類寫法在 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 開啟。
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,用
Runtime重設 static 欄位,換掉Initialize On Load Method Binary與Formatter Environment,並更換外掛 DLL。.Exit() - 升到 6.7 LTS 後:改用 6.5 與 6.6 的新 API,替換
DEVELOPMENT與_BUILD UNITY,轉換成 URP,再用 Project Auditor 檢查 CoreCLR 相容性。_64
每次升級前先把變更都 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 |
game、game、game 這類取得元件的捷徑屬性也在 6.5 一起移除,要全部改用 Get。
改寫時有三個地方會影響執行結果:
Find回傳的陣列不會排序,原本依賴Objects By Type Find回傳順序的程式要自己排序(6.0 升級指南)。Objects Of Type Entity是 8 bytes,存成Id int或當成 Dictionary 的 int Key 時會遺失一半的資料,要把相關的程式整段改用Entity型別(6.5 升級指南)。Id - 從 6.4 起,
Object會對所有子孫物件的元件呼叫.Destroy On。如果專案自己補呼叫過深層子物件的Disable On,升級後會變成呼叫兩次,要把補呼叫的程式拿掉(6.4 升級指南)。Disable
關閉 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」:

設定完成後連續按兩次 Play,如果分數、敵人清單或單例在第二次進入時仍是上一輪的值,保存這些資料的 static 欄位就要在進入 Play Mode 時重設。從 Unity 6.6 起,關閉 Domain Reload 的專案會自動啟用分析器,Console 會顯示 UAL0010、UAL0013 警告,標示還沒處理的 static 成員。
Unity 6.6 以上可以用 [Auto 讓 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 保持唯一的計數器,則要改加 [No 保留原本的值。
Unity 6.3 LTS 還沒有這兩個屬性,專案停在 6.3 LTS 時,就用 Runtime 在進入 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 以上後,也可以改用 Unity 命名空間的 [On 與 [On 屬性,取代訂閱 Editor。這兩個屬性在 Player 也會執行,不用再用 #if UNITY 把程式包起來(生命週期 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 |
Current 與 Get 從 Unity 6.5 起才提供,專案還在 6.3 LTS 時先保留原本的寫法,升到 6.7 LTS 再一起換掉。Binary 則不必等到特定版本,現在就可以把存檔改成 Json。舊格式的存檔要另外寫一段轉換程式,因此遊戲越早改用新的存檔格式,玩家手上需要轉換的舊存檔就越少。
另外兩個執行期的差異不會出現在編譯錯誤裡:
- 根據 7.0 alpha 的 release notes,
Environment在 CoreCLR 會丟出.Exit() Platform,結束遊戲要改用Not Supported Exception Application。.Quit() - Unity 的 CoreCLR 升級指南指出,CoreCLR 預設只註冊 ASCII 與 Unicode 系列的編碼,因此用
Encoding讀取 Big5 檔案前,要先呼叫.Get Encoding(950) Encoding註冊字碼頁編碼。.Register Provider(Code Pages Encoding Provider .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 與 UNITY,因此寫在 #if DEVELOPMENT 裡的除錯程式不會出現在 Development Build,也不會出現任何錯誤訊息。從 Unity 6.6 起,使用這兩個符號會出現 UAC0009 與 UAC0008 警告,6.6 升級指南依程式的用途給了三種改法:
- 安全檢查與斷言:改成
#if UNITY。Editor 一定會定義這個符號,因此原本的_ENABLE _CHECKS #if UNITY可以直接改成_EDITOR || DEVELOPMENT _BUILD #if UNITY。_ENABLE _CHECKS - Profiler 標記與診斷 Log:改成
#if UNITY,或放在_INCLUDE _INSTRUMENTATION [Conditional("UNITY。_INCLUDE _INSTRUMENTATION")] - 只想在 Development Build 執行、不能進正式版的程式,例如會印出 Token 的 Log:改用執行期的
Debug判斷,因為正式版也可能用含檢查的設定建置。.is Debug Build
兩個新符號由「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 判斷的程式,要改成在執行期判斷 Int,這個值為 8 時代表 64 位元,為 4 時代表 32 位元。
把 Built-in Render Pipeline 專案轉成 URP
根據 7000.0.0a20 的 release notes,用 7.0 alpha 開啟 Built-in Render Pipeline 的專案時,畫面會全部渲染成黑色,主視窗會出現錯誤橫幅,Surface Shader 也已停用。腳本裡用 Camera 與 Camera 插入渲染指令的寫法也已標為過時,在 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」,結果頁會顯示目前與目標的執行環境、各嚴重程度的問題數,以及最常見的十個問題:

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

分析結果不會列出前面幾節提到的所有寫法。在本文的測試專案裡,Assembly、Assembly、Environment 與 #if DEVELOPMENT 都沒有出現在結果裡,因此這幾種寫法仍要自己搜尋程式碼。修改完成後回到 Home 再分析一次,確認沒有剩下的問題。
實測紀錄
截圖與分析結果來自 Unity 6.7 Beta(6000.7.0b10)新建的專案。專案安裝 Project Auditor Rules 3.2.0,再放入三個腳本,分別用 Binary 存檔、用 App 與 Assembly 的 API 載入 Assembly,以及用 static 欄位、static 事件、#if DEVELOPMENT、#if UNITY 與 Environment 管理遊戲狀態。「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。

