使用 lint 檢查項目改善程式碼

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

除了建立測試來確保應用程式符合功能要求之外，您也必須透過 lint 工具執行程式碼，確保程式碼沒有任何結構上的問題。Lint 工具可協助您找出結構不良的程式碼，這類程式碼會影響 Android 應用程式的可靠性和效率，並讓程式碼難以維護。強烈建議您在發布應用程式前，修正所有 Lint 偵測出的錯誤。

例如，如果您的 XML 資源檔案包含未使用的命名空間，不但佔用磁碟容量，您還需要浪費精力處理。其他結構問題，例如使用已淘汰的元素或目標 API 版本不支援的 API 呼叫，都可能導致程式碼無法正確執行。Lint 可協助您處理這些問題。

如要提高 Lint 檢查效能，您也可以在程式碼中添加註解。

總覽

Android Studio 提供一款名為 lint 的程式碼掃描工具，可協助您找出並修正程式碼結構品質的問題，而不必執行應用程式或撰寫測試案例。這項工具會偵測每個問題，並提供說明訊息和嚴重性等級，方便您找出哪些重大問題需要優先處理。此外，您可以降低問題的嚴重性等級，忽略與您專案無關的問題，或是提高嚴重性等級來凸顯特定問題。

Lint 工具會檢查 Android 專案來源檔案是否有潛在錯誤，以及在正確性、安全性、效能、可用性、無障礙和國際化層面是否需要最佳化改善。使用 Android Studio 時，每次建構應用程式時，系統都會執行設定的 Lint 和 IDE 檢查。不過，您可以手動執行檢查，或透過指令列執行 Lint，如本頁所述。

內建 Lint 工具會在您使用 Android Studio 時檢查程式碼。您可以透過下列兩種方式查看警示和錯誤：

• 在編輯器視窗中以彈出式文字顯示。在 Lint 發現問題時，會標黃有問題的程式碼。若為嚴重問題，則會在程式碼下方標出紅線。
• 在 lint 的「Inspection Results」視窗中，依序按一下「Code」>「Inspect Code」。

注意：如果您的程式碼在 Android Studio 中編譯完畢，還會執行額外的 IntelliJ 程式碼檢查，以簡化程式碼審查作業。請盡可能讓 Android Studio 保持在最新狀態，確保您能使用最新的 Lint 規則和檢查功能。

圖 1 顯示 Lint 工具如何處理應用程式來源檔案。

應用程式來源檔案

來源檔案包含構成 Android 專案的檔案，包括 Kotlin、Java 和 XML 檔案、圖示和 ProGuard 設定檔。

lint.xml檔案

設定檔，可用於指定任何要排除的 Lint 檢查，並自訂問題嚴重性等級。

lint 工具

可透過指令列或 Android Studio 執行的靜態程式碼掃描工具。lint 工具會檢查可能影響 Android 應用程式品質和效能的結構程式碼問題。

lint 檢查結果

您可以在主控台或 Android Studio 的「Inspection Results」視窗中查看 Lint 的結果。如果您透過指令列執行 lint，結果會寫入 build/ 資料夾。詳情請參閱「手動執行檢查」一節。

透過指令列執行 lint

如果您正在使用 Android Studio 或 Gradle，請使用 Gradle 包裝函式，透過從專案的根目錄輸入下列其中一個指令來為您的專案叫用 lint 工作：

注意：請盡可能使用最新的 Android Gradle 外掛程式，以便使用最新的 Lint 規則。

• Windows 系統：

  gradlew lint
  

• Linux 或 macOS：

  ./gradlew lint
  

畫面會顯示類似下列輸出內容：

> Task :app:lintDebug
Wrote HTML report to file:<path-to-project>/app/build/reports/lint-results-debug.html

Lint 工具完成檢查後，會提供 Lint 報告的 XML 和 HTML 版本路徑。接著，您可以點選 HTML 報表並在瀏覽器中開啟，如圖 2 所示。

