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

除了建立測試確保應用程式符合功能要求之外，您還必須透過 lint 執行程式碼，確保程式碼沒有任何結構問題。Lint 工具可協助您找出結構不良的程式碼，這類程式碼會影響 Android 應用程式的可靠性和效率，並讓程式碼難以維護。

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

如要進一步提高程式碼檢查效能，建議您在程式碼中添加註解。

總覽

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

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

注意：如果您的程式碼在 Android Studio 中編譯完畢，還會執行額外的 IntelliJ 程式碼檢查，以簡化程式碼審查作業。

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

圖 1. 使用 Lint 工具進行程式碼掃描工作流程

應用程式來源檔案
來源檔案包含構成 Android 專案的檔案，包括 Java、Kotlin 和 XML 檔案、圖示和 ProGuard 設定檔。
lint.xml檔案
設定檔，可用於指定任何要排除的 Lint 檢查，並自訂問題嚴重性等級。
lint 工具
可透過指令列或 Android Studio 執行的靜態程式碼掃描工具 (請參閱手動執行檢查作業)。lint 工具會檢查可能影響 Android 應用程式品質和效能的結構程式碼問題。強烈建議您在發布應用程式前，修正所有 Lint 偵測出的錯誤。
lint 檢查結果
您可以在主控台或 Android Studio 的「Inspection Results」視窗中查看 Lint 的結果。請參閱手動執行檢查。

透過指令列執行 lint

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

  • Windows 系統：
    gradlew lint
  • Linux 或 Mac：
    ./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 所示。

圖 2. HTML Lint 報告範例

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

./gradlew lintRelease

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

使用獨立工具執行 lint

如果您未使用 Android Studio 或 Gradle，從 SDK Manager 安裝 Android SDK 指令列工具後，即可使用獨立的 Lint 工具。接著，您可以在 android_sdk/cmdline-tools/version/bin/lint 中找到 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 和 UnusedResources)，以及在 Preferences.xml 版面配置檔案中的一個警告(IconMissingDensityFolder)。

設定 Lint 以隱藏警告

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

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

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

在 Android Studio 中設定 Lint

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

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

設定 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>

您可以在 <issue> 標記中設定嚴重性屬性，藉此變更問題的嚴重性等級或停用 Lint 檢查功能。

提示：如要查看 Lint 支援問題的完整清單和對應的問題 ID，請執行 lint --list 指令。

lint.xml 檔案範例

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

<?xml version="1.0" encoding="UTF-8"?>
<lint>
    <!-- Disable the given 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>

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

您可以停用 Lint 檢查 Java、Kotlin 和 XML 來源檔案。

提示：您可以在「Default Preferences」(預設偏好設定) 對話方塊中管理 Java、Kotlin 或 XML 來源檔案的 Lint 檢查功能。依序選取「File」>「Other Settings」>「Default Settings」，然後在「Default Preferences」對話方塊的左側窗格中，依序選取「Editor」>「Inspections」。

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

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

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

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

Kotlin

@SuppressLint("all")

Java

@SuppressLint("all")

設定 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 選項

Gradle 的 Android 外掛程式可讓您使用模組層級 build.gradle 檔案中的 lint{} 區塊，以設定某些 lint 選項，例如執行或忽略哪些檢查項目。下列程式碼片段顯示您可設定的部分屬性：

Groovy

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 true, only report errors.
        ignoreWarnings true
        // If true, lint also checks all dependencies as part of its analysis. Recommended for
        // projects consisting of an app with library dependencies.
        checkDependencies true
    }
}
...

Kotlin

