メインコンテンツまでスキップ

コードベース読み取りのトラブルシューティングガイド

ヒント

このガイドは、Cursorがコードベースの読み取りとインデックス作成時に発生する可能性のある問題の解決を支援します。

一般的な症状​

1. ファイルが読み取れない​

症状​

  • ファイルが空白で表示される
  • ファイルアクセスエラーが表示される
  • 特定のファイルが開けない

解決策​

  1. ファイル権限の確認

    • ファイルアクセス権限の確認
    • ユーザー権限設定の確認
    • ファイル所有権の確認

  2. ファイルシステムの問題

    • ファイルシステムの整合性チェック
    • 破損ファイルの修復
    • ストレージデバイスの状態確認

  3. エンコーディングの問題

    • ファイルエンコーディングの確認
    • ファイル形式の変換
    • 正しい文字セットの使用

2. インデックス作成の失敗​

症状​

  • 検索結果が不完全
  • コードナビゲーションが機能しない
  • インデックスプロセスが停止

解決策​

  1. インデックスのクリーンアップ

    # インデックスファイルの削除
    rm -rf .cursor/index

    # Cursorの再起動

  2. 設定の確認

    {
      "search.indexing.enabled": true,
      "search.indexing.exclude": [
        "node_modules",
        "dist",
        ".git"
      ]
    }

  3. パフォーマンスの最適化

    • メモリ制限の増加
    • インデックス範囲の縮小
    • ファイルフィルタリングの最適化

3. パフォーマンスの問題​

症状​

  • ファイルの開き方が遅い
  • メモリ使用量が高い
  • 応答が遅い

解決策​

  1. リソース管理

    • メモリ使用量の監視
    • 開いているファイル数の制限
    • 未使用タブの閉じる

  2. 設定の最適化

    {
      "files.maxMemoryForLargeFilesMB": 4096,
      "files.watcherExclude": {
        "**/node_modules/**": true,
        "**/dist/**": true
      }
    }

  3. システムの最適化

    • システムキャッシュのクリア
    • システムドライバーの更新
    • ハードウェア状態の確認

予防措置​

1. プロジェクト設定​

設定の最適化：

  • .gitignoreの使用
  • ファイルフィルタリングの設定
  • 適切な制限の設定

2. パフォーマンス監視​

監視指標：

  • CPU使用率
  • メモリ消費
  • ディスクI/O
  • 応答時間

3. 定期的なメンテナンス​

メンテナンスタスク：

  • 一時ファイルのクリーンアップ
  • インデックスデータの更新
  • ストレージ空間の最適化
  • エラーログの確認

高度なトラブルシューティング​

1. ログ分析​

詳細ログの有効化：

{
  "cursor.logging.level": "debug",
  "cursor.logging.file": true
}

分析方法：

  1. エラーパターンの確認
  2. パフォーマンス問題の追跡
  3. リソースボトルネックの特定

2. パフォーマンス分析​

使用ツール：

  1. メモリアナライザー
  2. CPUプロファイラー
  3. I/Oモニター

最適化の提案：

  • ホットスポットの特定
  • リソース使用の最適化
  • キャッシュ戦略の改善

3. システム診断​

診断手順：

  1. システム健全性チェック
  2. ハードウェア診断
  3. ネットワーク分析
  4. ストレージ検査

特定のシナリオの解決策​

1. 大規模コードベース​

処理戦略：

  1. インクリメンタルインデックス
  2. 階層的ロード
  3. スマートキャッシュ
  4. オンデマンドインデックス

設定例：

{
  "search.indexing.maxFileSize": 524288000,
  "search.indexing.batchSize": 1000
}

2. リモートコードベース​

最適化方法：

  1. キャッシュの使用
  2. 転送の圧縮
  3. インクリメンタル同期
  4. 頻用ファイルのプリロード

3. 特殊ファイルタイプ​

処理推奨事項：

  1. バイナリファイル

    • 専用ビューアーの使用
    • ファイルサイズの制限
    • インデックスのスキップ

  2. 大きなテキストファイル

    • チャンク読み込み
    • 仮想スクロール
    • 遅延処理

ベストプラクティス​

1. プロジェクト組織​

組織化の推奨事項：

  • 適切なディレクトリ構造
  • 明確なファイル命名
  • 適切なモジュール分割
  • 文書の充実

2. 設定管理​

設定のポイント：

  • バージョン管理設定
  • チーム共有設定
  • 環境固有の設定
  • パフォーマンス最適化パラメータ

3. チームコラボレーション​

コラボレーションガイドライン：

  • 開発環境の統一
  • 設定ファイルの共有
  • コーディング規約の制定
  • 同期更新の維持

よくある質問​

1. インデックスの問題​

Q: なぜインデックスが不完全なのですか？ A: 以下が原因の可能性があります：

  • ファイル権限の問題
  • 設定の制限
  • リソース不足

2. パフォーマンスの問題​

Q: なぜファイルを開くのが遅いのですか？ A: 一般的な原因：

  • ファイルが大きすぎる
  • メモリ不足
  • ディスク速度が遅い