pnpm install後のビルドだけが止まり、Node.js 22と24のどちらを残すべきか判断できない状態なら、まず全台を最新版へ更新してはいけません。

最短の判断は、npm実行ならチームで検証済みのLTSを固定し、源码開発なら公式要件を満たすNode.js 22または24を同じ検査項目で比較することです。 そのうえで本番用環境は安定版、別の隔離環境はアップグレード検証用に分けます。

対象となる開発者

Web UIやHeadlessモードをnpmから素早く起動したい利用者、源码からビルドして機能追加や修正を行う貢献者、プラグインとCI runner、リモートMacの実行環境を管理する担当者向けの記事です。

Node.jsの一般的なアップグレード手順ではなく、DeepSeek Harnessをどの場面で22系に残し、どの場面で24系を検証するかという運用判断に絞ります。

公式要件の確認

現行の公式開発ガイドでは、源码開発の対応範囲はNode.js 22.19以上、または24以上です。CIではNode.js 22.19、24、26がカバーされていますが、CIの対象に含まれることは、あらゆるプラグインや本番構成の動作保証を意味しません。まずは公式開発ガイドとルートのpackage.jsonを確認します。

package.jsonにはNode.jsの条件が^22.19.0 || >=24.0.0として記載され、パッケージマネージャーはpnpm@11.7.0に固定されています。つまり、Node.js 22なら22.19未満を避け、Node.js 24なら24系の検証済みパッチを選び、pnpmだけを個人の環境に合わせて変更しないことが基本です。

Node.js側のリリース情報でも、22系と24系はLTSの対象として扱われています。ただし、LTSであることはDeepSeek Harnessの最新プラグインまで自動的に互換になるという意味ではありません。公式のNode.jsリリース一覧は、保守状況を確認する資料として使い、実際の採用判断はリポジトリ要件と自分の検証結果で決めます。

実行形態ごとの選択表

利用場面 第一候補 Node.js 22を維持する条件 Node.js 24を試す条件 成功判定
npm公開パッケージのWeb実行 検証済みのLTS 既存環境で起動とモデル接続が完了している 新しいプラグインが24系を要求する Web起動、モデル接続、工具呼び出し
npm公開パッケージのHeadless実行 検証済みのLTS CIや運用端末で再現性がある 24系でだけ必要な依存機能がある 1回の処理完了と終了コード
源码開発 22.19以上または24以上 既存ブランチのCIと型検査に合う 公式CIの主対象に合わせる必要がある pnpm run typecheckとbuild
プラグイン開発 Host互換を確認した版 ネイティブ依存が22系で安定している インストールからロードまで24系で通る 登録、ロード、工具実行、解除
CI runner 明示固定した版 正式ジョブの再現性を優先する 独立した検証ジョブで全検査に成功する ロックファイルを使った再構築
リモートMac 安定環境と検証環境を分離 現行セッションを止めずに維持したい 隔離環境で再インストールと回退を確認した 再起動、再接続、回退後の作業継続

この表の「第一候補」は性能順位ではありません。公式対応範囲、プラグイン依存、再構築のしやすさをまとめた運用上の初期値です。Node.js 24が新しいから速い、Node.js 22が必ず安定する、といった比較は、同じ源码と同じ検査項目を実行したデータなしには断定できません。

npm実行の最小検証

npm公開パッケージを使うだけなら、源码開発用の検査をすべて導入する必要はありません。公式READMEのnpm実行例はnpx @deepseek-ai/dsh webです。最初からNode.js 24へ移行するのではなく、現在利用しているLTSで次の確認を行います。実行方法は公式READMEのnpm手順に合わせてください。

  • [ ] node --versionで採用するNode.jsの実体を記録する
  • [ ] npmまたはnpxが別のNode.jsに紐づいていないことを確認する
  • [ ] WebまたはHeadlessの起動コマンドが終了せずに立ち上がる
  • [ ] APIキーを読み込み、モデル接続が完了する
  • [ ] 1回の工具呼び出しを実行し、結果がセッションへ戻る
  • [ ] プロセスを再起動しても同じ状態を再現できる