如果您的專案包含建構變數，lint 只會檢查預設變化版本。如要在其他變化版本中執行 Lint，則必須將變化版本名稱大寫，並在前面加上 lint。

./gradlew lintRelease

注意：Lint 不會在建構期間自動執行。強烈建議您在持續整合建構作業中明確執行 Lint，這樣在建構現有程式碼時，您就能查看最新的 Lint 檢查結果。

如要進一步瞭解如何透過指令列執行 Gradle 工作，請參閱「透過指令列建構應用程式」。

使用獨立工具執行 lint

如果您未使用 Android Studio 或 Gradle，請安裝 Android SDK 指令列工具，以便使用獨立的 Lint 工具。接著，您可以在 android_sdk/cmdline-tools/version/bin/lint 中找到 Lint 工具。

注意：如果您嘗試在 Gradle 專案上執行獨立工具，系統會顯示錯誤。請務必使用 gradle lint (Windows) 或 ./gradlew lint (macOS 或 Linux) 在 Gradle 專案上執行 Lint。

如要對專案目錄中的檔案清單執行 Lint，請使用下列指令：

lint [flags] <project directory>

例如，您可以發出以下指令，掃描 myproject 目錄和其子目錄下的檔案。問題 ID MissingPrefix 會指示 lint 僅掃描缺少 Android 命名空間前綴的 XML 屬性。

lint --check MissingPrefix myproject 

如要查看工具支援的旗標和指令列引數完整清單，請使用下列指令：

lint --help

以下範例呈現出在針對名為 Earthquake 的專案執行 Lint 指令時，主控台的輸出內容：

$ lint Earthquake

Scanning Earthquake: ...............................................................................................................................
Scanning Earthquake (Phase 2): .......
AndroidManifest.xml:23: Warning: <uses-sdk> tag appears after <application> tag [ManifestOrder]
  <uses-sdk android:minSdkVersion="7" />
  ^
AndroidManifest.xml:23: Warning: <uses-sdk> tag should specify a target API level (the highest verified version; when running on later versions, compatibility behaviors may be enabled) with android:targetSdkVersion="?" [UsesMinSdkAttributes]
  <uses-sdk android:minSdkVersion="7" />
  ^
res/layout/preferences.xml: Warning: The resource R.layout.preferences appears to be unused [UnusedResources]
res: Warning: Missing density variation folders in res: drawable-xhdpi [IconMissingDensityFolder]
0 errors, 4 warnings

範例輸出內容列出四個警告，沒有錯誤。

兩個警告與專案的 AndroidManifest.xml 檔案有關：

• ManifestOrder
• UsesMinSdkAttributes

一個警告與 res 目錄相關：IconMissingDensityFolder。

設定 Lint 以隱藏警告

根據預設，當您執行 Lint 掃描時，此工具會檢查所有支援 Lint 的問題。您也可以限制 lint 檢查的問題，並指派問題的嚴重性等級。例如，針對與專案無關的特定問題，您可以隱藏 lint 檢查，此外，您也可以將 lint 設定為在較低嚴重性等級回報非重大問題。

嚴重性等級如下：

• enable
• disable 或 ignore
• informational
• warning
• error
• fatal

您可以針對不同層級設定 Lint 檢查功能：

• 全球 (整項專案)
• 專案模組
• 正式版模組
• 測試模組
• 開啟檔案
• 類別階層
• 版本管控系統 (VCS) 範圍

設定 lint 檔案

您可以在 lint.xml 檔案中指定 Lint 檢查偏好設定。如果您要手動建立這個檔案，請將檔案放入 Android 專案根目錄。

lint.xml 檔案包含具有 <lint> 父項標記，其中包含一或多個子項 <issue> 元素。Lint 會為每個 <issue> 定義專屬 id 屬性值：

<?xml version="1.0" encoding="UTF-8"?>
<lint>
    <!-- list of issues to configure -->
</lint>

如要變更問題的嚴重性等級或停用 Lint 檢查功能，請在 <issue> 標記中設定嚴重性屬性。

