VS Codeで「rust-analyzer failed to load workspace」を修正する

エラーの概要

VS Codeを開いてRustを書こうとしたところ、オートコンプリートや型ヒントの代わりに、右下にこんな通知が表示されました：

rust-analyzer failed to load workspace: Failed to read Cargo metadata from path '/project/Cargo.toml'

エディタが沈黙します――定義への移動も、シンボル検索も、ホバー時の型表示もなくなります。原因は主に二つです。rust-analyzerがcargoを見つけられないか実行できないか、あるいは間違ったディレクトリでCargo.tomlを探しているかのどちらかです。

設定を変更する前に、統合ターミナルでプロジェクトのルートから以下を実行してください：

cargo metadata --format-version 1 --manifest-path ./Cargo.toml

結果は三パターンあり、それぞれ調べるべき箇所を教えてくれます：

GUIから起動したVS Code（Finder、Spotlight、スタートメニューなど）は、シェルのPATHを継承しません。そのため~/.cargo/binが追加されず、これがmacOSとLinuxで最も多い原因です。

まずツールチェーンが正常かどうか確認します：

rustup update
rustc --version

ターミナルでは動作するのにVS Codeで依然として失敗する場合は、ターミナルから直接VS Codeを起動してみてください：

code .

それが難しい場合は、rust-analyzerのバイナリを明示的に指定します。settings.jsonを開き（Ctrl+Shift+P → Preferences: Open User Settings (JSON)）、以下を追加してください：

{
  "rust-analyzer.server.path": "~/.cargo/bin/rust-analyzer",
  "rust-analyzer.cargo.buildScripts.enable": true
}

Windowsの場合、~をフルパスに置き換えてください：C:\\Users\\YourName\\.cargo\\bin\\rust-analyzer.exe

モノレポで作業していますか？あるいはクレートのルートではなく、クレートを含む親フォルダを開いていませんか？それが原因です。rust-analyzerはVS Codeが開いたフォルダのルートでCargo.tomlを探しますが、そこには何もありません。

マニフェストの場所を拡張機能に正確に伝えてください。.vscode/settings.jsonにlinkedProjectsを追加します：

{
  "rust-analyzer.linkedProjects": [
    "./subdir/Cargo.toml",
    "./another-crate/Cargo.toml"
  ]
}

ファイルを保存したら、コマンドパレット（Ctrl+Shift+P）を開いてRust-analyzer: Restart serverを実行してください。

これは気づきにくい問題です。VS Codeに同梱されているrust-analyzerは、インストール済みのツールチェーンと同期がずれることがあります――特にnightlyを使っている場合や、数週間更新していない場合に起こりやすいです。

以下の両方を実行してください：

rustup component add rust-analyzer
rustup component add rust-src

特定のツールチェーンを使用していますか？バージョンを固定しましょう。プロジェクトルートにrust-toolchain.tomlを作成します：

[toolchain]
channel = "nightly"

これによりcargoとrust-analyzerの両方が同じツールチェーンバージョンを使用するよう強制され、サイレントな不一致が発生しなくなります。

ターミナルではcargo metadataが正常に動作するのに、VS Codeでまだエラーが表示される場合は、何かが破損しています。VS Codeを完全に閉じてから、以下を実行してください：

cargo clean
rm -rf ./.cargo-lock  # 存在する場合
rm -rf ~/.cache/rust-analyzer  # Linux
# macOS: rm -rf ~/Library/Caches/rust-analyzer

VS Codeを再度開きます。ステータスバーを確認すると「Indexing」の進行状況インジケータが表示されます。クレートが約50個の中規模プロジェクトでは、30〜60秒程度かかります。何かテストする前に、完全に終わるまで待ちましょう。

本当に修正されたかどうか、どうやって確認しますか？

ステータスバーにrust-analyzer ✓または「Indexing」が表示される――赤いエラーアイコンではない
任意の変数にホバーすると、推論された型のツールチップがすぐに表示される
Outputパネルを開き、ドロップダウンからRust Analyzer Language Serverを選択する。エラーのスタックトレースではなく「Finished cargo metadata loading」と表示されることを確認する

**ワークスペースのCargo.toml：**マルチクレートのワークスペースでは、ルートのCargo.tomlにすべてのメンバーを列挙した[workspace]セクションが必要です。エントリが欠けていると、リストに載っていないクレートでまさにこのエラーが発生します。
**LinuxのnoexecマウントLinux：**プロジェクトがnoexecフラグ付きのマウント上にある場合、cargoはビルドスクリプトを実行できません。mount | grep noexecで確認し、必要であればフラグなしで再マウントしてください。
**拡張機能の競合：**旧来の「Rust」拡張機能と「rust-analyzer」を同時に実行しないでください――両者が言語サーバーの制御を奪い合い、どちらも正常に動作しなくなります。古い拡張機能は無効化またはアンインストールしてください。