更新前の確認とアップデート手順

更新予定を確認し、必要な復旧地点を用意してから新しい版を動かします。コード更新とデータベース移行の違いも説明します。

目次

更新するものを分ける

更新は、変更予定の確認、必要なバックアップの準備、確認用サイトでの更新と動作確認、本番への反映の順に進めます。プログラムの部品(パッケージ)を更新するほか、テーマや設定の修正、データベース内部の変更が必要になる場合もあります。

このガイドはEmDash 1.4.0時点の更新方式を説明します。実際に更新するときは、その日の対象版とリリース情報を確認してください。

1. 現在の状態を記録する

VS Codeでサイトのフォルダーを開き、新しいターミナルを用意します。Windowsではコマンドプロンプトを選びます。入力画面の開き方

サイトのプロジェクトで、使用中のNode.js、EmDash、Cloudflare用パッケージの版を確認します。package.jsonだけでなく、lockファイルと実際にインストールされた版も対象です。

node --version
npm ls emdash @emdash-cms/cloudflare

Node.js用サイトにCloudflareパッケージがないこと自体は問題ではありません。Cloudflare構成では、emdashと@emdash-cms/cloudflareの対応する版を揃えます。

既存のコード変更も保存しておき、今回の更新で何が変わったか比較できるようにします。公開サイトと同じデータを直接使うローカル設定なら、起動するだけでもそのデータへ影響する可能性があることを確認します。

2. 更新予定だけを見る

プロジェクトの一番外側、package.jsonがある場所で実行します。

npx upgrade-emdash@latest --dry-run

この段階では、更新するパッケージと変更説明を確認します。latestは実行時点の公開版を指すため、このガイドを書いた日の版と異なる場合があります。

更新ツールの--toは、nextなどの配信タグを選ぶ指定で、任意の完全な版番号を入れる指定ではありません。また、0.35.0より前のEmDashは段階的な更新が必要なので、公式の更新案内を先に確認します。

3. パッケージを更新し、作業指示を読む

予定を確認してから実行します。

npx upgrade-emdash@latest

このツールは、必要なパッケージと、EmDashの作業をAIに案内するスキルを更新します。今回必要な作業は.emdash/UPGRADE.mdにまとめられます。このコマンドでは、データベースの移行はまだ実行しません。

UPGRADE.mdを開き、今回のサイトに必要な修正を確認します。テーマのレイアウトや独自の設定ファイルは、自動的に新しいテンプレートへ置き換わりません。既存のカスタマイズを残して、必要な差分を反映します。

4. 新しいコードを起動する前に、移行を確認する

マイグレーションは、保存済みデータの構造を新しい版に合わせる処理です。既定のautoモードでは、未適用の内部移行が最初のアクセスで動きます。

作業指示に移行追加がある場合、以前からの未適用移行がある場合、データを書き換える作業が必要な場合は、新しいアプリを起動・配置する前に復元できるバックアップを用意します。管理画面のJSONだけでは代用できません。

ビルドすると、そのコードに対応する.emdash/migrations.jsonが生成されます。

npm run build

Cloudflare D1なら、対象設定を明示して状態を確認します。

npx emdash migrate --status --wrangler-config wrangler.jsonc

検証用と本番用など、名前を付けて環境を分けている場合は、対象の環境も指定します。状態確認は、適用済み・未適用・現在のコードが知らない移行を調べる操作です。知らない移行がある場合は、別の版や別の環境を見ていないか確認します。

5. 検証環境で適用する

対象DBと復旧地点を確認してから、対話式で移行する場合は次を使います。

npx emdash migrate --wrangler-config wrangler.jsonc

確認画面の対象をもう一度読みます。途中で切れた場合は、何も実行されなかったと決めつけず、同じDBの--statusを確認します。対象を間違えないよう、確認画面を省略するオプションは付けずに進めてください。

コードの配置後に確認する命令は次です。

npx emdash migrate --check --wrangler-config wrangler.jsonc

--checkは状態の確認だけを行います。移行を実行することはなく、不一致があれば、コマンドの成否を表す番号(終了コード)で知らせます。D1以外の接続方法や大きな移行は、内部移行の公式ガイド(別タブで開く)を参照します。

6. 表示以外も確認する

管理画面へのログイン、記事の取得、練習記事の編集・公開、画像の登録と表示を確認します。利用しているなら、予約公開、メール、サンドボックスのプラグインも試します。

検証環境で結果が揃ったら、対象版と復旧地点を記録し、同じ手順を公開先へ適用します。「ビルド成功」と「公開先で通常操作ができた」は別に記録します。

前のコードへ戻すだけでは足りない場合

内部移行は、基本的にデータベースを新しい構造へ変更していく方式です。前のコードを配置しても、DBの変更は元に戻りません。互換性がない場合は、移行前のDBと、それに対応するコード、画像、キーを一緒に戻します。

移行履歴を削除して無理に通したり、内部の取り消し関数を直接呼んだりしません。更新後の障害では、まず対象の版、ログ、移行状態を記録し、問題の切り分けを進めます。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。