在 Python 項(xiàng)目中使用 Pylint 進(jìn)行靜態(tài)代碼檢查，可以大大提升代碼質(zhì)量與一致性。與其每次在命令行里堆一長(zhǎng)串參數(shù)，不如通過(guò) pylintrc 統(tǒng)一管理配置：忽略哪些規(guī)則、命名規(guī)范如何定義、導(dǎo)入路徑如何設(shè)置等等。

本文從零開始，介紹：

1. Pylint 基本使用方法
2. pylintrc 的來(lái)源與優(yōu)先級(jí)
3. 如何生成、放置和加載 pylintrc
4. 常用配置段落詳解（消息控制、命名規(guī)范、路徑、格式等）
5. 在項(xiàng)目中落地的推薦實(shí)踐

一、Pylint 簡(jiǎn)要回顧

1. 安裝 Pylint

pip install pylint
# 或使用特定環(huán)境：
python -m pip install pylint

2. 基本使用示例

最簡(jiǎn)單的調(diào)用：

pylint your_module.py
pylint package_name

默認(rèn)情況下，Pylint 會(huì)使用內(nèi)置規(guī)則進(jìn)行檢查，給出 0–10 分的評(píng)分，并打印所有問(wèn)題。

但隨著項(xiàng)目復(fù)雜度變大，僅用命令行參數(shù)配置已不現(xiàn)實(shí)，這時(shí)就需要使用 pylintrc 進(jìn)行集中配置。

二、pylintrc 配置文件的來(lái)源與優(yōu)先級(jí)

Pylint 的配置文件名稱通常為：

• .pylintrc（項(xiàng)目根目錄常用）
• pylintrc

Pylint 查找配置文件的一般順序?yàn)椋ǜ拍钌希?/p>

1. 命令行參數(shù)指定的配置文件：

pylint --rcfile=path/to/your_pylintrc package_name

1. 當(dāng)前目錄及父目錄中的 .pylintrc 或 pylintrc
2. 用戶主目錄中的配置（如 ~/.pylintrc）
3. 全局系統(tǒng)級(jí)配置（如果存在）

一旦找到一個(gè)有效的配置文件，后續(xù)更高層級(jí)通常不會(huì)再繼續(xù)覆蓋（除非你在命令行再次指定不同的 --rcfile）。

推薦做法：
在每個(gè)獨(dú)立項(xiàng)目的根目錄下維護(hù)一個(gè) .pylintrc，保證項(xiàng)目?jī)?nèi)統(tǒng)一規(guī)則，避免依賴“全局”配置互相影響。

三、如何生成與使用 pylintrc

1. 生成初始模板

Pylint 提供了一個(gè)快速生成配置文件的命令：

pylint --generate-rcfile > .pylintrc

或者：

pylint --generate-rcfile > pylintrc

這會(huì)生成一個(gè)包含所有可用選項(xiàng)的完整配置文件（注釋說(shuō)明很詳細(xì)）。然后你可以按項(xiàng)目需要慢慢裁剪、修改。

2. 指定使用哪個(gè) pylintrc

如果你的配置文件名不是默認(rèn)的 .pylintrc，或者不在當(dāng)前目錄，可以使用 --rcfile 指定：

pylint --rcfile=config/pylintrc src/

在 CI 腳本或開發(fā)文檔中，把這一調(diào)用寫死，確保所有人用同一套配置。

四、pylintrc 的主要配置段落詳解

生成的 .pylintrc 非常長(zhǎng)，實(shí)際常用的主要集中在：

• [MASTER]（或新版本中的 [MAIN]）
• [MESSAGES CONTROL]
• [BASIC]
• [FORMAT]
• [DESIGN]
• [IMPORTS]
• [TYPECHECK]（有時(shí)會(huì)用到）

下面按使用頻率與重要性介紹。

4.1[MASTER]（或[MAIN]）——項(xiàng)目級(jí)別總控制

