Unity CLIで最小プロジェクトとEdit Modeテストを検証する

概要

Unity CLIを導入するだけでは、実際の開発フローに使えるかは分かりません。この記事では、Windows 11で公式Unity CLIを導入し、既存のUnity Editorを認識させ、空に近いプロジェクトの作成、C#のコンパイル、Edit Modeテスト一件の実行までを確認します。

検証範囲は、CLIの導入可否を判断できる最小限に限定します。Unity Pipeline package、MCP、シーンの自動編集、Play Modeテスト、プレイヤービルド、CI環境は扱いません。

結論

• Unity CLI 1.0.0-beta.5から、Unity Hubで導入済みのEditorを認識できました。
• Unity Editor 6000.5.1f1を追加で再インストールせずに利用できました。
• unity projects newで3Dテンプレートのプロジェクトを非対話で作成できました。
• unity testからC#をコンパイルし、Edit Modeテスト一件を実行できました。
• テストのためにUnity Pipeline packageを導入する必要はありませんでした。
• Unity 6.5の標準言語バージョンはC# 9.0でした。C# 10の構文は標準設定では使えません。

検証環境

Unity CLIは現在も実験的な機能です。導入時はUnity CLIの利用方法とリリースノートを確認し、使用したバージョンを記録します。

Unity CLIを導入する

Windowsでは、公式ドキュメントが案内するwingetを利用できます。

winget install Unity.CLI

今回の環境ではwingetコマンドを利用できなかったため、Unity公式CDNのPowerShellインストーラーを一時ファイルへ保存し、内容を確認してから実行しました。

$installerPath = Join-Path $env:TEMP 'unity-cli-install.ps1'

Invoke-WebRequest `
  -Uri 'https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1' `
  -OutFile $installerPath

Get-FileHash -LiteralPath $installerPath -Algorithm SHA256
Get-AuthenticodeSignature -LiteralPath $installerPath

& $installerPath -Target '1.0.0-beta.5' -Channel 'beta'

2026年8月16日の検証では、取得したインストーラースクリプトにAuthenticode署名はありませんでした。スクリプトは、公式マニフェストに記載されたSHA-256でダウンロードしたCLIバイナリを検証します。実行前に取得元と内容を確認し、重要な環境では組織のソフトウェア導入ルールにも従います。

インストーラーは%LOCALAPPDATA%\Unity\bin\unity.exeを配置し、ユーザーのPATHへ追加します。既に開いているターミナルには反映されないため、インストール後にターミナルを開き直します。

CLIと既存Editorを確認する

CLI、Editor、ライセンスの状態は、プロジェクトを変更せずに確認できます。

unity --version
unity editors --installed --json
unity license status --json
unity doctor --json

今回の環境では、Hubから導入済みの6000.3.18f1と6000.5.1f1が自動的に見つかりました。新規プロジェクトで新しい機能とプラットフォーム対応を試すため、検証にはUpdateリリースの6000.5.1f1を選びました。運用中の製品でバージョンを長期間固定する段階では、Unity 6のサポート方針に従いLTSも検討します。

Git対象外の検証領域を用意する

製品用リポジトリの構成を決める前だったため、検証用プロジェクトはリポジトリ直下の.tmpへ置き、Git対象外にしました。

/.tmp/

unity projects newは、指定した親ディレクトリが存在しない場合に作成に失敗しました。先に親ディレクトリを作成します。

New-Item -ItemType Directory -Path .tmp -Force | Out-Null
$validationParent = (Resolve-Path '.tmp').Path

unity --non-interactive --json projects new EvorisUnityCliValidation `
  --path $validationParent `
  --editor-version 6000.5.1f1 `
  --template com.unity.template.3d

成功すると、ProjectSettings/ProjectVersion.txtに6000.5.1f1とEditorのリビジョンが記録されます。

Edit Modeテストを一件追加する

Assets/Tests/EditModeにテスト用Assembly Definitionを置きます。

{
  "name": "Evoris.UnityCliValidation.EditModeTests",
  "rootNamespace": "Evoris.UnityCliValidation.Tests",
  "references": [],
  "includePlatforms": ["Editor"],
  "autoReferenced": false,
  "optionalUnityReferences": ["TestAssemblies"]
}

続いて、Unityの型を利用する小さなテストを追加します。

using NUnit.Framework;
using UnityEngine;

namespace Evoris.UnityCliValidation.Tests
{
    public sealed class GrowthMathTests
    {
        [Test]
        public void Max_SelectsLargerGrowthValue()
        {
            Assert.That(Mathf.Max(2, 3), Is.EqualTo(3));
        }
    }
}

Unity 6000.5.1f1はコンパイル時に-langversion:9.0を指定します。最初の試行ではC# 10のファイルスコープ名前空間を使ったため、CS8773で失敗しました。Unityの現行C#コンパイラー資料に合わせ、C# 9互換の通常の名前空間へ修正しています。

Unity CLIからテストする

テスト結果とEditorログの保存先を分け、CLIからEdit Modeテストを実行します。

$projectPath = (Resolve-Path '.tmp/EvorisUnityCliValidation').Path
$resultDirectory = Join-Path $projectPath 'TestResults'
$resultPath = Join-Path $resultDirectory 'editmode.xml'
$logPath = Join-Path $resultDirectory 'editmode.log'

New-Item -ItemType Directory -Path $resultDirectory -Force | Out-Null

unity --non-interactive --json test $projectPath `
  --mode EditMode `
  --output $resultPath `
  --timeout 600 `
  -- `
  -nographics `
  -logFile $logPath

-logFileを指定しない場合、Editorの初期化、パッケージ解決、コンパイラー引数など大量のログが標準出力へ流れます。CLIの構造化された結果を読みやすくするため、Editorログは別ファイルへ保存します。

検証結果は次のとおりでした。

NUnit形式の結果はTestResults/editmode.xmlへ保存されます。CLIは成功時にレポートのパスをJSONで返すため、エージェントやCIが終了値と結果ファイルを機械的に確認できます。

ログを公開するときの注意

Unity Editorの起動ログには、ローカルの絶対パス、ユーザー環境、起動引数、一時的な認証情報などが含まれる可能性があります。検証ログをGitへ追加したり、記事やCI成果物として公開したりする前に内容を確認し、認証情報と個人情報を除去します。

テスト結果のXMLも、プロジェクト名やテスト名を含みます。公開する必要がなければ、終了値と集計だけを記録する方が安全です。

Pipeline packageをまだ入れない理由

unity projects newやunity testは、Unity CLIがEditorをバッチ起動して完結するため、Unity Pipeline packageなしで利用できました。

Unity Pipeline packageは、実行中のEditorへ接続し、Editorが公開するコマンド、シーン、GameObject、Consoleなどを扱う段階で検討します。テストやビルドだけが目的なら、最初から導入範囲を広げる必要はありません。

関連資料

• Unity CLIの利用方法
• Unity CLIリファレンス
• Unity CLIリリースノート
• Unity Pipeline package
• Unity 6のリリースサポート
• UnityのC#コンパイラー