最近在代码评审的时候我发现自己越来越不想评论“这里该加个空格”“那个换行不对”这类问题了。不是因为团队纪律变好了而是我们把Black引入了工作流——提交代码前自动格式化机器能解决的问题就不要再让人来争论。这篇就聊聊我实际使用Black的经验包括它为什么这么“固执”、怎么把它嵌进日常开发和团队协作里以及我踩过的几个坑。1. Black到底解决了什么问题1.1 团队协作中代码风格的真实痛点只要一个项目超过两个人维护代码风格就会变成一种隐性的沟通成本。你可能经历过这样的场景A同事习惯写在行尾加两个空格来对齐赋值语句B同事觉得没必要C同事写函数参数时喜欢一个参数占一行D同事觉得参数少的时候一行写完更清爽。这些东西本身没有对错但是每次代码评审都会因此多出几条“建议修改”的评论。更麻烦的是有些同事对格式修改非常敏感你动了他的格式他会觉得你在挑刺——哪怕你只是按约定俗成的风格调整了一下。还有一类问题是工具带来的。很多人用IDE自带的格式化功能但在不同编辑器之间同样一段代码格式化出来的结果可能完全不同。今天你用某款IDE的自动整理提交了代码明天同事用另一款软件打开再改几个字符保存整个文件的diff就变得特别大。真正要改的逻辑可能只有一行但diff里显示的是一大片格式变动评审的人根本分不清哪些是真实改动。1.2 Black“零配置”和“固执己见”的定位Black给自己的定位是“The Uncompromising Code Formatter”翻译过来就是不妥协的代码格式化工具。它和传统的格式化工具最大的区别在于Black几乎不给你配置选项。你不用去决定缩进用几个空格、行宽设多少、字符串用单引号还是双引号——所有这些都已经被Black定死了。这一点乍一听非常反直觉很多人第一反应是“凭什么不让我配置”但我想说一个实际使用后的体会格式化工具的配置选项本身就是分歧的来源。一个团队在引入格式化工具的时候花在争论“到底选哪套配置”上的时间可能比真正使用工具的时间还多。有人喜欢把每行宽设成79有人坚持88还有人觉得120也没问题。这些争论最终会消耗团队的精力而Black的哲学就是这些选择不重要统一才重要。Black的默认行宽是88个字符而不是PEP 8推荐的79。这个选择是有讲究的。79是历史遗留——早期终端宽度80列为了留一个字符的余量才有了这个惯例。但在现代宽屏编辑器和4K显示器环境下79显得过于保守会让代码频繁换行反而影响阅读。88这个数字是在可读性和行宽利用之间做了权衡得到的结果。Black的开发者给它取了个副标题叫“不妥协的格式化工具”意思是你可以不认同它的每一个具体决策但只要你接受统一格式这个大前提它的所有默认值都是经过考量的。1.3 与autopep8、yapf等工具的对比Python生态里其实早有自动化格式化的工具最常见的是autopep8和yapf。autopep8的思路是“让现有代码符合PEP 8”——它只是修改那些不合规的地方而合规的地方保持原样。yapf的理念是“以更好的代码风格为目标”——它会参照Google的Python代码风格指南。这两类工具都有个共同问题它们是“可协商”的。autopep8有很多参数可以调yapf甚至有一套独立的配置格式你可以在配置里指定几乎所有的排版规则。这就导致了前面说的那个情景团队“引入”了格式化工具但每个人的配置不一样格式化的结果还是不一致。Black走的是另一条路它不在“现有代码风格”基础上做局部修正而是把整个文件按照一套固定规则重新排版。这使得它有两个核心优势同一个文件在任何机器、任何时间、任何人手里运行Black得到的结果完全一致你的代码一旦被Black格式化它的风格就是Black风格而不是“某个人的风格”我在实际项目里把autopep8切换成Black之后最直观的感受是代码评审的讨论内容真的变了——大家不再花时间讨论格式而是把精力花在逻辑和设计上。如果你所在的团队还没用过任何格式化工具我建议直接上Black没必要在autopep8和yapf之间来回比较。2. Black的安装与基础使用2.1 安装与环境准备Black的安装非常简单直接用pip安装即可pip install black如果你是Python 3.10以上的环境更推荐用pipx安装这样Black会运行在独立环境里不会污染你的项目依赖pipx install black安装完成后可以用下面的命令查看版本black --version在写这篇文章的时候我用的版本已经迭代到比较新的版本新版本还支持了Python 3.12的语法特性。如果你项目的Python版本比较老可能需要在安装时指定版本。比如项目还跑在Python 3.8上可以用black22.3.0这类兼容版本。但说实话如果条件允许尽量把项目升级到新版本PythonBlack的新版本对语法的支持会好很多。Black本质上是独立于你的项目环境的它的作用是读取你的Python源码文件并重写它们。所以你不需要把Black写进项目的依赖里除非你有特殊需求。2.2 命令行基础用法与常用参数最常见的使用方式是在项目根目录下直接运行black .这个命令会递归处理当前目录下所有的.py文件。如果你只想格式化某个文件或者某个目录也可以直接指定路径black my_module.py black src/Black执行之后会输出类似这样的信息reformatted my_module.py All done! ✨ ✨ 1 file reformatted, 1 file left unchanged.这里我截取了它的输出——注意这里的emoji是Black自带的不是我在文章里加的。如果你的终端不支持emoji显示Black的提示可能会有点奇怪但不影响功能。除了直接格式化还有几个参数我几乎每次都用得上--check只检查文件是否需要格式化但不真正修改文件。这个参数在CI和pre-commit里是主力——如果文件不符合Black风格命令会以非零状态退出。--diff不修改文件而是输出格式化的差异。这个参数很适合在引入Black的初期观察它到底会改动哪些地方。--line-length修改行宽。我刚才说了Black默认88但如果你的团队有特殊约定可以用这个参数调整。--skip-string-normalization不统一字符串引号。默认情况下Black会把单引号字符串改成双引号如果字符串里没有双引号的话。如果你项目里全是单引号风格的代码又不想被全部改一遍可以先加上这个参数过渡。不过我的建议是过渡期结束就把这个参数去掉毕竟统一总要有个终点。--fast跳过语法检查。Black默认在格式化前会先用AST检查代码语法如果发现语法错误就不会格式化文件。加上--fast会跳过这一步速度更快但风险也更高。我一般不推荐用除非你的项目文件特别多、格式化速度成了瓶颈。2.3 用--diff观察Black的改动逻辑前面提到我要在一开始引入Black时先看它到底会怎么改代码。这里有一个非常实用的操作流程black --diff --check my_module.py输出会像标准diff一样用-和标记出每一处改动。比如你写了这样一坨代码def my_function(name,age,address): resultfName: {name}, Age: {age}, Address: {address} return resultBlack处理完之后diff会显示出函数定义里的逗号后补充空格参数之间统一加一个空格f-string里的大括号表达式和文字之间保持紧凑这种可视化的反馈非常有用。你可以快速建立对Black风格的“直觉”知道它在哪些场景下会做什么样的改动。等你看过几次diff之后写代码的时候就会自然而然地写出符合Black风格的代码减少后续格式化的改动量。2.4 在项目里建立配置文件Black的定位是零配置但它并不是完全不支持配置文件。你可以在项目的pyproject.toml里设置少数几个可调项。举个例子[tool.black] line-length 100 skip-string-normalization true target-version [py310]target-version是告诉Black你的代码要求支持哪个Python版本。这个参数会影响Black对某些语法特性的处理。比如有些语法在老版本里是SyntaxErrorBlack会根据你指定的目标版本决定是否把它留在代码里。配置文件的另一个作用是让所有成员使用一致的设置。就算你不调整任何参数我也建议在pyproject.toml里显式写上[tool.black]这一行哪怕下面是空的。原因很简单AI辅助工具和某些IDE插件会自动扫描pyproject.toml来确定项目是否启用了Black如果你没有配置文件IDE可能会用全局配置而不是项目级的导致环境不一致。3. 核心设计细节Black的格式化规则3.1 行宽、括号和隐式续行的处理逻辑Black对代码排版有一套相当成体系的处理逻辑理解这些逻辑你会对它的“固执”有更清晰的认知。行宽控制默认88字符。超过这个长度的代码Black会尝试用各种方式把代码拆成多行。比如一个很长的列表字面量my_list [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]Black会把它拆成多行——但注意它的拆分方式它不会机械地每N个元素换一行而是会先尝试把整个列表以“逗号”为单位分成尽量多的项目然后根据项目数量决定是否拆成“一个元素一行”的竖排形式。这就是Black的“爆炸式”排版explode如果一个容器里的元素无法在一行内放下Black会把它全部展开每个元素占一行。隐式续行Python里括号内的换行都是合法的Black充分利用了这一点。它不会在行尾加反斜杠\来续行除非是没有括号的场景比如长字符串拼接。这一点我觉得比很多手写风格都干净。Call式参数排版函数调用你如果写成这样result some_function_name(param_one1, param_two2, param_three3, param_four4, param_five5, param_six6)如果这行超过了88个字符Black会把它变成result some_function_name( param_one1, param_two2, param_three3, param_four4, param_five5, param_six6, )注意每个参数后面都跟了一个逗号这种“魔法尾逗号”是Black的一个特色当容器被拆成多行时Black会在最后一个元素后面也加逗号。这样以后加参数时diff会只显示一行新增而不是改两行。3.2 魔法尾逗号的规则与实际利用“魔法尾逗号”这个名字听起来有点玄乎但它的规则其实非常简单。给你看个例子。最开始代码是这样my_tuple ( 1, 2, 3 )注意最后一个元素3后面没有逗号。很快你就会在那后面加一个4my_tuple ( 1, 2, 3, 4 )这样diff显示了两个改动3那一行加了逗号新增了4那一行。但如果你一开始就在3后面加了尾逗号新增4时就只有一个改动行。Black深谙此道所以当它把容器类的东西拆成多行时会在最后一个元素后强制加尾逗号。这样做对后续维护非常友好。这有个例外对于函数调用如果“魔法尾逗号”存在Black会一直保持“爆炸式”排版即使后来参数少了、能在一行放下了它也不会自动收回成一行。这是为了避免频繁的格式来回变动。在Black的文档里这种行为模式被称为“magic trailing comma keeps explode”。我建议在写只有两三个参数的函数调用时还是让Black来决定是否展开比较省心。3.3 字符串引号的统一逻辑Black默认会把所有不包含双引号的单引号字符串统一成双引号。也就是说name Alice会被改成name Alice这个改动会引起很多人的不舒服因为Python社区里“单引号党”和“双引号党”一直没消停过。Black的这个选择逻辑是Python标准库里大部分代码使用的是双引号而且JSON、HTML这些数据格式也大量使用双引号统一使用双引号可以让格式化结果更多样化地嵌入其他数据场景。如果你的代码里有大量文档字符串或者SQL查询片段其中包含单引号但完整字符串本身内部有双引号字符或需要转义这是Black不会强行修改的场景。比如text He said HelloBlack会保留单引号因为它理清楚规则是如果字符串内部包含了双引号那就用单引号做边界反之内外调换。我早期用Black的时候没注意这个细节看到一些字符串“没被修改”我还以为是工具不稳定后来翻代码发现并不是——只是那些字符串内部包含了另一种引号。如果你真的不想让Black改引号风格可以加--skip-string-normalization但我个人不推荐长期使用因为统一的目的就是减少思考。3.4 Black对空行和注释的处理规则Black在空行规则上跟PEP 8基本一致函数和类定义前后有两个空行类内部方法之间有一个空行。但Black还有个不太为人注意的规则——它会删掉“多余的”空行但它不会把一个空行在特殊上下文里全部删光。比如你在一个函数内部为了“视觉分组”写了多个空行Black会保留其中一个两个空行的上限超过的部分会被清理。注释的处理则是Black相对“保守”的领域。Black不会移动你的注释位置也不会重写注释内容。但有一个有趣的行为如果一个注释前面是代码后面紧跟着代码Black会保持注释在原来的位置不会为它额外增加空行。这有时候会导致注释跟代码在视觉上“粘”得太紧需要你自己手动加空行。还有一个常见的行为如果整个文件只有一行注释或者文件末尾没有换行符Black会自动在文件末尾补一个换行符。这是POSIX标准的规定很多工具都会有这个处理Black也不例外。3.5 不可变数据结构与格式化的联姻Black对代码的元数据是严格不修改的——它不会动你的docstring不会去重命名变量更不会改变代码逻辑。它连f-string里的可读表达都不会去触碰比如它不会把f{a}{b}改成f{a}{b}里的空格调整因为它不解析f-string内部的内容。这给了我一个安全心理。团队推行Black时我最怕的是“格式化工具试图聪明地重写逻辑导致bug”。Black在设计上就规避了这种风险它只触碰AST层面看到的排版信息对代码的语义结构是零影响。换句话说你完全可以通过Black格式化来统一风格而不必担心它悄悄改变了程序的运行结果。4. 实操过程把Black嵌入项目工作流4.1 在VS Code里配置保存时自动格式化把Black集成到编辑器里是让你“无感使用”的关键一步。我用的是VS Code配置起来非常简单。在settings.json里加几项{ python.formatting.provider: black, editor.formatOnSave: true, editor.codeActionsOnSave: { source.organizeImports: true } }editor.formatOnSave开启后每次按下保存VS Code就会自动调用Black格式化当前文件。这个过程大概几十毫秒几乎感觉不到。还有一点需要注意如果你装了其他Python格式化插件比如autopep8扩展那就要确保它们不是同一个文件格式化的provider。VS Code的老设置里格式化的provider和应用方式可能会互相冲突我踩过一顿坑。建议只保留一个provider避免两个格式化工具抢文件。如果你用的是PyCharm可以到 Settings → Tools → Python Integrated Tools → Code style → Formatter 里选BlackPyCharm对新版本Black的集成也做得不错。不过我个人觉得PyCharm的保存时自动格式化不如VS Code顺手如果你喜欢PyCharm建议用外部工具的方式配置快捷键。4.2 用pre-commit强制提交前格式化编辑器里配置好了只能保证你自己写的代码是格式化过的。但一个团队里总有没配置编辑器的人或者干脆有人在CI机器上直接改代码。要保证仓库里所有代码都是Black风格的最稳妥的方式是接上pre-commit。项目根目录建一个.pre-commit-config.yamlrepos: - repo: https://github.com/psf/black rev: 23.3.0 hooks: - id: black然后在项目里执行安装pre-commit install这样每次执行git commit的时候pre-commit会调用Black检查暂存区里的Python文件。如果文件没有被格式化pre-commit会直接修改它们并且让commit失败提醒你重新add和commit。这个流程用起来刚开始可能会觉得烦——有一次我发现我提交了代码pre-commit把三个文件格式化了我还得重新git add再提交一次。但习惯之后这种“强制”反而会防止不规范的代码进入仓库。在pre-commit里我建议同时挂一个isort来管理import排序。Black不处理import顺序而isort正好补这个缺。配置如下repos: - repo: https://github.com/psf/black rev: 23.3.0 hooks: - id: black - repo: https://github.com/pycqa/isort rev: 5.12.0 hooks: - id: isort args: [--profile, black]注意--profile black这个参数。isort的默认配置跟Black的某些排版习惯是有冲突的比如isort默认在import语句后的换行和Black的组合方式会导致多出一个空行。用--profile black就是告诉isort“请按照Black的兼容模式工作”这样两个工具就不会打架了。4.3 在CI流水线中设置格式化检查pre-commit管住了开发者本地的提交但有些团队用Git工作流不是所有人都会装pre-commit的。那就要在CI上设一道保险。在CI的Python测试步骤之前加一步black --check .这样当任何人推送代码到远端分支时CI会自动检查所有Python文件的格式是否合规。不合规就直接fail流水线要求开发者先跑一次Black再推。这一步可能会引发某些同事的不满——特别是那些已经写好代码、但格式从来不合规的人。我的建议是引入Black的时候先在“新代码”上强约束老代码可以分批处理。比如先在CI里只检查src/目录等大家都习惯了再扩展到tests/或者其他目录。4.4 Black与pylint、flake8等lint工具的配合Black只管格式不管代码质量。实际项目中通常还要搭配lint工具来捕获潜在的bug和坏味道。常见组合是Black flake8 pylint。这里有个细节要注意flake8默认的行宽上限是79而Black默认是88。如果你同时用这两个工具flake8会在E501 line too long上频繁误报——因为Black允许88字符而flake8按79去查自然会有无数“超长行”。解决办法是在flake8配置里把行宽调成88[flake8] max-line-length 88 extend-ignore E203, W503E203和W503这两个错误码是flake8和Black在切片空格规则上冲突的主要来源。Black在切片时会遵守PEP 8里“冒号两边不加空格”的写法但flake8旧规则要求加空格导致冲突。extend-ignore里把这俩关掉是社区的标准做法。pylint和Black的冲突相对少一些但偶尔会在“不必要的换行”这类提示上有争执。说实话pylint的可配置项实在太多不同团队差异很大我这里不展开讲但你可以考虑在pylintrc里关闭格式相关的检查把格式的事情完全交给Blackpylint只保留逻辑和复杂度相关的检查。这样职责更清晰。5. 常见问题与排查技巧实录5.1 Black运行后文件为空或大量代码被误改这个问题出现得不多但一旦出现就很吓人。最常见的原因是Black在运行时读到了一个包含语法错误的文件。前面说了Black默认会检查AST遇到语法错误会拒绝格式化。但如果你用了--fast跳过语法检查之后格式化器可能在解析阶段抛异常导致文件被清空或写入不完整的内容。我实际遇到的另一种情况是文件编码问题。如果Python文件是非UTF-8编码比如GBK而且文件里包含特殊字符Black在读写时会出现乱码。解决方式是在项目入口处统一指定UTF-8编码配置文件里也可以放[tool.black] ...Black本身没提供编码参数但我没找到官方推荐我在实际中都是确保文件是UTF-8。通过IDE统一改编码会省下很多痛苦。如果怀疑Black把文件改得面目全非先不要慌用git diff查看具体改动。只要你的代码之前是被git管理的总能把误改的部分恢复原状。然后重新在干净副本上跑Black。5.2 格式化后代码变得难以阅读的场景Black并不总是“让代码更好看”。它有几个场景会让代码变得非常碎。最典型的是很长的if条件表达式。比如if condition_one and condition_two and condition_three and condition_four and condition_five and condition_six:Black会把它拆成if ( condition_one and condition_two and condition_three and condition_four and condition_five and condition_six ):这种格式在逻辑上确实清楚但会占据大量垂直空间。我见过一些人觉得这种排版太浪费。但这种场景其实应该由开发者先重构代码——把复杂的条件抽取成命名清晰的函数而不是让格式化工具来硬排。如果你发现Black的格式化结果特别啰嗦那多半不是Black的问题而是你的代码该重构了。5.3 配置了--check但在CI中仍然通过有一种常见场景是你在CI里写了black --check .但某些不合规的文件仍然没有被拦截。排查步骤先确认--check对目录的递归处理是否符合预期。Black默认会递归处理给定目录下的所有.py文件但不会处理隐藏目录以.开头的目录。如果你的项目里源代码放在src/.internal/这种目录下就可能会被漏掉。再确认Black是否忽略了某些文件。Black支持在pyproject.toml里通过extend-exclude配置排除目录[tool.black] extend-exclude /(build|dist|\.venv|venv)/ 如果你之前配置过排除目录可能会发现CI检查漏掉了某些文件。还有一种情况项目的.gitignore包含了某些目录而Black默认不会处理这些被忽略的目录新版本Black在--check模式下会把gitignored文件也考虑进去行为略有变化但总归要检查一下。5.4 Black与Jupyter Notebook的兼容问题如果你的仓库里有.ipynb文件直接运行black .并不会格式化它们。新版本的Black支持处理Notebook文件但需要在后面加--include参数或者明确指定文件路径。还有一个办法是在Jupyter里用black[jupyter]方式来安装然后通过魔法指令%black格式化单元格。我自己处理Notebook较少一般是在Notebook里粘贴代码之前先在自己编辑器里用Black格式化好再粘贴进去。这样省掉了额外配置的复杂性。5.5 如何说服团队成员接受Black这不算技术问题但可能是推行Black时最难的一步。我经历过几次团队推行格式化工具的讨论总结一下行之有效的思路不要一上来就说“我们要用Black”而是先提议“我们能不能定一个统一的代码风格让工具自动实现”。然后花一两个星期用black --diff生成一些现有代码的改动示例在评审会上展示给同事看。大家看了diff会觉得“哦原来这个工具改的是这些地方”大多是空行、引号、缩进之类的变化并没有本质伤害。只要没有人对某一条规则特别极端地反对通常就能通过。如果你在的团队里有人对“双引号”或“88字符行宽”特别在意可以先给他们一个“安全阀”用兼容配置过渡半年比如skip-string-normalization。但这种过渡期要明确截止时间不然这个参数就会变成永久设置团队风格又回到分裂状态了。我个人在实际使用中还发现把Black纳入代码评审规范之后大家写代码的心态会自然发生变化——知道最终格式会被工具统一写的时候就不太纠结排版了反而会把更多注意力放在命名和逻辑上。这是一种隐性的效率提升不容易量化但真实存在。5.6 一个实用的组合配置模板聊了这么多最后给你一份我目前项目里在用的Black相关配置直接抄作业就行。pyproject.toml[tool.black] line-length 88 target-version [py310] skip-string-normalization false.pre-commit-config.yamlrepos: - repo: https://github.com/psf/black rev: 23.3.0 hooks: - id: black - repo: https://github.com/pycqa/isort rev: 5.12.0 hooks: - id: isort args: [--profile, black]setup.cfg或.flake8[flake8] max-line-length 88 extend-ignore E203, W503这套组合我用了很长时间稳定。团队规模从两人到二十人都靠这套配置维持代码风格的一致性。成本极低收益很高。