提示：如要查看 Lint 支援問題的完整清單和對應的問題 ID，請執行 lint --list 指令。--list 選項必須透過獨立 lint 工具執行。

lint.xml 檔案範例

以下範例顯示 lint.xml 檔案的內容：

<?xml version="1.0" encoding="UTF-8"?>
<lint>
    <!-- Disable the IconMissingDensityFolder check in this project -->
    <issue id="IconMissingDensityFolder" severity="ignore" />

    <!-- Ignore the ObsoleteLayoutParam issue in the specified files -->
    <issue id="ObsoleteLayoutParam">
        <ignore path="res/layout/activation.xml" />
        <ignore path="res/layout-xlarge/activation.xml" />
    </issue>

    <!-- Ignore the UselessLeaf issue in the specified file -->
    <issue id="UselessLeaf">
        <ignore path="res/layout/main.xml" />
    </issue>

    <!-- Change the severity of hardcoded strings to "error" -->
    <issue id="HardcodedText" severity="error" />
</lint>

以下範例說明如何回報不同類型的問題。IconMissingDensityFolder 檢查功能已完全停用，而 ObsoleteLayoutParam 檢查功能只會在附加 <ignore ... /> 宣告中指定的檔案中停用。

為 Kotlin、Java 和 XML 來源檔案設定 Lint 檢查功能

您可以在「Preferences」對話方塊中關閉 Kotlin、Java 和 XML 來源檔案的 Lint 檢查功能：

1. 依序選取「File」>「Settings」 (Windows 上) 或「Android Studio」>「Preferences」(macOS 或 Linux 上)。
2. 依序選取「Editor」>「Inspections」。
3. 如要停用，請取消選取相應的來源檔案。

您可以選取適當的設定檔，為 IDE 或個別專案設定這些設定。

在 Java 或 Kotlin 中設定 Lint 檢查功能

如要停用 Android 專案中特定類別或方法的 Lint 檢查功能，請在該程式碼中加入 @SuppressLint 註解。

以下範例說明如何關閉 onCreate 方法中的 NewApi 問題。Lint 工具會持續檢查這個類別其他方法中的 NewApi 問題。

@SuppressLint("NewApi")
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

@SuppressLint("NewApi")
@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

您也可以在任何可組合函式上執行相同操作。以下程式碼片段說明如何在任何 Composable 上關閉 NewApi 檢查。

  @SuppressLint("NewApi")
  @Composable
  fun MyComposable{
    ...
  }
  

以下範例說明如何為 FeedProvider 類別中的 ParserError 問題關閉 Lint 檢查功能：

@SuppressLint("ParserError")
class FeedProvider : ContentProvider() {

@SuppressLint("ParserError")
public class FeedProvider extends ContentProvider {

如要隱藏檔案中的所有 lint 問題，請使用 all 關鍵字：

@SuppressLint("all")

@SuppressLint("all")

您可以使用相同的註解，在任何可組合函式上抑制 Lint 檢查。

在 XML 中設定 Lint 檢查功能

您可以使用 tools:ignore 屬性，為 XML 檔案的特定部分關閉 Lint 檢查功能。將下列命名空間值放入 lint.xml 檔案，讓 Lint 工具識別此屬性：

namespace xmlns:tools="http://schemas.android.com/tools"

以下範例說明如何為 XML 版面配置檔案的 <LinearLayout> 元素中的 UnusedResources 問題關閉 lint 檢查功能。ignore 屬性由宣告該屬性的父項元素的子項元素繼承。在此範例中，子項 <TextView> 元素也要停用 Lint 檢查：

<LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:ignore="UnusedResources" >

