文章目錄

每次要給人試玩,都得打開 Unity、在「Build Profiles」切換平台、按下「Build」再等它跑完。Unity CLI 的建置指令能把這些步驟縮成一行,建置 Windows 版時也不用寫任何 C# 建置程式。指令結束時會用結束碼回報成功或失敗,因此也能寫進腳本,之後執行一次腳本就能產出新版本。
建置成功不代表專案沒有問題。建置失敗時,建置記錄會指出錯在哪一行,但會拖慢效能或妨礙升級的寫法與設定不會讓建置失敗,Console 通常也不會出現警告。這類問題要交給 Unity 編輯器內建的 Project Auditor,它不必執行遊戲,就能依規則掃過程式、資源與專案設定:
Unity CLI 能替專案裝好 Project Auditor 需要的規則套件,再把掃描結果存成 CSV,存好後就能用 PowerShell 篩出自己專案的問題。
以下在 Windows 11 實測,使用 Unity CLI 1.0.1 與 Unity 6000.6.9f1,專案是用 unity projects create 建立的 3D(URP)範本。開始前要先照〈Unity CLI 安裝教學〉裝好 Unity CLI 與專案使用的編輯器版本,並啟用授權。專案要放在 NTFS 格式的磁碟,因為 ReFS 格式的開發磁碟機會讓 Unity CLI 連不上開著的編輯器。
建置專案
Windows 版的平台名稱是 StandaloneWindows64。unity build --list-targets 會列出各平台與建置條件,這個平台標示為「零程式碼」,只要指定輸出位置就能建置。在專案資料夾執行下面的指令,其中 --target 是建置的平台,-o 是輸出的執行檔位置。加上 --no-tail 後,終端機只會顯示結果,不會把編輯器的完整記錄也印出來:
1unity build --target StandaloneWindows64 -o Builds\Windows\Game.exe --no-tail
指令結束後,可以用 $LASTEXITCODE 查看結束碼,它是 PowerShell 保存上一個指令結束碼的變數。如果畫面出現「建置成功」,$LASTEXITCODE 也是 0,就代表建置完成:

編輯器沒開時,成功的畫面上方會出現一行 LicensingClient has failed validation; ignoring。這是背景啟動的編輯器寫進記錄的訊息,只要畫面出現「建置成功」就不用理會,我實際開啟建置出來的遊戲也能正常執行。
建置完成後,Builds\Windows 裡除了 Game.exe 與 Game_Data 這些遊戲檔案,還有兩個 Unity CLI 與 Unity 留下的項目:
| 項目 | 內容 |
|---|---|
Game.provenance.json |
這次建置的紀錄:結果、結束碼、編輯器版本與專案裡每個套件的版本 |
Game_BackUpThisFolder_ButDontShipItWithYourGame |
除錯用的資料,資料夾名稱寫明發佈時不要附上 |
這兩項不影響遊戲執行,給人試玩時只要把其他檔案一起壓縮就可以。
編輯器開著與沒開時的差異
unity build 在編輯器開著或沒開時都用同一行指令,兩種情況的建置方式與實測時間如下:
| 編輯器狀態 | 建置方式 | 實測時間 |
|---|---|---|
| 沒有開啟這個專案 | 在背景啟動編輯器建置,建置完成後自動關閉 | 第一次 1 分 53 秒,之後 17 秒 |
| 已經開啟這個專案 | 直接在開著的編輯器裡建置,並把作用中的平台切換成建置目標 | 7 秒 |
第一次在背景建置時,編輯器會先匯入專案的資源,因此花的時間比較久,之後再建置就會沿用匯入的結果。如果建置時編輯器開著,之後要切回原本的平台,就到「Build Profiles」切換。
處理建置失敗
專案的程式有編譯錯誤時,unity build 會列出錯誤所在的檔案與行數,最後顯示建置失敗與記錄檔位置:

