strapi-version-upgrade

Strapi のバージョンアップグレード

Strapi プロジェクトを指定したバージョンにアップグレードします。このスキルでは、次の 2 つの厳格なルールを適用します。

1. アップグレード前に、必ず破壊的変更を確認してください。 現在のバージョンと対象バージョンの間に適用される破壊的変更を確認せずに、アップグレードを実行してはいけません。
2. アップグレードには必ず @strapi/upgrade ツールを使用してください。 package.json を手動で編集したり、npm install @strapi/strapi@x を直接実行したりしてアップグレードしてはいけません。

以下の手順を順番に実行してください。

ステップ 1 — 現在のバージョンと対象バージョンを確認する

1. package.json の dependencies にある @strapi/strapi から、プロジェクトで現在使用している Strapi のバージョンを読み取ります。作業ディレクトリに Strapi プロジェクトがない場合は、処理を中止してユーザーに伝えてください。

2. 公開されている最新バージョンを確認します。

   npm view @strapi/strapi dist-tags
   

   latest タグは、最も新しい安定版リリースを示します。legacy は通常、最新の v4 を示します。

3. 対象バージョンを決定します。ユーザーがバージョンまたはリリースタイプ（major／minor／patch／latest／特定の x.y.z）を指定した場合は、それを使用します。指定がない場合は latest を既定値とし、ユーザーに確認してください。

4. セマンティックバージョニングに従って、アップグレードの差分を分類します。現在のバージョンと対象バージョンの major／minor／patch を比較してください。破壊的変更が導入されるのは、major の数値が変わる場合だけです。 minor および patch リリースは、定義上、後方互換性があります。

ステップ 2 — 破壊的変更を確認する（アップグレード前に必須）

利用可能な場合は、strapi-docs-mcp スキル／strapi-docs MCP サーバーを使用してください。利用できない場合は、ドキュメントを直接取得してください。patch アップグレードの場合でも、このステップを省略してはいけません。

strapi-docs MCP サーバーが利用可能な場合

現在のバージョンから対象バージョンへのアップグレードに伴う破壊的変更を、次のように問い合わせてください。

「Strapi を <current> から <target> にアップグレードする際の破壊的変更は何ですか？」

破壊的変更のタイトルを正確に引用し、codemod で対応できるものと手作業が必要なものを明記してください。

MCP サーバーが利用できない場合

破壊的変更のページを直接取得してください（認証は不要です）。フラットな Markdown 形式を優先してください。

• major バージョンの移行（例：v4 → v5）：https://docs.strapi.io/cms/migration/v4-to-v5/breaking-changes.md

.md URL に対して WebFetch を使用してください（docs.strapi.io のページ URL に .md を追加すると、タブやアコーディオン内に隠れた内容のない、フラットな Markdown を取得できます）。.md 形式のページが 404 になる場合は、HTML URL を再試行してください。

具体的なレポートを作成する — コードベースを調査する

ドキュメントに記載された一般的な一覧だけで終わらせないでください。破壊的変更ごとに、プロジェクトのソースを grep して、実際に該当するものがあるか確認し、概要をプロジェクト固有の一覧にまとめてください。具体的には、次の作業を行います。