    <TextView
        android:text="@string/auto_update_prompt" />
</LinearLayout>

如要停用多個問題，請以半形逗號分隔個別字串列出要停用的問題。例如：

tools:ignore="NewApi,StringFormatInvalid"

如要略過檢查 XML 元素中的所有 lint 問題，請使用 all 關鍵字：

tools:ignore="all"

使用 Gradle 設定 Lint 選項

Android Gradle 外掛程式可讓您使用模組層級 build.gradle 檔案中的 lint{} 區塊，以設定某些 lint 選項，例如執行或忽略哪些檢查項目。

下列程式碼片段顯示您可設定的部分屬性：

android {
    ...
    lint {
        // Turns off checks for the issue IDs you specify.
        disable += "TypographyFractions" + "TypographyQuotes"
        // Turns on checks for the issue IDs you specify. These checks are in
        // addition to the default lint checks.
        enable += "RtlHardcoded" + "RtlCompat" + "RtlEnabled"
        // To enable checks for only a subset of issue IDs and ignore all others,
        // list the issue IDs with the 'check' property instead. This property overrides
        // any issue IDs you enable or disable using the properties above.
        checkOnly += "NewApi" + "InlinedApi"
        // If set to true, turns off analysis progress reporting by lint.
        quiet = true
        // If set to true (default), stops the build if errors are found.
        abortOnError = false
        // If set to true, lint only reports errors.
        ignoreWarnings = true
        // If set to true, lint also checks all dependencies as part of its analysis.
        // Recommended for projects consisting of an app with library dependencies.
        checkDependencies = true
    }
}
...

android {
    ...
    lint {
        // Turns off checks for the issue IDs you specify.
        disable 'TypographyFractions','TypographyQuotes'
        // Turns on checks for the issue IDs you specify. These checks are in
        // addition to the default lint checks.
        enable 'RtlHardcoded','RtlCompat', 'RtlEnabled'
        // To enable checks for only a subset of issue IDs and ignore all others,
        // list the issue IDs with the 'check' property instead. This property overrides
        // any issue IDs you enable or disable using the properties above.
        checkOnly 'NewApi', 'InlinedApi'
        // If set to true, turns off analysis progress reporting by lint.
        quiet true
        // If set to true (default), stops the build if errors are found.
        abortOnError false
        // If set to true, lint only reports errors.
        ignoreWarnings true
        // If set to true, lint also checks all dependencies as part of its analysis.
        // Recommended for projects consisting of an app with library dependencies.
        checkDependencies true
    }
}
...

建立警示基準

您可以為專案目前的警告拍攝快照，然後使用快照做為日後檢查的基準，這樣便僅會回報新問題。基準快照可讓您開始使用 Lint 使建構失敗，而不需返回並先解決所有現有問題。

如要建立基準數據匯報，請按照下列步驟修改專案的 build.gradle 檔案：

android {
    lint {
        baseline = file("lint-baseline.xml")
    }
}

android {
    lintOptions {
        baseline file("lint-baseline.xml")
    }
}

首次新增此行時，系統會建立 lint-baseline.xml 檔案以建立您的基準。此後，工具只會讀取檔案來判斷基準。如要建立新的基準，請手動刪除檔案，然後再次執行 Lint 以重新建立檔案。

接著，從 IDE 選取「Code」>「Inspect Code」，或從指令列執行 lint，如下所示。輸出結果會顯示 lint-baseline.xml 檔案的位置。設定檔的檔案位置可能與此處顯示的內容不同：

$ ./gradlew lintDebug -Dlint.baselines.continue=true
...
Wrote XML report to file:///app/lint-baseline.xml
Created baseline file /app/lint-baseline.xml

執行 lint 會記錄 lint-baseline.xml 檔案目前的所有問題。一組目前的問題稱為基準。如果您想與其他使用者分享，可以將 lint-baseline.xml 檔案勾選為版本管控。

自訂基準

如要只將特定問題類型新增至基準，請按照下列步驟編輯專案的 build.gradle 檔案，指定要新增的問題：

android {
    lint {
        checkOnly += "NewApi" + "HandlerLeak"
        baseline = file("lint-baseline.xml")
    }
}

android {
    lintOptions {
        checkOnly 'NewApi', 'HandlerLeak'
        baseline file("lint-baseline.xml")
    }
}

建立基準後，如果您在程式碼集中加入任何新警告，Lint 只會列出新錯誤。

基準警示

當基準生效時，您會收到資訊警告，表示有一或多個問題遭到篩除，因其已列入基準。這則警告是為了提醒您，您已經設定基準，且需要在某個時間點修正所有問題。

這則資訊警告也會追蹤不再回報的問題。這項資訊可讓您知道實際的問題是否已修正，因此可選擇重新建立基準，避免錯誤再次出現時未能偵測出來。

注意：當您在 IDE 以批次模式執行檢查時，系統會啟用基準，但當您編輯檔案時，系統會在背景執行編輯檢查時忽略基準。這是因為基準適用於程式碼集有大量現有警告的情況，而您希望在本機修正程式碼。

手動執行檢查

如要手動執行設定的 lint 和其他 IDE 檢查，請依序選取「Code」>「Inspect Code」。檢查結果會顯示在「Inspection Results」視窗中。

設定檢查範圍和設定檔

選取要分析的檔案 (檢查範圍) 和要執行的檢查 (檢查設定檔)，如下所示：

1. 在「Android」檢視畫面中開啟專案，選取您要分析的專案、資料夾或檔案。
2. 在選單列中依序選取「Code」>「Inspect Code」。

3. 在「Specify Inspection Scope」對話方塊中查看設定。

   

