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

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

例如,如果您的 XML 資源檔案包含未使用的命名空間,就會佔用空間,並需要進行不必要的處理。其他結構問題,例如使用已淘汰的元素或目標 API 版本不支援的 API 呼叫,都可能導致程式碼無法正確執行。Lint 可協助您處理這些問題。

如要改善 Lint 效能,您也可以在程式碼中加入註解

總覽

Android Studio 提供名為 Lint 的程式碼掃描工具,可協助您找出並修正程式碼結構品質的問題,而不必執行應用程式或編寫測試案例。這項工具偵測到的每個問題都會提供說明訊息和嚴重性等級,方便您優先處理需要做出的重要改善。您也可以降低問題的嚴重性等級,忽略與專案無關的問題,或是提高嚴重性等級來醒目顯示特定問題。

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

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

  • 在編輯器視窗中以彈出式文字顯示。當 Lint 發現問題時,會以黃色醒目顯示有問題的程式碼。如果是更嚴重的問題,代碼會以紅色底線標示。
  • 依序按一下「Code」>「Inspect Code」,在 lint 的「Inspection Results」視窗中查看。

注意:程式碼在 Android Studio 中編譯後,系統會另外執行 IntelliJ 程式碼檢查作業,簡化程式碼審查流程。

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

使用 Lint 工具進行程式碼掃描工作流程。
圖 1.使用 Lint 工具進行程式碼掃描工作流程。
應用程式來源檔案
來源檔案包含構成 Android 專案的檔案,包括 Kotlin、Java 和 XML 檔案、圖示和 ProGuard 設定檔。
lint.xml檔案
設定檔,可用於指定任何要排除的 Lint 檢查,並自訂問題嚴重性等級。
lint 工具
可透過指令列或 Android Studio 在 Android 專案中執行的靜態程式碼掃描工具。Lint 工具會檢查可能影響 Android 應用程式品質和效能的結構程式碼問題。
lint 檢查結果
您可以在控制台或 Android Studio 的「Inspection Results」視窗中查看 Lint 的結果。如果透過指令列執行 lint,系統會將結果寫入 build/ 資料夾。詳情請參閱「手動執行檢查」一節。

透過指令列執行 lint

如果您使用的是 Android Studio 或 Gradle,請使用 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 所示。

HTML Lint 報告範例
圖 2. HTML Lint 報告範例。

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

./gradlew lintRelease

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

使用獨立工具執行 lint

如果您不是使用 Android Studio 或 Gradle,請安裝 Android SDK 指令列工具,以便使用獨立的 Lint 工具。在 android_sdk/cmdline-tools/version/bin/lint 找出 Lint 工具。

注意:如果您嘗試在 Gradle 專案中執行獨立工具,則會發生錯誤。在 Gradle 專案中,您應一律使用 gradle lint (Windows) 或 ./gradlew lint (macOS 或 Linux) 執行 Lint。

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

lint [flags] <project directory>

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

lint --check MissingPrefix myproject 

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

lint --help

以下範例顯示 Lint 指令對名為 Earthquake 的專案執行時,控制台輸出內容:

$ 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
有一則警告與 Preferences.xml 版面配置檔案有關:UnusedResources

有一項警告與 res 目錄相關:IconMissingDensityFolder

設定 Lint 以隱藏警告

根據預設,當您執行 Lint 掃描時,工具會檢查 Lint 支援的所有問題。您也可以限制 Lint 檢查的問題,以及指派問題的嚴重性等級。舉例來說,您可以隱藏 Lint 檢查,找出與專案無關的特定問題,並設定 Lint,以較低的嚴重性等級回報非重大問題。

嚴重性等級為:

  • enable
  • disableignore
  • 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 指令。

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」>「Inspects」
  3. 如要停用,請取消選取適當的來源檔案。

如要為 IDE 或個別專案設定這些設定,請選取適當的設定檔。

在 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);

也可以在任何可組合項中完成相同操作。下列程式碼片段說明如何關閉任何可組合項的 NewApi 檢查。

Kotlin

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

以下範例說明如何為 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")

您可以使用相同註解,隱藏任何可組合函式的 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 選項

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

下列程式碼片段說明您可以設定的部分屬性:

Kotlin

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
    }
}
...

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 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 方法都會遵循設定順序。例如,在 finalizeDsl() 中將問題設為「fatal」,即可在主要 DSL 中覆寫問題的「disable」等級。

建立警告基準

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

如要建立基準快照,請修改專案的 build.gradle 檔案,如下所示:

Kotlin

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

Groovy

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

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

接著,依序選取「Code」>「Inspect Code」,從 IDE 執行 Lint,或者從指令列執行 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 檔案以指定要新增的問題:

Kotlin

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