• src/index.{js,ts}（アプリの register／bootstrap エントリ）を読み、破壊的変更の影響を受けるパターンを確認します。
• プロジェクトのコントローラー、サービス、ルートファイル（src/api/**）をスキャンします。アップグレードツールの codemod は一般的なパターンに対応しますが、カスタムロジックでは、破壊的変更によって名前が変更または削除される API が使用されていることがよくあります。
• コンテンツタイプのスキーマ（src/api/**/content-types/**/schema.json および src/components/**）を読み、破壊的変更の影響を受ける属性を確認します。たとえば、型が変更された属性や、新しい予約済み／システム名と衝突する属性名などです。
• package.json と config/plugins.{js,ts} を確認し、互換性が影響を受ける可能性のあるサードパーティ製プラグインを調べます。

破壊的変更の各タイトルを検索の手掛かりとして使用し、削除または名前変更された API、非推奨のオプション、予約済みの名前を grep してください。各破壊的変更に該当するファイルを報告し、アップグレードによってどの部分に影響があり、どの部分を手作業で修正する必要があるのかをユーザーが正確に把握できるようにしてください。

報告とゲート

• 同じメジャーバージョン（マイナー／パッチバージョンのアップグレード）： 破壊的変更はありませんと明確に伝えてください。破壊的変更のデータベースは、メジャーバージョンの移行のみを対象としています。確認は実施したことも伝えてください。
• メジャーバージョンのアップグレード： 上記のコードベースのスキャンに基づき、該当する破壊的変更を要約してください。codemod で対応できる変更と、手動でのコード更新が必要な変更を明示し、予約名の衝突（データベースの移行が必要になる場合があります。手順 7 を参照）を挙げてください。続行する前にユーザーの肯定的な返信を待ってください。同じターン内で続行しないでください。

ステップ 3 — 事前の安全確認

アップグレードの前に、コードベースとデータベースをバックアップするようユーザーに伝えてください（デフォルトの SQLite DB は .tmp/data.db です）。アップグレードツールでは、任意の要件として Git の作業ツリーがクリーンであることも確認します。そのため、変更をコミットしてクリーンな状態にしておくと、ロールバックが容易になります。

ファイルを変更せずに変更内容を確認できるよう、まずドライランを提案してください。

npx @strapi/upgrade <target> --dry

ステップ 4 — 実行中の Node バージョンを確認する（ツールを実行する前）

@strapi/upgrade ツール自体は Node CLI です。npx が呼び出されたときに使われる Node 上で動作し、対象の Strapi と同じ Node 要件を宣言しています。そのため、package.json の engines だけでなく、実行中の Node もツールを実行する前に対象のバージョン範囲を満たしている必要があります。満たしていない場合、アップグレードの実行と、それに続くアプリの起動のどちらも、サポート対象外のランタイム上で行われます。

1. 現在実行中の Node バージョンを確認します（node -v）。

2. 対象の Strapi がサポートする Node のバージョン範囲を確認します。

   npm view @strapi/strapi@<target-x.y.z> engines
   

   （ドキュメントが推奨する、そのメジャーバージョン向けの Node バージョンと照合してください。Strapi は有効な LTS を推奨しています。）

3. 実行中の Node がすでに対象のバージョン範囲を満たしている場合は、ステップ 5 に進みます。

4. 満たしていない場合は、アップグレード前に Node をアップグレードする必要があります。 対応方法は、ユーザーがNode バージョンマネージャーを使用しているかどうかによって異なります。判断する前に確認してください（PATH 上の nvm、fnm、volta と、リポジトリ内の .nvmrc／.node-version／Volta フィールドを確認します）。

   • バージョンマネージャーがある場合： Node バージョンをアップグレードするかどうかをユーザーに尋ねるよう促し、ランタイムを変更する前に必ずユーザーの確認を得てください。確認が取れた場合に限り、次の手順を実行します。
     • 対象のバージョン範囲内から Node バージョンを選びます。対象が提示している LTS リリースを優先してください。
     • バージョンマネージャーを使って切り替えます（グローバルインストールは決して行わないでください）。これにより変更を元に戻せるため、ロールバックが必要な場合でも古い Strapi を古い Node で実行できます。CI とチームメンバーの環境を揃えるため、リポジトリでバージョンを固定すること（.nvmrc／.node-version／Volta フィールド）を提案してください。
   • バージョンマネージャーがない場合： システムの Node を自分で変更しようとしてはいけません。ランタイムをグローバルに入れ替えるのはリスクがあり、簡単に元に戻せないためです。代わりに、Node バージョンを自分で変更するようユーザーに伝え、まずバージョンマネージャー（nvm、fnm、または volta）をインストールしてから、対象のバージョン範囲内の Node バージョンを選択することを推奨してください。ランタイムの問題が解決されるまで作業を停止し、待機してください。
   • Node を切り替えた直後に node_modules を再インストールしてはいけません。 この時点では package.json がまだ古い Strapi を固定しているため、クリーンインストールを行うと、新しい Node に対して古い依存関係ツリーが再構築されます。これにより、バージョン範囲が重複しない場合（下記）には engines のチェックに失敗したり、ネイティブモジュールが誤った ABI 向けにビルドされたりして、ツールが作業を進める前に現在の動作状態が壊れる可能性があります。クリーンインストールは、ステップ 5 の後、ツールが package.json を対象のバージョンに書き換えてから行います（ステップ 7d を参照）。
   • 現在の Node と対象の Node のバージョン範囲がまったく重複しない場合（例：現在は Node 18 をサポートしているが、対象は ≥20 を要求する場合）、古いランタイムを維持したまま安全にインプレースで切り替えることはできません。安全な順序は、まず古い Node で現在のメジャーバージョンを最新のパッチバージョンにする（npx @strapi/upgrade minor を実行する）ことです。こうすれば、その手順をロールバックできます。その後、Node を対象のバージョン範囲に切り替え、ステップ 5 でメジャーアップグレードを実行します。依存関係を再インストールするのは、そのアップグレードの実行後に限ります。

ステップ 5 — アップグレードツールでアップグレードを実行する

プロジェクトのルートから公式ツールを実行します。対象に合ったコマンド形式を選択してください。

npx @strapi/upgrade latest          # newest stable version
npx @strapi/upgrade major           # next major (requires being on latest patch of current major first)
npx @strapi/upgrade minor           # latest minor+patch in current major
npx @strapi/upgrade patch           # latest patch in current minor
npx @strapi/upgrade to <x.y.z>      # a specific published version

注意：

• major には条件があります。プロジェクトが現在のメジャーバージョンの最新パッチバージョンを使用している必要があります。そうでない場合は、先に minor を実行してから major を実行してください。
• レジストリポリシー（.npmrc の min-release-age など）によって latest がブロックされる場合や、ユーザーが特定のバージョンを希望する場合は、to <x.y.z> を使用してください。to を使用すると、メジャーバージョンの安全性チェックは意図的にスキップされます。
• プレリリースの場合は、--codemods-target <x.y.z> を追加してください。
• 便利なフラグ：-y/--yes（プロンプトを自動承認）、-d/--debug（詳細表示）、-p/--project-path <path>（現在の作業ディレクトリ以外のプロジェクト）。メジャーバージョンをまたぐアップグレードでは -y/--yes を避けてください。これを使うと、latest でのメジャーバージョン安全性プロンプトを含むすべてのプロンプトが自動承認されます。ユーザーが無人実行を依頼した場合を除き、対話モード（または各手順でユーザーの明示的な承認を得る方法）を優先してください。

このツールは依存関係を更新してインストールし、対象バージョン向けの codemod を実行します。この手順を、手動での package.json 編集や単独の npm install で代用しないでください。

インストール段階が失敗した場合（ERESOLVE など）、手動で依存関係を編集する前に、まず node_modules とロックファイルを削除して再試行してください（rm -rf node_modules package-lock.json && npm install）。古いメジャーバージョンのロックファイルが原因であることが最も多く、クリーンな再インストールで通常は解決します。

ステップ 6 — engines フィールドを修正する

アップグレードツールは依存関係を更新しますが、package.json の engines フィールドには手を加えません。古いメジャーバージョンの engines.node の範囲が残っていると、互換性チェックに失敗し、アップグレード後の install（npm／yarn／pnpm）がブロックされることがあります。（これは package.json で宣言された範囲であり、ステップ 4 で確認した_実行中の_ Node とは異なります。）

1. プロジェクトの package.json から engines を読み取ります。
2. ステップ 4 で確認した対象バージョンの Node の範囲を再利用します（npm view @strapi/strapi@<target-x.y.z> engines）。
3. プロジェクトの engines.node の範囲が対象バージョンより狭い場合、または対象バージョンと互換性がない場合は、対象メジャーバージョンに適した範囲への置き換えを提案し、ユーザーの確認後に編集を適用します。すでに互換性がある場合は変更しません。

ステップ 7 — アップグレード後：codemod の未対応箇所、プラグイン、マイグレーション

以下を順に実行します。破壊的な変更やコードを変更する操作の前には、必ずユーザーの確認を求めます。ツールが自動的に適用した変更以外は、すべてユーザーが決定します。

7a — codemod の未対応箇所を確認し、修正を提案する

1. アプリを再起動する前に、ツールが加えた変更（特に codemod による編集と package.json）を確認するようユーザーに伝えます。
2. codemod が対応するのは一般的なパターンであり、すべてではありません。ステップ 2 で「手動」として示された破壊的変更と、codemod が実際に変更したコードを照合します。未対応のものが残っている場合は、アプリケーションコードの修正を試みてよいかユーザーに尋ね、肯定の返答を待ちます。同じターンで編集を始めてはいけません。ユーザーが確認した後にのみ、ツールの codemod が適用されてからコードを編集します（先に編集してはいけません。codemod の変更と競合するためです）。

7b — 互換性のないサードパーティ製プラグインをアップグレードする

ステップ 2 の package.json／config/plugins の調査、またはインストール／起動時のエラーで判明したサードパーティ製プラグインのうち、対象の Strapi バージョンと互換性のないものがある場合：

1. 対象バージョンをサポートするプラグインのバージョンを特定します（npm view <plugin> versions、または @strapi/strapi に対するピア依存関係の範囲を確認します）。
2. 各プラグインをアップグレードする前に、ユーザーに個別に確認します。すべてのプラグインのバージョン更新について別々に確認し、黙ってまとめてアップグレードしてはいけません。
3. 確認されたバージョン更新を適用し、再インストールします。

7c — 予約名の衝突 → カスタムデータベースマイグレーション

Step 2 で、対象のメジャーバージョンの新しい予約名／システム名と名前が衝突する属性が見つかった場合は、名前の変更が必要です。カラム名の変更にはデータ損失のリスクがあります。その場合は、次の手順に従います。

1. 名前を変更するかどうかをユーザーに確認します。
2. 変更する場合は、名前の変更中に既存データを保持するため、データベースマイグレーションを生成するかどうかをユーザーに確認します。
3. マイグレーションの書き込みまたは実行の前に、明示的なバックアップ確認を必須とします。 マイグレーションは次回起動時に実際のデータベースに対して実行され、名前の変更をきれいに元に戻すことはできません。そのため、データベースを手動でバックアップ済みであることをユーザーに確認してください。その後、処理を止め、別の返信で明確な「はい」があるまで待ちます。同じターン内で続行してはいけません。 曖昧な返答をもとに続行してはいけません。また、ユーザーの確認に代えて、ユーザーの代わりにバックアップを取ることも決してしてはいけません。バックアップがまだの場合は処理を止め、先にバックアップしてもらいます。
4. 確認を得てから、reference.md に従ってマイグレーションを作成します（配置、順序に関する注意点、データを安全に保つ名前の変更、システムカラムの衝突、冪等性、down()）。この点を曖昧にしてはいけません。記載された順序と衝突のルールは、起動時の失敗と気付かないデータ損失の両方を防ぐためのものです。

7d — 確認

1. メジャーアップグレードでは、Strapi 組み込みのデータマイグレーションが新しいメジャーバージョンでの初回起動時に自動実行されることに注意してください。アップグレードツール自体はデータをマイグレーションせず、./database/migrations/ にあるカスタムマイグレーションも同じタイミングで実行されます。
2. Step 4 で Node を切り替えた場合は、ここでクリーンインストールを実行します。ツールが package.json を対象バージョンに書き換えた後に行い、前には行わないでください：rm -rf node_modules && install。ネイティブモジュール（better-sqlite3、sharp、…）は特定の Node ABI 向けにコンパイルされます。以前の Node のビルドが残っていると、「Node を切り替えたら起動しなくなった」という最もよくある問題が発生し、アップグレードの不具合と誤解されやすくなります。
3. 確認します。必要に応じて再インストールし、管理画面を再ビルドして、アプリを起動し、問題なく起動することを確認します。