   「Specify Inspection Scope」對話方塊中顯示的選項，會因您選取的專案、資料夾或檔案而異：

   • 當您選取一個專案、檔案或目錄時，「Specify Inspection Scope」對話方塊會顯示您所選取的專案、檔案或目錄的路徑。
   • 當您選取多個專案、檔案或目錄時，「Specify Inspection Scope」對話方塊會為「Selected files」顯示已選取的圓形按鈕。

   如要變更要檢查的項目，請選取其他圓形按鈕。如需「Specify Inspection Scope」對話方塊中所有可能欄位的說明，請參閱「指定檢查範圍對話方塊」。

4. 在「Inspection profile」下方，選取要使用的設定檔。

5. 按一下「OK」執行檢查。

   圖 4 顯示「Inspect Code」執行作業中的 lint 和其他 IDE 檢查結果：

   

6. 在「Inspection Results」窗格中，展開並選取錯誤類別、類型或問題，即可查看檢查結果。

   「Inspection Report」窗格會顯示「Inspection Results」窗格中所選錯誤類別、類型或問題的檢查報告，並顯示錯誤的名稱和位置。在適用情況下，檢查報告會顯示其他資訊，例如問題語法，協助您修正問題。

7. 在「Inspection Results」窗格樹狀檢視中，右鍵按一下類別、類型或問題，即可顯示內容選單。

   視情況而定，您可以：

   • 跳至來源。
   • 排除和納入所選項目。
   • 略過問題。
   • 編輯設定。
   • 管理檢查警報。
   • 重新執行檢查。

如要瞭解工具列按鈕、內容選單項目和檢查報告欄位的說明，請參閱「 檢查結果工具視窗」。

使用自訂範圍

使用 Android Studio 提供的其中一個自訂範圍，如下所示：

1. 在「Specify Inspection Scope」對話方塊中，選取「Custom scope」。

2. 按一下「Custom scope」清單，即可顯示選項：

   

   • 所有位置：所有檔案。
   • 「Project Files」：目前專案中的所有檔案。
   • 「Project Source Files」：僅限目前專案中的來源檔案。
   • 「Project Production Files」：僅限目前專案中的正式版檔案。
   • 「Project Test Files」：僅限目前專案中的測試檔案。
   • Scratches and Consoles：僅顯示您在目前專案中開啟的暫存檔案和主控台。
   • 「Recently Viewed Files」：僅顯示目前專案中最近查看過的檔案。
   • 「Current File」：僅顯示目前專案中的檔案。在選取檔案或資料夾時顯示。
   • 「Selected Directory」：僅顯示目前專案中的目前資料夾。在選取資料夾時顯示。
   • 「Class Hierarchy」：選取這個選項並按一下「OK」後，畫面上會出現一個對話方塊，其中列出了目前專案中的所有類別。在對話方塊中，使用「Search by Name」欄位篩選並選取要檢查的類別。如果您未篩選類別清單，程式碼檢查功能會檢查所有類別。

如果您為專案設定了版本控制系統，則可以選擇只搜尋已修改過的檔案。

3. 按一下「OK」。

建立自訂範圍

如果您想要查看不在任何可用自訂範圍範圍內的檔案和目錄，您可以建立自訂範圍：

1. 在「Specify Inspection Scope」對話方塊中，選取「Custom scope」。

2. 按一下「Custom Scope」清單後方的三個點。

   