示例：

[MASTER]
# 要檢查的 Python 版本，有助于啟用/禁用特定規(guī)則。
py-version = 3.10
# 忽略的目錄/文件（相對(duì)于運(yùn)行 pylint 的路徑）。
ignore = migrations, build, dist
ignore-patterns = .*_pb2\.py
# 指定額外的導(dǎo)入路徑（相當(dāng)于在 sys.path 中追加）。
init-hook = 
    import sys, os;
    sys.path.append(os.path.abspath("src"))

說(shuō)明：

• py-version：指明項(xiàng)目目標(biāo) Python 版本，避免為不支持的語(yǔ)法報(bào)錯(cuò)。
• ignore：直接忽略整個(gè)目錄或文件夾名，例如編譯產(chǎn)物、第三方代碼、自動(dòng)生成代碼等。
• ignore-patterns：使用正則忽略文件名，適合 protobuf、API 自動(dòng)生成文件等。
• init-hook：在 Pylint 啟動(dòng)前執(zhí)行一小段 Python 代碼。常用于處理項(xiàng)目根路徑、虛擬環(huán)境路徑等。

4.2[MESSAGES CONTROL]——控制啟用/禁用的檢查規(guī)則

示例：

[MESSAGES CONTROL]
# 全局禁用的消息
disable =
    C0114,  # missing-module-docstring
    C0115,  # missing-class-docstring
    C0116,  # missing-function-docstring
    R0903,  # too-few-public-methods
    W0511,  # fixme (TODO/FIXME 注釋)
    C0103,  # invalid-name (有些團(tuán)隊(duì)喜歡更靈活的命名)
# 也可以啟用一些默認(rèn)關(guān)閉的規(guī)則（較少使用）
enable =
    useless-suppression

說(shuō)明：

每條消息規(guī)則都有一個(gè)“符號(hào)名”和“數(shù)字 ID”，例如：

• missing-module-docstring 對(duì)應(yīng) C0114
• too-many-arguments 對(duì)應(yīng) R0913

disable 中可以寫：

• 數(shù)字 ID：C0114
• 符號(hào)名：missing-module-docstring

一般推薦使用符號(hào)名，可讀性更強(qiáng)，比如：

disable =
    missing-module-docstring,
    missing-class-docstring,
    missing-function-docstring

局部禁用：
有時(shí)只想在某一行/某個(gè)函數(shù)禁用某條規(guī)則，可以用注釋：

# 禁用當(dāng)前行的 invalid-name 檢查
x = 1  # pylint: disable=invalid-name

# 禁用整個(gè)函數(shù)的 too-many-locals 檢查
def complicated():  # pylint: disable=too-many-locals
    ...

4.3[BASIC]——命名規(guī)范與基礎(chǔ)規(guī)則

示例：

[BASIC]
# 模塊、類、函數(shù)、變量命名風(fēng)格
variable-rgx = [a-z_][a-z0-9_]*$
function-rgx = [a-z_][a-z0-9_]*$
method-rgx   = [a-z_][a-z0-9_]*$
class-rgx    = [A-Z][a-zA-Z0-9]+$

# 允許的常量命名（全大寫）
const-rgx    = ([A-Z_][A-Z0-9_]*)|(__.*__)$

# 不進(jìn)行命名檢查的變量名（常見于循環(huán)計(jì)數(shù)、棄用變量）
good-names = 
    i,
    j,
    k,
    x,
    y,
    z,
    _

說(shuō)明：

• xxx-rgx 用正則定義命名規(guī)則，覆蓋了大多數(shù) PyLint 的“命名不規(guī)范”告警。
• good-names：白名單變量名，即使不符規(guī)則也不報(bào)錯(cuò)。
• 有些團(tuán)隊(duì)比較寬松，可以把 C0103（invalid-name）禁掉，而不是精細(xì)配置正則。