Groovy

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. 在「指定檢查範圍」對話方塊中查看設定。

    指定檢查範圍
    圖 3.查看檢查範圍設定。

    「指定檢查範圍」對話方塊中顯示的選項會因您選取的專案、資料夾或檔案而異:

    • 當您選取專案、檔案或目錄時,「指定檢查範圍」對話方塊會顯示所選專案、檔案或目錄的路徑。
    • 當您選取多個專案、檔案或目錄時,「指定檢查範圍」對話方塊會顯示「已選取的檔案」圓形按鈕。

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

  4. 在「Inspection profile」下方,選取要使用的設定檔。
  5. 按一下「OK」執行檢查。

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

    選取問題即可查看解決方法。
    圖 4. 檢測結果。選取問題即可查看解決方案。
  6. 在「Inspection Results」窗格中,展開並選取錯誤類別、類型或問題來查看檢查結果。

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

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

    視情境而定,您可以:

    • 跳至來源。
    • 排除與納入所選項目。
    • 隱藏問題。
    • 編輯設定。
    • 管理檢查快訊。
    • 重新執行檢查。

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

使用自訂範圍

請使用 Android Studio 提供的其中一個自訂範圍,如下所示:

  1. 在「指定檢查範圍」對話方塊中,選取「自訂範圍」
  2. 按一下「Custom 範圍」清單,即可查看選項:

    選擇檢查範圍
    圖 5.請選取您要使用的自訂範圍。
    • 所有位置:所有檔案。
    • 「Project Files」:目前專案中的所有檔案。
    • 「Project Source Files」僅限目前專案中的來源檔案。
    • 「Project Production Files」僅限目前專案中的正式版檔案。
    • 「Project Test Files」:僅限目前專案中的測試檔案。
    • 「Scratches and Consoles」:只有您在目前專案中開啟的暫存檔案和控制台。
    • 最近查看的檔案:只查看目前專案中的檔案。
    • 「Current File」僅顯示目前專案中的檔案。在選取檔案或資料夾時顯示。
    • 「Selected Directory」:僅限目前專案中的資料夾。選取資料夾後就會顯示。
    • 「Class Hierarchy」:選取這個選項後點選「OK」,系統會顯示對話方塊,其中含有目前專案中的所有類別。在對話方塊中,使用「Search by Name」欄位篩選並選取要檢查的類別。如果您未篩選類別清單,程式碼檢查功能會檢查所有類別。

    如果您已為專案設定 VCS,您也可以透過其他選項將搜尋範圍限制在修改過的檔案。

  3. 按一下「OK」

建立自訂範圍

如要檢查不在任何現有自訂範圍範圍內的檔案和目錄,您可以建立自訂範圍:

  1. 在「Specify Inspection Scope」對話方塊中,選取「Custom scope」
  2. 按一下「Custom Scope」(自訂範圍) 清單後方的三點圖示。

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

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

    建立自訂範圍
    圖 7.建立自訂範圍。
  3. 按一下對話方塊左上角的 按鈕定義新範圍。
  4. 在隨即顯示的「Add Scope」(新增範圍) 清單中,選取「Local」

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

    從「Find Usages」對話方塊中選取共用範圍。
    圖 8.從「Find Usages」對話方塊中選取共用範圍。
  5. 為範圍命名,然後按一下「OK」

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

  6. 從清單中選取「Project」

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

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

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

    定義自訂範圍
    圖 9.定義自訂範圍。
    • 「Include」:包含這個資料夾及其檔案,但不包含所屬的任何子資料夾。
    • 「包含遞迴」:包含這個資料夾及其檔案,以及其中的子資料夾及其檔案。
    • 「Exclude」:排除這個資料夾及其檔案,但不排除任何子資料夾。
    • 「排除遞迴」:排除這個資料夾及其檔案,以及其中的子資料夾及其檔案。

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

    自訂範圍的範例
    圖 10.自訂範圍的範例。
    • 如果您選取「java」資料夾,然後按一下「Exclude Recursative」,「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」>「Inspects」
  3. 「Inspections」窗格會顯示支援的檢查項目及說明的清單。

    支援的檢查項目與相關說明
    圖 11.支援的檢查項目及其說明。
  4. 選取「Profile」清單,即可在「Default」 (Android Studio) 和「Project Default」 (進行中的專案) 檢查之間切換。

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

  5. 在左側窗格的「Inspections」清單中,選取頂層設定檔類別,或是展開群組並選取特定設定檔。

    選取設定檔類別後,您可以單獨檢查該類別中的所有檢查項目。

  6. 選取「Show Schema Actions」(顯示結構定義動作) 顯示結構定義動作圖示 清單,即可複製、重新命名、新增說明、匯出及匯入檢查。
  7. 完成後,請按一下「OK」