この流れで問題がなければ、npm利用者はNode.js 22から24へ移す理由が「新しいから」だけになっていないかを確認します。逆に、対象プラグインの要件が24系を示している場合は、既存環境を上書きせず、別のNode.jsで同じチェックを行ってから切り替えます。

源码開発とpnpmの固定

源码開発では、Node.jsのバージョンだけを合わせても不十分です。公式開発ガイドはCorepack経由のpnpmを前提にし、リポジトリ側もpnpmのバージョンを固定しています。pnpm installの結果を個人の環境差に任せると、依存関係の再解決、postinstallスクリプト、ネイティブ依存の生成物が混ざり、Node.jsの問題に見える別の失敗が起きます。

新しいチェックアウトでは、次の順番を崩さないことが重要です。

  • [ ] Node.js 22.19以上、または24以上を用意する
  • [ ] corepack enableを実行し、pnpm --versionでリポジトリ指定と一致させる
  • [ ] pnpm-lock.yamlを変更せずにpnpm installを実行する
  • [ ] postinstallが省略されていないことを確認する
  • [ ] pnpm run typecheckを実行する
  • [ ] 源码を変更した場合は必要に応じてpnpm run buildを実行する

pnpm-lock.yamlの公式ファイルは、依存関係の再構築に必要な記録です。Node.jsだけを切り替えてロックファイルまで更新してしまうと、失敗原因が runtime なのか依存更新なのか判別しにくくなります。

プラグインとネイティブ依存

プラグイン開発では、Node.jsの切り替えによってプラグインのインターフェース故障とネイティブ依存のビルド故障が同時に見えることがあります。PTY、SQLite、画像処理、ファイル監視など、OSやCPUアーキテクチャに依存するモジュールが含まれる場合は、Node.jsを変更した後に依存モジュールの再インストールや再ビルドが必要になることがあります。

判定は「ビルドできたか」だけで終わらせません。次の順番で、どの層が壊れているかを分けます。

  • [ ] クリーンな依存関係でインストールできる
  • [ ] TypeScriptの型検査が通る
  • [ ] Hostがプラグインを認識する
  • [ ] プラグインの工具定義が登録される
  • [ ] 実際の工具呼び出しが完了する
  • [ ] プラグインを外した状態で本体が起動する
  • [ ] 旧Node.jsへ戻した場合も同じ解除手順で起動できる

Node.js 24でインストールだけ成功し、ロード時に失敗するなら、Node.jsの基本互換よりもネイティブモジュール、exports定義、Host側の登録処理を疑います。Node.js 22で同じプラグインを動かし、差分をログとlockfileに残すと、原因をインターフェースの変更と誤認しにくくなります。

CI runnerの固定方法

CIでは、既定イメージのNode.jsが更新されるたびに正式ビルドの結果が変わる構成を避けます。公式開発ガイドはNode.js 22.19、24、26の互換性マトリクスを説明していますが、これは対応確認の材料であり、各チームのプラグインや秘密情報を含む運用環境の保証ではありません。

正式ジョブでは、少なくとも次を明示します。

  • Node.jsのメジャー版と採用パッチ
  • Corepackの有効化方法
  • package.jsonが指定するpnpm
  • pnpm-lock.yamlを使うインストール方法
  • typecheck、build、プラグイン検査の実行結果
  • 使用したコミット、Node.js、pnpmの記録

Node.js 24を試す場合は、正式ジョブの既定値を直接書き換えず、独立した検証ジョブに分けます。検証ジョブが失敗しても、安定版の成果物生成とデプロイ判定が巻き込まれない構成にしておくと、更新を延期する判断が可能になります。

リモートMacの二軌道運用

リモートMacでは、Node.js 22と24を同じ作業ディレクトリで頻繁に切り替えないことが安全です。現行のAgentを維持する安定環境と、新しいNode.js、依存キャッシュ、プラグインを検証する隔離環境を分け、切り替え前後の状態を記録します。