4.4[FORMAT]——代碼風(fēng)格（行寬、縮進(jìn)等）

示例：

[FORMAT]
# 最大行寬
max-line-length = 100

# 單行中的最大導(dǎo)入數(shù)量
max-module-lines = 1000

# 縮進(jìn)字符與縮進(jìn)大小
indent-string = '    '
indent-after-paren = 4

說(shuō)明：

• max-line-length 是最常用的選項(xiàng)之一，建議和 Black/Flake8 等工具對(duì)齊，比如統(tǒng)一用 88 或 100。
• 許多團(tuán)隊(duì)會(huì)用 Black 做格式化，Pylint 只提供警告提示，你可以：
  • 在 Pylint 中放寬行寬；
  • 或者在 CI 中用 Black 格式化后再跑 Pylint。

4.5[DESIGN]——復(fù)雜度與結(jié)構(gòu)相關(guān)規(guī)則

示例：

[DESIGN]
# 函數(shù)允許的最大參數(shù)個(gè)數(shù)
max-args = 6

# 函數(shù)允許的最大局部變量數(shù)
max-locals = 15

# 函數(shù)允許的最大分支數(shù)（if/for/while/try...）
max-branches = 12

# 函數(shù)允許的最大語(yǔ)句數(shù)
max-statements = 50

# 類允許的最大公共方法數(shù)
max-public-methods = 20

說(shuō)明：

• 這些限制幫助你控制函數(shù)/類的復(fù)雜度。
• 具體數(shù)值要結(jié)合團(tuán)隊(duì)實(shí)際情況調(diào)優(yōu)，否則 Pylint 會(huì)“過(guò)于嘮叨”。
• 如果某個(gè)函數(shù)確實(shí)合理地復(fù)雜，可以用局部禁用（# pylint: disable=too-many-branches）加注釋說(shuō)明。

4.6[IMPORTS]——導(dǎo)入相關(guān)檢查

示例：

[IMPORTS]
# 允許的相對(duì)導(dǎo)入的最大層級(jí)
# 建議在現(xiàn)代項(xiàng)目中優(yōu)先使用絕對(duì)導(dǎo)入
known-standard-library = os, sys, json
known-third-party = requests, flask, django
known-first-party = myproject

說(shuō)明：

• 某些舊項(xiàng)目喜歡大量相對(duì)導(dǎo)入（from .. import x），你可以通過(guò)規(guī)則限制。
• known-* 系列主要用于 import 排序與分組（與 isort 配合更好）。

4.7 其他常用段落

[TYPECHECK]

[TYPECHECK]
# 忽略無(wú)法導(dǎo)入的模塊，防止“import-error”太多干擾
ignored-modules =
    some_optional_dependency

如果運(yùn)行 Pylint 的環(huán)境里缺少某些第三方庫(kù)（但生產(chǎn)環(huán)境有），可以把這些模塊加入忽略列表，避免大量誤報(bào)。

[LOGGING]

[LOGGING]
logging-modules = logging

控制 log 調(diào)用的檢查，例如是否使用正確的格式化方式等。

五、典型項(xiàng)目的 pylintrc 示例

下面給出一個(gè)常見的、相對(duì)“務(wù)實(shí)”的項(xiàng)目配置示例，可直接作為模板：

[MASTER]
py-version = 3.10
ignore = build, dist, .venv, migrations
ignore-patterns = .*_pb2\.py
init-hook = 
    import sys, os;
    sys.path.append(os.path.abspath("src"))

[MESSAGES CONTROL]
disable =
    missing-module-docstring,
    missing-class-docstring,
    missing-function-docstring,
    missing-return-doc,      # 如果你用 type hints 和文檔工具，可以酌情禁用
    too-few-public-methods,
    invalid-name,
    fixme

[BASIC]
good-names =
    i,
    j,
    k,
    x,
    y,
    z,
    _,
    db,
    pk,
    id

