pylint配置文件应放在项目根目录，命名为.pylintrc（最稳定推荐），或pyproject.toml（含[tool.pylint]）；它按顺序查找.pylintrc、pyproject.toml、setup.cfg和~/.pylintrc，找到即停止。
PyLint 配置文件该放哪、叫什么名
PyLint 不会自动读取任意位置的配置文件，必须明确告诉它配置在哪，或者按约定路径放置。默认会依次查找：.pylintrc（当前目录）、pyproject.toml（带 [tool.pylint]）、setup.cfg（含 [pylint]），最后是用户主目录下的 ~/.pylintrc。优先推荐用 .pylintrc —— 它最稳定、支持最全，且团队协作时容易 git 跟踪。
生成初始配置：运行 pylint --generate-rcfile > .pylintrc，然后编辑该文件。别直接改全局配置，否则不同项目风格会互相干扰。
如何让 PyLint 报错而非警告来阻断 CI 或本地提交
PyLint 默认把风格问题（比如行太长、变量名小写）标为 message type = convention，这类不会导致退出码非 0。要实现“强制检查”，必须把关键规则提升为错误级，或用 --errors-only + 严格阈值控制。
- 在
.pylintrc的[MESSAGES CONTROL]下启用你关心的规则，例如：enable=missing-module-docstring,missing-class-docstring,missing-function-docstring,invalid-name,line-too-long - 在
[REPORTS]中设fail-on=error,convention（PyLint ≥ 2.14 才支持；旧版本需用--exit-zero反向控制，不推荐） - 更稳妥的做法是：CI 中用
pylint --exit-zero --output-format=colorized --score=n --fail-on=convention your_module/，并配合--score=n（如n=8）设定最低可接受分数
常见误配：invalid-name 规则为什么总报错 self、cls、id？
invalid-name 是最常被误伤的规则。它默认用正则 [a-z][a-zA-Z0-9]{2,30}$ 匹配变量名，但 self、cls、id、pk 等都短于 3 字符，直接被拒。
解决方式是在 .pylintrc 的 [MESSAGES CONTROL] 后加 [MESSAGES] 段：
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
[MESSAGES]
variable-rgx=[a-z][a-zA-Z0-9]{2,30}$
const-rgx=[A-Z][A-Za-z0-9]{2,30}$
argument-rgx=[a-z][a-zA-Z0-9]{2,30}$
attr-rgx=[a-z][a-zA-Z0-9]{2,30}$
然后在 [MESSAGES] 下覆盖特例：
good-names=i,j,k,ex,Run,_,self,cls,id,pk
漏掉 pk 或 id 是 Django/Flask 项目里最常踩的坑——它们不是“坏名字”，只是不符合默认正则。
vscode 或 pre-commit 中集成时为何不生效
VS Code 的 Python 插件默认调用的是 workspace 根目录下的 .pylintrc，但如果项目有 pyproject.toml 且含 [tool.pylint]，部分旧版插件会忽略 .pylintrc。确认方式：在终端进项目根目录，执行 pylint --version && pylint --help-msg=C0103，看输出是否显示已启用 invalid-name。
pre-commit 配置里容易错在路径和 Python 版本：
-
entry: pylint --rcfile=.pylintrc必须显式指定，不能依赖自动发现 - 确保
types: [python]，否则 .py 文件可能被跳过 - pre-commit 使用的 Python 环境必须已安装
pylint，建议用additional_dependencies: ["pylint==2.17.5"]锁版本，避免 CI 和本地行为不一致
真正难调试的点在于：PyLint 的配置加载顺序、消息类型分级、以及不同 Python 解释器环境之间的隔离。哪怕只改一行 good-names，也得重新验证所有上下文是否识别——尤其当项目同时用 mypy、ruff、black 时，各工具对“合法标识符”的定义并不统一。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
