除了建構測試來確認應用程式符合功能要求以外,您還必須使用 Lint 工具執行程式碼,確保程式碼不會發生結構問題。Lint 工具可找出結構不良的程式碼,找出可能影響 Android 應用程式的可靠性和效率,並導致程式碼更難以維護。強烈建議您在發布應用程式前,修正所有 Lint 偵測到的錯誤。
舉例來說,如果您的 XML 資源檔案包含未使用的命名空間,會佔用空間,並需要不必要的處理。其他結構問題,例如使用已淘汰的元素或目標 API 版本不支援的 API 呼叫,都可能導致程式碼無法正確執行。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 工具進行程式碼掃描工作流程。](https://developer.android.com/static/studio/images/write/lint.png?authuser=9&hl=zh-tw)
- 應用程式來源檔案
- 來源檔案包含 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
工作:
- 如使用 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 報告範例](https://developer.android.com/static/studio/images/write/html_lint_report.png?authuser=9&hl=zh-tw)
如果您的專案包含建構變數,Lint 只會檢查預設變化版本。如要在其他變化版本中執行 Lint,則必須將變化版本名稱大寫,並在前面加上 lint
。
./gradlew lintRelease
如要進一步瞭解如何透過指令列執行 Gradle 工作,請參閱「透過指令列建構應用程式」。
使用獨立工具執行 lint
如果您未使用 Android Studio 或 Gradle,請安裝 Android SDK 指令列工具,以便使用獨立的 Lint 工具。在 android_sdk/cmdline-tools/version/bin/lint
中找到 Lint 工具。
注意:如果您嘗試在 Gradle 專案中執行獨立工具,系統會顯示錯誤。在 Gradle 專案中執行 Lint 時,請一律使用 gradle lint
(Windows) 或 ./gradlew
lint
(macOS 或 Linux)。
如要對專案目錄中的檔案清單執行 Lint,請使用下列指令:
lint [flags] <project directory>
例如,您可以發出以下指令,掃描 myproject
目錄和其子目錄下的檔案。問題 ID MissingPrefix
會指示 lint 僅掃描缺少 Android 命名空間前綴的 XML 屬性。
lint --check MissingPrefix myproject
如要查看工具支援的旗標和指令列引數完整清單,請使用下列指令:
lint --help
以下範例顯示針對名為「地震」的專案執行 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
Preferences.xml
版面配置檔案相關:UnusedResources
。
有一個與 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
指令。
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 檢查功能:
- 依序選取「File」>「Settings」 (Windows) 或「Android Studio」>「Preferences」(macOS 或 Linux)。
- 依序選取「Editor」>「Inspections」。
- 如要停用,請取消選取適當的來源檔案。
如要為 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
問題。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()
中將問題設為嚴重錯誤,在主要 DSL 中會覆寫禁用。
建立警告基準
您可以為專案目前的警告擷取快照,然後使用該快照做為日後檢查的基準,這樣系統就只會回報新問題。基準快照可讓您開始使用 Lint 使建構失敗,而不需返回並先解決所有現有問題。
如要建立基準快照,請修改專案的 build.gradle
檔案,如下所示:
Kotlin
android { lint { baseline = file("lint-baseline.xml") } }
Groovy
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
檔案來指定要新增的問題:
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」視窗中。
設定檢查範圍和設定檔
選取您要分析的檔案 (檢查「範圍」) 和要執行的檢查 (檢查「設定檔」),如下所示:
- 在「Android」檢視畫面中開啟專案,然後選取要分析的專案、資料夾或檔案。
- 在選單列中,依序選取「Code」>「Inspect Code」。
在「Assign Inspection Scope」對話方塊中查看設定。
圖 3.查看檢查範圍設定。 「Assign Inspection Scope」對話方塊中顯示的選項,會因您選取的專案、資料夾或檔案而不同:
- 當您選取一項專案、檔案或目錄時,「Assign Inspection Scope」對話方塊會顯示所選專案、檔案或目錄的路徑。
- 當您選取多個專案、檔案或目錄時,「Assign Inspection Scope」對話方塊會顯示「Selected files」已選取的圓形按鈕。
如要變更要檢查的項目,請選取其他圓形按鈕。如需「指定檢查範圍」對話方塊中所有可能欄位的說明,請參閱指定檢查範圍對話方塊。
- 在「檢查設定檔」下方,選取要使用的設定檔。
按一下「OK」執行檢查。
圖 4 顯示「Inspect Code」執行中的 lint 和其他 IDE 檢查結果:
圖 4. 檢測結果。請選取問題來查看解決方法。 -
在「Inspection Results」窗格中,展開並選取錯誤類別、類型或問題來查看檢查結果。
「Inspection Report」窗格會顯示「Inspection Results」窗格中所選錯誤類別、類型或問題的檢查報告,並顯示錯誤的名稱和位置。在適用情況下,檢查報告會顯示其他資訊 (例如問題摘要),協助您修正問題。
在「Inspection Results」窗格樹狀檢視中,在類別、類型或問題上按一下滑鼠右鍵,即可顯示內容選單。
您可以根據情境,執行以下操作:
- 跳到來源。
- 排除並納入所選項目。
- 隱藏問題
- 編輯設定。
- 管理檢查快訊。
- 重新檢查。
如需工具列按鈕、內容選單項目和檢查報表欄位的說明,請參閱「 檢查結果工具視窗」。
使用自訂範圍
使用 Android Studio 提供的其中一個自訂範圍,如下所示:
- 在「指定檢查範圍」對話方塊中,選取「自訂範圍」。
按一下「自訂範圍」清單,以顯示選項:
圖 5.請選取要使用的自訂範圍。 - 所有位置:所有檔案。
- 「Project Files」:目前專案中的所有檔案。
- 「Project Source Files」:僅限目前專案中的來源檔案。
- 「Project Production Files」:僅限目前專案中的正式版檔案。
- 「Project Test Files」:僅限目前專案中的測試檔案。
- 暫存檔案和主控台:只有您在目前專案中開啟的暫存檔案和主控台。
- 最近查看的檔案:僅限目前專案中最近查看的檔案。
- 「Current File」:僅顯示目前專案中的檔案。在選取檔案或資料夾時顯示。
- 已選取的目錄:僅限目前專案中的資料夾。當您選取資料夾時,畫面上就會顯示這個圖示。
- 「Class Hierarchy」:選取這個選項並按一下「OK」後,系統會顯示對話方塊,列出目前專案中的所有類別。在對話方塊中,使用「Search by Name」(依名稱搜尋) 欄位篩選及選取要檢查的類別。如果您未篩選類別清單,程式碼檢查功能會檢查所有類別。
如果專案已設定 VCS,您也可以選擇將搜尋範圍限制在經過修改的檔案。
- 按一下「OK」。
建立自訂範圍
如要檢查不在任何現有自訂範圍涵蓋範圍內的特定檔案和目錄,您可以建立自訂範圍:
- 在「Specify Inspection Scope」對話方塊中,選取「Custom scope」。
按一下「自訂範圍」清單後方的三點圖示。
圖 6.指定檢查範圍對話方塊。 系統會隨即顯示「Scopes」對話方塊。
圖 7.建立自訂範圍。 - 按一下對話方塊左上角的
按鈕,定義新範圍。
- 在隨即顯示的「Add Scope」(新增範圍) 清單中,選取「Local」(本機)。
本機和共用範圍都會用於專案中的「Inspect Code」功能。「Shared」範圍也可供其他具有範圍欄位的專案功能使用。例如,當您按一下「Edit Settings」圖示
變更「Find Usages」設定時,產生的對話方塊會顯示「Scope」欄位,供您選取共用的範圍。
圖 8.從「Find Usages」對話方塊中選取共用範圍。 - 為範圍命名,然後按一下「OK」。
「Scopes」對話方塊的右側窗格會填入可讓您定義自訂範圍的選項。
- 從清單中選取「專案」。
畫面會顯示可用的專案清單。
注意:您可以為專案或套件建立自訂範圍。相關步驟相同。
展開專案資料夾,選取要新增至自訂範圍的項目,然後選取要納入或排除該資料夾。
圖 9.定義自訂範圍。 - 「Include」:包含這個資料夾及其檔案,但不包含所屬的任何子資料夾。
- 「Include Recursative」(包含遞迴):包含這個資料夾及其檔案,以及其子資料夾和當中的檔案。
- 「Exclude」:排除這個資料夾及其檔案,但不排除任何子資料夾。
- 「Exclude Recursative」(排除遞迴):排除這個資料夾及其檔案,以及其子資料夾和當中的檔案。
圖 10 顯示包含「main」資料夾,且以遞迴方式包含「java」和「res」資料夾。藍色表示部分包含的資料夾,綠色表示週期性包含的資料夾和檔案。
圖 10.自訂範圍的模式範例。 - 如果您選取「java」資料夾,然後按一下「Exclude Recursally」,則「java」資料夾及下方的所有資料夾和檔案都會消失。
- 如果您選取以綠色醒目顯示的 MainActivity.kt 檔案,然後按一下「Exclude」,MainActivity.kt 不會再顯示為綠色,但「java」資料夾下的其餘項目仍會呈現綠色。
- 按一下「OK」。自訂範圍會顯示在清單底部。
查看及編輯檢查設定檔
Android Studio 提供一組 Lint 和其他檢查設定檔,可透過 Android 更新更新。您可以沿用這些剖析資料,也可以編輯名稱、說明、嚴重性和範圍。您也可以啟用及停用整個群組或群組中的個別設定檔。
如要存取「檢查」設定,請按照下列步驟操作:
- 依序選取「File」>「Settings」。(Windows) 或「Android Studio」>「Preferences」(偏好設定) (macOS 或 Linux)。
- 依序選取「Editor」>「Inspections」。
選取「Profile」清單,即可在「Default」 (Android Studio) 和「Project Default」 (進行中的專案) 檢查之間切換。
詳情請參閱 IntelliJ「管理設定檔」頁面。
在左側窗格的「Inspections」清單中,選取頂層設定檔類別,或展開一個群組並選取特定的設定檔。
選取特定設定檔類別後,您可以將該類別中的所有檢查項目編輯為單一檢查。
- 選取「Show Schema Actions」
清單,即可複製、重新命名、新增說明、匯出及匯入檢查。
- 完成後,請按一下「OK」。
「Inspections」窗格會顯示支援的檢查項目及其說明清單。
![支援的檢查項目與相關說明](https://developer.android.com/static/studio/images/write/inspectionprofiles_2x.png?authuser=9&hl=zh-tw)