Unity│プロジェクトのバージョンを上げる手順｜バックアップ・API Updater・セーフモード

2026年9月29日2026年10月2日

Unityのプロジェクトは、新しいバージョンのエディタで開き直すことでバージョンを上げられます。

ただし、一度上げると元に戻せないことがあるので、手順を決めてから進めます。

最初に：元を保持した控えを作り、Gitで未追跡・除外対象・LFSの実体も確認する
Unity Hub の「プロジェクト」で、新しいエディタを選んで開く
古い書き方のコードは API Updater が書き換えを提案する
エラーがあるとセーフモードで開く。コンソールのエラーを直してから進む

この記事は、Unity公式マニュアル「Upgrade your Unity project」「API updater」（2026年9月29日に確認）にもとづいています。

Unityのエディタでの再現は含まず、画面の名前は英語版の表記です。

1. 控えを取る

公式マニュアルは、問題が起きたときに元に戻せるよう、最初に控えを取ることを勧めています。

Gitなどのバージョン管理を使う場合も、コミットに入っていない未追跡・除外ファイルや、LFSの実体が別にある点を確認します。git status –shortで作業を確認し、必要な.meta・Packagesのmanifestとlock・ProjectSettingsがそろっているかを確かめます。制作上必要な外部素材や設定も、別途控えに含めてください。

Gitで管理するときの .gitignore の書き方は、Unityの.gitignoreの設定方法で紹介しています。

主要3フォルダーを新しい場所へコピーする例

以下はWindows PowerShell 5.1で、Assets・Packages・ProjectSettingsの通常ファイルを新しいフォルダーへコピーする例です。Libraryは生成し直すキャッシュとしてコピーしません。

この3フォルダー以外に独自のソース、.gitignore、.gitattributes、外部参照、ローカル設定などがある場合は追加で控えます。このスクリプトだけをプロジェクト全体の完全なバックアップとは扱わないでください。リンク・ジャンクションは対象外で、空の下位フォルダー、アクセス権や代替データストリームの保持も対象にしていません。

UTF-8（BOM付き）のcopy-unity-core.ps1として保存し、Unityを閉じてファイルの更新を止めた後、コマンドプロンプトからプレビューします。

param([Parameter(Mandatory=$true)][string]$Project,
      [Parameter(Mandatory=$true)][string]$Output,
      [switch]$Apply)
