Unity CLI 建置教學:用指令產出 Windows 版遊戲,並以 Project Auditor 檢查專案問題

摘要

透過 Unity CLI 的建置指令,我們不用打開 Unity 編輯器、也不用寫 C# 建置程式,就能把專案建置成 Windows 版。指令會用結束碼回報成功或失敗,因此能直接寫進建置腳本。Unity CLI 也能讓 Project Auditor 掃描程式、資源與專案設定,把問題整理成一份 CSV 報告。

文章目錄

每次要給人試玩,都得打開 Unity、在「Build Profiles」切換平台、按下「Build」再等它跑完。Unity CLI 的建置指令能把這些步驟縮成一行,建置 Windows 版時也不用寫任何 C# 建置程式。指令結束時會用結束碼回報成功或失敗,因此也能寫進腳本,之後執行一次腳本就能產出新版本。

建置成功不代表專案沒有問題。建置失敗時,建置記錄會指出錯在哪一行,但會拖慢效能或妨礙升級的寫法與設定不會讓建置失敗,Console 通常也不會出現警告。這類問題要交給 Unity 編輯器內建的 Project Auditor,它不必執行遊戲,就能依規則掃過程式、資源與專案設定:

建置失敗時看建置記錄找出錯誤的位置,建置成功後由 Project Auditor 掃描,列出影響 CPU、記憶體、載入時間與升級遷移的問題

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,就代表建置完成:

終端機執行 unity build 後顯示建置成功(StandaloneWindows64)與記錄檔位置,$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 會列出錯誤所在的檔案與行數,最後顯示建置失敗與記錄檔位置:

unity build 建置失敗時列出 CS0029 編譯錯誤的檔案與行數,最後一行顯示「建置失敗(結束碼 1)」與記錄檔位置

畫面最後一行的「結束碼 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 個:

Project Auditor 的 Summary 頁,Code 有 20 個問題、Assets 有 6 個、Game Objects 為 0

問題排除

症狀 處理方式
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 個屬於自己的專案。

延伸閱讀

Ted Liou

Ted Liou

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

留言