android {
    ...
    lintOptions {
        // Turns off checks for the issue IDs you specify.
        disable("TypographyFractions")
        disable("TypographyQuotes")
        // Turns on checks for the issue IDs you specify. These checks are in
        // addition to the default lint checks.
        enable("RtlHardcoded")
        enable("RtlCompat")
        enable("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 true, only report errors.
        ignoreWarnings = true
        // If true, lint also checks all dependencies as part of its analysis. Recommended for
        // projects consisting of an app with library dependencies.
        isCheckDependencies = true
    }
}
...

用於覆寫特定問題嚴重性等級的所有 lint 方法：enable、disable/ignore、informational、warning、error、fatal：請遵守設定順序。例如，在 finalizeDsl() 中將問題設為嚴重錯誤，在主要 DSL 中會覆寫禁用。

建立警示基準

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

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

Groovy

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

Kotlin

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

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

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

$ ./gradlew lintDebug

...

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 來新增問題：

Groovy

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

Kotlin

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

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

基準警示

當基準生效時，您會收到資訊警告，表示有一或多個問題遭到篩除，因其已列入基準。這則警告是為了提醒您，您已經設定基準，因為若能修正所有問題是最理想的情況。

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

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

手動執行檢查

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

設定檢查範圍和設定檔

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

  1. 在「Android」檢視畫面中開啟專案，選取您要分析的專案、資料夾或檔案。
  2. 從選單列中，依序選取「Analyze」> 「Inspect Code」。
  3. 在「Specify Inspection Scope」對話方塊中查看設定。指定檢查範圍

    圖 3. 查看檢查範圍設定

    「Specify Inspection Scope」對話方塊中顯示的選項組合，會因您選取的專案、資料夾或檔案而改變。您可以選取其他圓形按鈕，變更要檢查的項目。如需「Specify Inspection Scope」對話方塊中所有可能欄位的說明，請參閱指定檢查範圍對話方塊。

    • 當您選取了一個專案、檔案或目錄時，「Specify Inspection Scope」對話方塊會顯示您所選取的「Project」、「File」或「Directory」的路徑。
    • 當您選取多個專案、檔案或目錄時，「Specify Inspection Scope」對話方塊會為「Selected files」顯示已勾選的圓形按鈕。
  4. 在「Inspection profile」下，保留預設的設定檔 (「Project Default」)。
  5. 按一下「OK」執行檢查。圖 4 顯示了「Inspect Code」執行作業中的 lint 和其他 IDE 檢查結果：

    圖 4. 選取問題即可查看解決方案

  6. 在左側的窗格中，透過展開並選取錯誤類別、類型和問題來查看檢查結果。

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

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

    根據您的背景資訊，您可以進行以下某些或部分操作：跳至來源、排除和納入所選項目、隱藏問題、編輯設定、管理檢查快訊，以及重新執行檢查。

有關左側工具列按鈕、內容選單項目和檢查報告欄位的說明，請參閱「檢查工具視窗」。

使用自訂範圍

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

  1. 在「Specify Inspection Scope」對話方塊中，按一下「Custom scope」。
  2. 按一下「Custom scope」下拉式清單即可顯示選項。

    選擇檢查範圍

    圖 5. 選取要使用的自訂範圍

    • 「Project Files」：目前專案中的所有檔案。
    • 「Project Production Files」：僅限目前專案中的正式版檔案。
    • 「Project Test Files」：僅限目前專案中的測試檔案。請參閱測試類型和位置。
    • 「Open Files」：僅顯示您在目前專案中開啟的檔案。
    • 「Module <your-module>」：僅顯示目前專案中對應模組資料夾中的檔案。
    • 「Current File」：僅顯示目前專案中的檔案。在選取檔案或資料夾時顯示。
    • 「Class Hierarchy」：選取這個選項然後按一下「OK」後，畫面上會出現一個對話方塊，其中列出了目前專案中的所有類別。使用對話方塊中的「Search by Name」欄位來篩選並選取要檢查的類別。如果您未篩選類別清單，程式碼檢查功能會檢查所有類別。
  3. 按一下「OK」。

建立自訂範圍

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

  1. 在「Specify Inspection Scope」對話方塊中，選取「Custom scope」。
  2. 按一下「Custom scope」下拉式清單中後方的三個點。

    圖 6. 指定檢查範圍對話方塊

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

    圖 7. 建立自訂範圍

  3. 按一下「Add」 定義新的範圍。
  4. 在隨後顯示的「Add Scope」下拉式清單中，選取「Local」。

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

    圖 8. 從「Find Usages」對話方塊中選取共用範圍

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

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

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

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

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

  7. 展開專案資料夾，選取要新增至自訂範圍的項目，然後按一下右側的其中一個按鈕。

    圖 9.定義自訂範圍

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

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

    圖 10.自訂範圍的範例

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

查看及編輯檢查設定檔

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

如要存取「Inspections」對話方塊：

  1. 依序選取「Analyze」>「Inspect Code」。
  2. 在「Inspection profile」下的「Specify Scope」 對話方塊中，按一下「More」。

    「Inspections」對話方塊會顯示支援檢查項目及其說明的清單。

    圖 11. 支援的檢查項目與相關說明

  3. 選取「Profile」下拉式清單，即可在「Default」(Android Studio) 和「Project Default」(啟用的專案) 的檢查之間切換。詳情請參閱這個 IntelliJ 指定檢查範圍對話方塊頁面。
  4. 在左側窗格的「Inspections」對話方塊中，選取頂層的設定檔分類，或展開一個群組然後選取一個特定的設定檔。選取設定檔類別後，您可以將該類別中的所有檢查項目編輯為單次檢查。
  5. 選取「Manage」下拉式清單，即可複製、重新命名、新增說明、匯出及匯入檢查。
  6. 完成後，請按一下「OK」。