$ErrorActionPreference = 'Stop'
$projectItem = Get-Item -LiteralPath $Project
if (-not $projectItem.PSIsContainer) { throw 'Project must be a folder' }
$root = $projectItem.FullName.TrimEnd('\')
$out = [IO.Path]::GetFullPath($Output).TrimEnd('\')
if ($out -eq $root -or $out.StartsWith($root + '\', [StringComparison]::OrdinalIgnoreCase)) { throw 'Output must be outside Project' }
if (Test-Path -LiteralPath $out) { throw 'Output already exists' }
if ($projectItem.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Links/junctions are not supported' }
$plan = @(foreach ($folder in @('Assets','Packages','ProjectSettings')) {
    $dir = Get-Item -LiteralPath (Join-Path $root $folder)
    if (-not $dir.PSIsContainer) { throw 'Required core folder is missing' }
    $entries = @($dir) + @(Get-ChildItem -LiteralPath $dir.FullName -Recurse -Force)
    if (@($entries | Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint }).Count) { throw 'Links/junctions are not supported' }
    foreach ($file in $entries | Where-Object { -not $_.PSIsContainer }) {
        [pscustomobject]@{
            Relative = $file.FullName.Substring($root.Length + 1)
            Source = $file.FullName
            SHA256 = (Get-FileHash -LiteralPath $file.FullName -Algorithm SHA256).Hash
        }
    }
})
if (-not $plan.Count) { throw 'No core files' }
$plan | Format-List Relative, SHA256
if (-not $Apply) { Write-Host 'Preview only'; return }
[IO.Directory]::CreateDirectory($out) | Out-Null
foreach ($folder in @('Assets','Packages','ProjectSettings')) { [IO.Directory]::CreateDirectory((Join-Path $out $folder)) | Out-Null }
foreach ($row in $plan) {
    $dst = Join-Path $out $row.Relative
    if ((Get-FileHash -LiteralPath $row.Source -Algorithm SHA256).Hash -ne $row.SHA256) { throw 'Source changed during copy' }
    [IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($dst)) | Out-Null
    [IO.File]::Copy($row.Source, $dst, $false)
    if ((Get-FileHash -LiteralPath $dst -Algorithm SHA256).Hash -ne $row.SHA256) { throw 'Copy hash mismatch' }
}
$plan | Select-Object Relative,SHA256 | Export-Csv -LiteralPath (Join-Path $out 'core-hashes.csv') -NoTypeInformation -Encoding UTF8
Write-Host ('Core files copied: ' + $plan.Count)

powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File ".\copy-unity-core.ps1" -Project "C:\Practice\Unity Project" -Output "C:\Practice\Unity Before Upgrade"

RelativeとSHA256の一覧を確認し、同じコマンドの末尾に-Applyを付けてコピーします。OutputはProjectの外にある、未作成の新しい場所を指定します。

コピー後は3フォルダーとcore-hashes.csvができ、ファイルの内容が元と一致することをハッシュで確認しています。Source changedやCopy hash mismatchで止まった場合は一部だけコピーされている可能性があるため、未完成の出力を保持して調べ、新しい出力先でやり直します。

アップグレードの試験用には、控えをさらに別の新しい場所へコピーし、追加で控えたファイルもそろえます。元プロジェクトと更新前の控えを残し、試験用コピーだけを新しいEditorで開いてください。

2026年10月2日、練習用ファイル構成で、プレビュー・.metaを含むコピーのバイト一致・既存出力の保持・元の版とファイル内容の保持を確認しました。Unityによるアップグレードそのものは未検証です。

2. 上げる前に確かめる

新しいバージョンの「新機能」、アップグレードガイド、リリースノート
使っているアセットやパッケージが、新しいバージョンに対応しているか

複数のバージョンをまたいで上げるときは、アップグレードガイドを古い順に読みます。

Unity 6.3 へ上げるなら「Upgrade to Unity 6.3」、6.0 へなら「Upgrade to Unity 6.0」のように、バージョンごとのガイドがあります。

3. 新しいエディタで開く

Unity Hub で新しいバージョンのエディタを入れておく
Unity Hub の「プロジェクト」で、試験用コピーのエディタのバージョンを新しいものに変える（または「Open with…」）
「Change Editor version?」の画面で「Change version」を選ぶ
「Opening Project in Non-Matching Editor Installation」の画面で「Continue」を選ぶ

開くと、Library フォルダーの中身が新しいバージョンに合わせて作り直されるので、大きなプロジェクトでは時間がかかります。

エディタの入れ方は、Unity Hubでエディタとモジュールを入れる方法で紹介しています。

4. API Updaterで古いコードを書き換える

API Updater は、スクリプトの中の古くなった書き方を見つけて、新しい書き方に書き換えることを提案します。

公式マニュアルの例では、light.color = Color.red; が GetComponent<Light>().color = Color.red; に書き換わります。

書き換えられるのは、コンソールのメッセージに UnityUpgradable と書かれたものだけです。

それ以外のエラーや警告は、自分で直す必要があります。

コマンドで動かすとき（バッチモード）は、-accept-apiupdate を付けると確認なしで書き換えます。

書き換えの記録はエディタのログに残り、環境変数 UNITY_APIUPDATER_LOG_THRESHOLD で記録の細かさを変えられます。

5. セーフモードが出たら

スクリプトにコンパイルのエラーがあると、「Enter Safe Mode?」の画面が出ます。

セーフモードでは、エラーを直すことに絞った状態でプロジェクトが開きます。

最初のコンパイルエラーを開き、対象パッケージの対応版や依存関係を確認します。派生したエラーをまとめて機械的に置換せず、原因を直した後に再コンパイルして残件を確認します。

6. パッケージを更新してテストする

コンソールのエラーと、「古くなった（deprecated）」という警告を片付ける
Package Manager で、パッケージを新しいバージョンに合った版に更新する
ゲームを動かして、すべての機能を試す
書き出す機種ごとにビルドして確かめる

更新前と比べる入力・操作・結果の記録

以下を更新前の控えと更新後の試験用コピーで同じ条件にして確認します。結果がそろうまで、チームで使う元プロジェクトへ反映しません。

入力・対象	操作	結果の確認
ProjectVersion.txt、manifest.json、packages-lock.json	版と依存関係の差分を保存	想定したEditor・パッケージだけが変わっている
代表シーン・入力機器・保存データ	同じ場面をPlayして操作・読み込み	描画、入力、音、保存と復元が更新前と同じ
対象機種とビルド設定	機種ごとにビルドし実行	起動・主要操作・エラーの有無を記録

API Updaterの変更もGitの差分で確認します。失敗した場合は更新後のコピーを古いEditorで無理に開き直さず、保持した更新前の控えを元のEditorで開きます。

確認資料：Unityのプロジェクト更新手順。Hub、API Updater、Safe Mode、Play・ビルドの実操作は今回未検証です。