dart-run-static-analysis

分析與修復 Dart 程式碼

目錄

• 分析設定
• 忽略診斷資訊
• 工作流程：執行靜態分析
• 工作流程：套用自動修復
• 範例

分析設定

請透過專案根目錄下的 analysis_options.yaml 檔案來設定 Dart 分析器。

• 基礎設定： 務必使用 include: 指令引進標準規則集（例如 package:lints/recommended.yaml 或 package:flutter_lints/flutter.yaml）。
• 嚴格型別檢查： 在 analyzer: language: 節點下啟用嚴格型別檢查，防止隱式向下轉型（implicit downcasts）與 dynamic 動態型別推導。請設定 strict-casts: true、strict-inference: true 以及 strict-raw-types: true。
• Linter 規則： 在 linter: rules: 節點下明確啟用或停用特定規則。覆寫已包含的規則時請使用鍵值對映射（rule_name: true/false）；定義全新規則集時請使用列表（- rule_name）。切勿在同一個 rules 區塊中混用列表與映射語法。
• 格式化工具設定： 在 formatter: 節點下設定 dart format 的行為。可設定 page_width（預設為 80）與 trailing_commas（automate 或 preserve）。
• 分析器外掛： 在 analyzer: plugins: 節點下新增外掛以啟用自訂診斷。請確保已將外掛套件新增至 pubspec.yaml 的 dev_dependencies 中。

忽略診斷資訊

當診斷資訊（Lint 或警告）出現誤報或套用至自動生成的程式碼時，可以明確將其忽略。

• 檔案層級排除： 在 analysis_options.yaml 的 analyzer: exclude: 節點中使用 Glob 樣式排除整個檔案或目錄（例如 **/*.g.dart）。
• 檔案層級忽略： 在 Dart 檔案頂端加上 // ignore_for_file: <diagnostic_code>，即可在整個檔案中忽略特定的診斷資訊。若要忽略所有 Linter 規則，請使用 // ignore_for_file: type=lint。
• 行層級忽略： 在問題程式碼的正上方或行尾加上 // ignore: <diagnostic_code>。
• Pubspec 忽略： 在 pubspec.yaml 檔案中問題程式碼的正上方加上 # ignore: <diagnostic_code>（例如 # ignore: sort_pub_dependencies）。
• 外掛診斷資訊： 忽略外掛專屬的問題時，請在診斷代碼前加上外掛名稱前綴（例如 // ignore: some_plugin/some_code）。

工作流程：執行靜態分析

使用此工作流程來識別型別相關的 Bug、程式碼風格違規以及潛在的執行階段錯誤。

任務進度：

• [ ] 1. 確認專案根目錄存在 analysis_options.yaml。
• [ ] 2. 使用 analyze_files MCP 工具（若可用）或 CLI 命令 dart analyze <target_directory> 執行分析器。
• [ ] 3. 檢視診斷輸出結果。
• [ ] 4. 若必須將 info 層級的問題視為失敗，請加上 --fatal-infos 旗標。
• [ ] 5. 手動解決回報的錯誤，或繼續執行自動修復工作流程。

工作流程：套用自動修復

使用此工作流程來修復過時的 API 用法、套用快速修復（Quick fixes）以及進行程式碼遷移（例如 Dart 3 遷移）。

任務進度：

• [ ] 1. 使用 dart_fix MCP 工具或 CLI 命令 dart fix --dry-run 進行預覽執行（Dry run），檢視預計變更。
• [ ] 2. 檢視預計套用的修復，確保其符合預期的架構設計。
• [ ] 3. 若需要額外的修復，請確認 analysis_options.yaml 中已啟用對應的 Linter 規則。
• [ ] 4. 使用 dart_fix MCP 工具或 CLI 命令 dart fix --apply 套用修復。
• [ ] 5. 使用 dart_format MCP 工具或 CLI 命令 dart format . 格式化已修改的程式碼。
• [ ] 6. 執行靜態分析工作流程，驗證所有診斷問題皆已解決。

範例

完整的 analysis_options.yaml

include: package:flutter_lints/recommended.yaml

analyzer:
  exclude:
    - "**/*.g.dart"
    - "lib/generated/**"
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  errors:
    todo: ignore
    invalid_assignment: warning
    missing_return: error

linter:
  rules:
    avoid_shadowing_type_parameters: false
    await_only_futures: true
    use_super_parameters: true

formatter:
  page_width: 100
  trailing_commas: preserve

程式碼內停用診斷資訊

// 針對整個檔案停用
// ignore_for_file: unused_local_variable, dead_code

void processData() {
  // 針對特定行停用
  // ignore: invalid_assignment
  int x = '';
  
  const y = 10; // ignore: constant_identifier_names
}