畫面最後一行的「結束碼 1」是編輯器本身的結束碼,unity build 回傳給 PowerShell 的 $LASTEXITCODE 則是 6。完整的建置記錄存在專案的 Logs 資料夾,檔名是 build-平台-時間戳記.log,建置失敗時要從這裡找原因。修好錯誤後重新執行同一行指令,當結束碼回到 0,就代表建置成功。
同樣的專案如果用 unity open . --until-ready 開啟,編輯器會停在「Enter Safe Mode?」的對話框,指令則以結束碼 6 結束,訊息會說明專案有編譯錯誤。這時編輯器還沒載入專案,也無法接受指令,因此 unity close . 無法關閉編輯器。加上 --force 就能結束編輯器,也不會丟失未存檔的變更:
1unity close . --force
寫成建置腳本
把建置指令寫成 PowerShell 腳本,之後只要執行腳本就能建置,並依結束碼顯示結果。在專案資料夾建立 build.ps1:
1param(
2 [string]$Project = ".",
3 [string]$Target = "StandaloneWindows64",
4 [string]$Output = "Builds\Windows\Game.exe"
5)
6
7unity build $Project --target $Target -o $Output --no-tail
8$code = $LASTEXITCODE
9
10if ($code -eq 0) {
11 Write-Host "建置成功:$Output"
12} else {
13 Write-Host "建置失敗,結束碼 $code,完整記錄在專案的 Logs 資料夾"
14}
15exit $code
在專案資料夾執行 .\build.ps1,建置成功時最後一行會顯示「建置成功:Builds\Windows\Game.exe」。腳本會把 unity build 的結束碼原樣傳出去,因此其他腳本或排程呼叫 build.ps1 時,也能用 $LASTEXITCODE 判斷成功或失敗。如果遇到 0 與 6 以外的結束碼,可以執行 unity --help,說明的最後面會列出每個結束碼。如果 PowerShell 回報已停用指令碼執行,處理方式見〈PowerShell 執行原則〉。
檢查專案問題
Project Auditor 只在編輯器開著專案時才能掃描,因此先用 unity open 開啟專案,等編輯器載入完成:
1unity open . --until-ready
開啟成功時,指令會直接結束,不會顯示錯誤訊息。如果要確認編輯器已經載入完成,可以執行 unity status,state 欄顯示 ready 就代表可以繼續。
安裝規則套件
編輯器載入完成後執行 unity projects audit。這個指令會替專案安裝 Project Auditor 的規則套件,再打開 Project Auditor 視窗。--workflow 只會決定視窗要停在哪一頁,和 CSV 報告無關,這裡用的是 upgrade:
1unity projects audit --workflow upgrade
輸出會顯示安裝了 com.unity.project-auditor-rules@3.2.0,這個套件會寫進專案的 Packages\manifest.json。如果專案有用版本控制,manifest.json 與 packages-lock.json 會出現這筆變更,這時我們可以選擇一起 Commit 這筆變更,或是把這兩個檔案還原。
把結果存成 CSV
規則套件裝好後,我們就能用 Unity CLI 讓編輯器掃描專案,並把結果直接存成 CSV。unity command 會請開著的編輯器執行功能,用法見〈讓 Claude Code 操作 Unity 編輯器〉。執行 run_audit 開始掃描:
1unity command diagnostics run_audit --output-path Reports/audit.csv
指令會立刻結束並顯示 status: scanning,掃描則在編輯器的背景進行。接著用 audit_status 查詢進度,當狀態變成 completed,就代表報告已經寫好。範本專案從開始掃描到顯示 completed 花了 3 分 54 秒:
1unity command diagnostics audit_status
掃描完成時,輸出如下:
1status: completed
2scanId: 461fafe6
3csvPath: C:\UnityProjects\BuildDemo\Reports\audit.csv
4issueCount: 40
CSV 每一列是一個問題,欄位有 Category、Severity、Areas、Description、RelativePath、Line、DescriptorId 與 Recommendation。範本專案的 40 個問題裡,有 14 個來自 Unity 自己的套件,路徑在 Packages 或 Library 底下,不是我們能修改的檔案。用 PowerShell 排除這些路徑後,就只剩自己專案的問題:
1Import-Csv Reports\audit.csv |
2 Where-Object RelativePath -notmatch '^(Packages|Library)/' |
3 Select-Object Category, Severity, Description
範本專案篩完後列出 26 筆,其中有 14 個程式問題與 12 個專案設定問題。排除前的 40 筆裡,各類問題的例子如下,Areas 欄是問題影響的面向,CSV 的 Recommendation 欄則寫了修改方式:
| 類別 | 範本專案列出的問題 | Areas |
|---|---|---|
| 程式 | 每次呼叫都會配置新的 VisualElement、Label 物件,也會呼叫 Debug.LogWarning |
Memory、CPU |
| 程式 | 預先編譯的 DLL 以 .NET Framework 為目標 | MigrationToCoreCLR |
| 資源 | Shader 引用了內建渲染管線的 UnityCG.cginc |
MigrationToURP |
| 專案設定 | 沒有指定 URP Asset、品質等級的 Mipmap Streaming 沒有開啟 | Quality、Memory |
| 專案設定 | Splash Screen 已開啟、Fixed Timestep 維持預設值、物理的 Layer Collision Matrix 全部勾選 | LoadTime、CPU |
| 專案設定 | com.unity.ide.visualstudio 等套件有新版本可以更新 |
Upgrade |
在 Project Auditor 視窗按「Start Analysis」時,編輯器也會再分析一次專案,分析完成後,同一個位置的按鈕會變成「New Analysis」。Summary 頁的各分類問題數和排除路徑前的 CSV 相同,Code 有 20 個、Assets 有 6 個、Project Settings 有 14 個:

問題排除
| 症狀 | 處理方式 |
|---|---|
unity build 回報「必須提供 –output」 |
建置 Windows 版時要加上 -o 指定執行檔的位置 |
unity build 回報目標「沒有內建的命令列建置」 |
這個平台需要 Unity 6 的建置設定檔(--profile)或 C# 建置程式(--execute-method) |
audit_status 顯示 unavailable 與「Install the Project Auditor Rules package」 |
先執行一次 unity projects audit 安裝規則套件 |
編輯器開著,unity command 一直找不到編輯器 |
專案放在 ReFS 格式的開發磁碟機時會發生這個問題,處理方式見〈讓 Claude Code 操作 Unity 編輯器〉的問題排除 |
總結
只要用 Unity CLI 指定平台與輸出位置,就能建置 Windows 版並用結束碼判斷結果,也能用 Project Auditor 把專案問題存成 CSV。範本專案在背景建置第一次花了 1 分 53 秒,之後再建置是 17 秒,編輯器開著時則是 7 秒。Project Auditor 掃出的 40 個問題裡,有 26 個屬於自己的專案。