[FORMAT]
max-line-length = 100
indent-string = '    '
indent-after-paren = 4

[DESIGN]
max-args = 6
max-locals = 15
max-branches = 12
max-statements = 50
max-public-methods = 20

[TYPECHECK]
ignored-modules =
    my_optional_lib

[IMPORTS]
known-first-party = myproject

你可以從這個(gè)模板出發(fā)，根據(jù)團(tuán)隊(duì)約定和項(xiàng)目特點(diǎn)逐步調(diào)整。

六、結(jié)合命令行與 CI 的使用方式

1. 日常本地使用

在項(xiàng)目根目錄有 .pylintrc 后，本地檢查非常簡(jiǎn)單：

# 在項(xiàng)目根目錄
pylint src/ tests/

如需臨時(shí)使用另一份配置：

pylint --rcfile=.pylintrc-strict src/

2. 在 CI 中集成

典型 CI（如 GitHub Actions）腳本片段：

- name: Install dependencies
  run: |
    pip install -r requirements.txt
    pip install pylint
- name: Run Pylint
  run: |
    pylint src/ tests/

建議：

• 先在本地讓團(tuán)隊(duì)成員跑通并接受告警級(jí)別，再把規(guī)則固化到 CI 中，避免一上來(lái)就“告警爆炸”導(dǎo)致大家反感。
• 必要時(shí)可以設(shè)置“過(guò)渡期配置”：先禁一些規(guī)則（在 .pylintrc 里 disable），代碼質(zhì)量穩(wěn)定后再逐步收緊。

七、使用 pylintrc 的一些實(shí)踐經(jīng)驗(yàn)

先跑默認(rèn)規(guī)則，觀察實(shí)際項(xiàng)目的告警類型

• 把“業(yè)務(wù)無(wú)法接受的大量誤報(bào)”的規(guī)則先禁掉。
• 對(duì)傳統(tǒng)代碼庫(kù)，適當(dāng)放寬命名/復(fù)雜度限制是常態(tài)。

與其它工具對(duì)齊

• 與 Black / isort / Flake8 明確邊界：
  • 格式化交給 Black，Pylint 主要管邏輯和結(jié)構(gòu)。
  • 導(dǎo)入順序交給 isort，Pylint 僅對(duì)明顯錯(cuò)誤導(dǎo)入進(jìn)行提示。

分階段治理

• 老項(xiàng)目可以按目錄分階段開啟 Pylint：
  • 新代碼目錄使用較嚴(yán)格規(guī)則；
  • 舊代碼暫時(shí) relax，一點(diǎn)點(diǎn)“清債”。

善用局部禁用

• 對(duì)極特殊的函數(shù)或模塊，在注釋中寫清原因并局部禁用特定規(guī)則，而不是全局一刀切。

八、小結(jié)

使用 pylintrc 的核心目標(biāo)是：把“代碼風(fēng)格和質(zhì)量標(biāo)準(zhǔn)”寫成可執(zhí)行配置，并讓整個(gè)團(tuán)隊(duì)用同一套規(guī)則。

關(guān)鍵步驟回顧：

安裝 Pylint，并在項(xiàng)目根目錄生成 .pylintrc：

pylint --generate-rcfile > .pylintrc

根據(jù)項(xiàng)目實(shí)際需求調(diào)整：

• 在 [MESSAGES CONTROL] 中禁用/啟用規(guī)則；
• 在 [BASIC] 自定義命名規(guī)范；
• 在 [FORMAT] 統(tǒng)一行寬和縮進(jìn)；
• 在 [DESIGN] 控制復(fù)雜度。

本地和 CI 中統(tǒng)一調(diào)用：

pylint src/ tests/

到此這篇關(guān)于使用pylintrc配置Python代碼檢查的詳細(xì)指南的文章就介紹到這了,更多相關(guān)pylintrc配置Python代碼檢查內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論