   系統會隨即顯示「Scopes」對話方塊。

   

3. 按一下對話方塊左上角的 按鈕，即可定義新的範圍。
4. 在隨即顯示的「Add Scope」清單中，選取「Local」。

   本機和共用範圍都會用於專案中的「Inspect Code」功能。「Shared」範圍也可供其他具有範圍欄位的專案功能使用。例如，當您按一下「Edit Settings」圖示 變更「Find Usages」設定時，產生的對話方塊會顯示「Scope」欄位，供您選取共用的範圍。

   

5. 為範圍命名，然後按一下「OK」。

   「Scopes」對話方塊的右側窗格會填入可讓您定義自訂範圍的選項。

6. 在清單中選取「Project」。

   畫面會顯示可用的專案清單。

   注意：您可以為專案或套件建立自訂範圍。步驟相同。

7. 展開專案資料夾，選取要新增至自訂範圍的項目，然後選取是否要納入或排除該項目。

   

   • 「Include」：包含這個資料夾及其檔案，但不包含任何子資料夾。
   • 「Include Recursively」：包含這個資料夾及其檔案，以及子資料夾及其檔案。
   • 「Exclude」：排除這個資料夾及其檔案，但不排除任何子資料夾。
   • 「Exclude Recursively」：排除這個資料夾及其檔案、子資料夾及其檔案。

   圖 10 顯示了包含「main」資料夾，且以遞迴方式包含「java」和「res」資料夾。藍色表示部分包含的資料夾，綠色表示週期性包含的資料夾和檔案。

   

   • 如果您選取「java」資料夾，然後按一下「Exclude Recursively」，綠色醒目提示便不會出現在「java」資料夾以及所有資料夾和檔案上。
   • 如果選取標示綠色的「MainActivity.kt」檔案，然後按一下「Exclude」，則「MainActivity.kt」不會再以綠色醒目顯示，但「java」資料夾下的其他項目仍會以綠色醒目顯示。
8. 按一下「OK」。自訂範圍會顯示在清單底部。

查看及編輯檢查設定檔

Android Studio 提供一組 lint 和其他檢查設定檔，其會透過 Android 更新進行更新。您可以直接使用這些設定檔，也可以編輯名稱、說明、嚴重性和範圍。您也可以啟用及停用整個群組或群組中的個別設定檔。

如要存取「Inspections」設定，請按照下列步驟操作：

1. 依序選取「File」>「Settings」。(在 Windows 上) 或「Android Studio」>「Preferences」(在 macOS 或 Linux 上)。
2. 依序選取「Editor」>「Inspections」。

3. 「Inspections」窗格會顯示支援的檢查項目及其說明的清單。

   

4. 選取「Profile」清單，即可在「Default」 (Android Studio) 和「Project Default」 (啟用的專案) 的檢查之間切換。

   詳情請參閱 IntelliJ「管理設定檔」頁面。

5. 在左側窗格的「Inspections」清單中，選取頂層的設定檔分類，或展開一個群組然後選取特定的設定檔。

   選取設定檔類別後，您可以將該類別中的所有檢查項目編輯為單次檢查。

6. 選取「Show Schema Actions」 清單，即可複製、重新命名、新增說明、匯出及匯入檢查。
7. 完成後，請按一下「OK」。