最低限、次の情報を環境台帳に残します。

  • Node.jsとpnpmの実行パスおよびバージョン
  • リポジトリのコミットとlockfileのハッシュ
  • インストール、typecheck、buildのコマンド
  • ネイティブ依存の再インストール手順
  • WebまたはHeadlessプロセスの再起動方法
  • 旧環境へ戻す手順と、回退後に確認する機能

特に見落とされやすいのが、Node.jsの回退後に既存のnode_modulesをそのまま使うことです。ネイティブ依存が含まれる場合は、Node.jsを戻した後にも依存関係を再構築し、Web起動、Headless実行、プラグインロード、作業ディレクトリの再接続まで確認します。

リモートMacを一時的な検証環境として使う場合は、RUVCLOUDのMac環境案内から利用形態を確認し、安定環境と検証環境を分けて運用できるかを先に決めます。長期的な固定負荷や物理インターフェースが必要な用途では、専用の自前Macのほうが適する場合もあります。

同一基準でのアップグレード判定

Node.js 22と24を比較する際は、ベンチマークの数値を作るのではなく、DeepSeek Harnessで実際に必要な一連の作業を同じ条件で実行します。比較対象はNode.jsだけにし、源码、lockfile、pnpm、API設定、プラグイン構成を揃えます。

  • [ ] 同じコミットをクリーンチェックアウトする
  • [ ] 同じpnpmで依存関係をインストールする
  • [ ] pnpm run typecheckを実行する
  • [ ] pnpm run buildを実行する
  • [ ] WebまたはHeadlessを起動する
  • [ ] モデル接続と1回の工具呼び出しを確認する
  • [ ] 対象プラグインの登録、実行、解除を確認する
  • [ ] 失敗時のログ、終了コード、lockfile差分を保存する

判定は次の条件式で十分です。

  • 22系で全項目が通り、24系に固有の要件がない場合は「維持」
  • 24系で同じ項目が通り、チームの公式CIや新規プラグイン要件にも合う場合は「アップグレード」
  • 24系でネイティブ依存、プラグインロード、回退のいずれかが未確認なら「暫定維持」

FAQ

最低要件の確認

DeepSeek Harnessの源码開発では、公式ガイドとpackage.jsonの両方を確認します。現行の記載はNode.js 22.19以上、または24以上です。npm公開パッケージでは、利用するリリースとプラグインの組み合わせによって結果が変わるため、公開パッケージの要件確認と最小実行テストを分けて行います。

Node.js 22と24の初期選択

Web UIやHeadlessをnpmから使うだけなら、すでにチームで再現できているLTSを優先します。源码開発や公式CIへの貢献ではNode.js 24を検証候補にできますが、24系を採用する根拠は新しさではなく、typecheck、build、プラグイン実行、回退まで通った記録です。

更新後のビルド失敗

更新後にビルドが壊れた場合は、同じコミットを旧Node.jsで再実行し、Node.jsの差分と依存関係の差分を分離します。pnpm installがlockfileを変更していないか、ネイティブ依存が再構築されたか、TypeScript型検査だけが失敗していないかを順に確認すると、問題の層を絞れます。

リモートMacの固定

リモートMacでは、Node.jsのバージョン名だけでなく、実行ファイルのパス、pnpmの固定方法、lockfile、再構築コマンド、回退手順を台帳化します。現行Agentを動かす環境を直接更新せず、隔離環境でインストールからプラグインロードまで確認してから切り替えると、セッション停止の影響を抑えられます。

現在の共有runnerや個人Macだけで運用すると、既定イメージの更新、Node.jsの実体差、pnpmの取得元の違い、ネイティブ依存の再構築漏れが同時に発生しやすくなります。特に、安定版を残したまま新しいNode.js 24を検証したい場合、1台の環境を上書きする方法は回退の証拠を残しにくいという弱点があります。

一方、RUVCLOUDのMac環境なら、安定運用用と検証用を分ける前提で、Node.jsの固定、環境再構築、回退確認を進めやすくなります。短期のプラグイン検証やCI再現環境が必要な場合は、RUVCLOUDの利用プランと、実際の作業環境を用意するMac注文ページを確認し、バージョン固定と回退証拠を残せる構成を選ぶと判断しやすくなります。