在 VS Code 中使用 Black 格式化 Python 代码

Ne0inhk

— 8 min read

在 VS Code 中使用 Black 格式化 Python 代码的详细指南

Black 是目前 Python 社区最流行的自动格式化工具之一，它的特点是“极少配置、强制风格”：你把代码交给 Black，它按照一套统一规则帮你排版，从此团队不用再纠结“空格还是换行”。

这篇文章会详细说明：

  1. Black 是什么、适合做什么
  2. 安装 Black（虚拟环境 / 全局）
  3. 在 VS Code 中配置 Black 为默认格式化工具
  4. 保存时自动格式化
  5. 配置 Black 参数（行宽等）
  6. 常见问题与排错

一、Black 简介

Black 的核心理念：

  • 只做格式，不改语义。
  • 尽量减少可配置项，以统一风格。
  • 通过命令行或编辑器扩展自动格式化。

在 VS Code 中使用 Black 的典型流程是：

  • 保存文件 → Black 自动修改代码排版 → 你只关注业务逻辑。

二、安装 Black

在 VS Code 中使用 Black，底层还是依赖系统/虚拟环境中的 black 命令。因此第一步是安装 Black。

2.1 在项目虚拟环境中安装（推荐）

# 创建虚拟环境（示例） python -m venv .venv # 激活虚拟环境（Windows） .\.venv\Scripts\activate # 激活虚拟环境（macOS / Linux）source .venv/bin/activate # 安装 black pip install black

这样做的好处：

  • 每个项目可以使用各自版本的 Black，避免项目之间互相影响。
  • 便于在 requirements.txt 或 pyproject.toml 中记录依赖版本。

2.2 全局安装（不太推荐，但可以）

pip install --user black

适合个人简单脚本项目，但团队协作时，还是建议使用虚拟环境或者在 pyproject.toml 中锁定 Black 版本。

三、VS Code 基础配置：启用 Python 扩展

在 VS Code 中使用 Black 之前，需要先装好 Python 扩展。

  1. 打开 VS Code
  2. 左侧点击「扩展（Extensions）」图标
  3. 搜索 Python，安装 Microsoft 官方的 Python 扩展
  4. 推荐同时安装 Pylance 扩展（类型提示、补全更好）

安装好后，VS Code 会自动识别 .py 文件的 Python 语言特性。

四、在 VS Code 中选择解释器（指向 Black 所在环境）

如果你把 Black 安装在虚拟环境里，需要让 VS Code 知道用哪个 Python 解释器（也就是哪个虚拟环境）。

  1. 打开 Python 项目
  2. 按 Ctrl+Shift+P（macOS 上 Cmd+Shift+P）打开命令面板
  3. 输入并选择：Python: Select Interpreter
  4. 在列表中选择你创建的虚拟环境，比如：
    • .venv
    • venv
    • 或其他你自定义的名字

选择正确解释器后：

  • VS Code 使用该环境运行 Black、lint 工具、调试等。
  • 若 Black 在此环境中安装成功，后面配置就能正常工作。

五、将 Black 设置为默认格式化工具

VS Code 支持多个格式化工具（如 autopep8、yapf、Black），需要显式告诉 VS Code：Python 用 Black 来格式化。

5.1 通过设置图形界面配置（适合初学）

  1. 打开设置：
    • 方式一：左下角齿轮 → Settings
    • 方式二：快捷键 Ctrl+, / Cmd+,
  2. 右上角搜索框中输入：Python Formatting Provider
  3. 在下拉选项中选择：black

若搜索不到该选项，可以搜索 formatting provider 或换成中文关键字（如“格式化”），确保 Python 扩展已安装。

5.2 直接编辑 settings.json（适合熟悉 VS Code 配置的人）

  1. Ctrl+Shift+P / Cmd+Shift+P
  2. 输入：Preferences: Open Settings (JSON)
  3. 在 JSON 中添加或修改如下内容（注意逗号语法）：
{ // ... 其他设置 ... // 使用 Black 作为 Python 格式化工具 "python.formatting.provider": "black" }

保存后生效。

六、启用「保存时自动格式化」

为了真正“无感”使用 Black，建议开启保存即自动格式化。

6.1 全局启用保存自动格式化（所有语言）

  1. 设置中搜索：Format On Save
  2. 勾选：Editor: Format On Save（editor.formatOnSave）

这意味着所有支持格式化的文件在保存时都会被对应的格式化工具处理。

6.2 只针对 Python 启用（更精细控制）

如果只希望 Python 自动格式化，可以在 settings.json 中使用语言特定配置：

{ // 全局不自动格式化 "editor.formatOnSave": false, "[python]": { "editor.formatOnSave": true, "editor.defaultFormatter": "ms-python.python" // 使用 Python 扩展的格式化 }, "python.formatting.provider": "black" }

说明：

  • "[python]" 里的配置只对 Python 文件生效。
  • editor.defaultFormatter 指定该语言由哪个扩展来执行格式化，ms-python.python 是官方 Python 扩展的 ID。

保存 settings.json 后，打开一个 .py 文件，试着写点不规整的代码，然后保存，看是否会被 Black 重新排版。

七、手动触发 Black 格式化

即使不开保存自动格式化，你也可以随时手动触发格式化：

  • 快捷键：
    • Windows / Linux：Shift+Alt+F
    • macOS：Shift+Option+F
  • 或右键代码编辑区 → 选择「Format Document」

如果出现弹窗提示「选择格式化程序」：

  1. 选择 Python 格式化（一般会有 Python 或 Black 等选项）
  2. 如果没看到 Black，需要确认上面几步是否已正确安装 / 配置。

八、配置 Black 的行为（行宽等）

Black 的设计理念是“少配置”，但仍然提供了几个核心参数，最常用的是 line-length（最大行宽）。

Black 支持以下配置文件之一：

  • pyproject.toml（推荐，现代项目标配）
  • pyproject.toml 中 [tool.black] 段落

8.1 在 pyproject.toml 中配置 Black（推荐）

在项目根目录创建或编辑 pyproject.toml：

[tool.black] line-length = 100 target-version = ["py310"] skip-string-normalization = true

常见选项说明：

  • line-length：最大行宽，默认 88，可改为如 100、120 等。
  • target-version：目标 Python 版本，影响一些语法支持。
  • skip-string-normalization：默认为 false，Black 会统一把字符串引号改为双引号。如果不想改引号，可以设为 true。

Black 在运行时会自动从当前目录向上查找 pyproject.toml 中的 [tool.black] 配置段。

8.2 不建议在 VS Code 里直接改 Black 命令参数

以前的 Python 扩展支持通过 python.formatting.blackArgs 添加 Black 参数，例如：

"python.formatting.blackArgs": [ "--line-length", "100" ]

在新版本中，更推荐通过 pyproject.toml 来管理 Black 的配置，实现“编辑器/CI 一致”，避免 VS Code 和命令行用到不同的格式规则。

九、在命令行与 VS Code 中保持一致

如果你在 CI 或命令行也会运行 Black，强烈建议：

  1. 在项目根目录使用 pyproject.toml 统一配置 Black。
  2. VS Code 只是调用安装在虚拟环境里的那个 Black，可自动读取同一份配置。

命令行示例：

# 在项目根目录 black .# 或者只格式化某些目录 black src tests

VS Code 保存时用的规则会和命令行一致。

十、常见问题与排错

10.1 保存时没有自动格式化

排查步骤：

  1. 在 VS Code 中确认已选择正确解释器（Python: Select Interpreter）。
  2. 查看 settings.json 中：
    • "python.formatting.provider": "black" 是否正确。
    • editor.formatOnSave 或 [python].editor.formatOnSave 是否为 true。
  3. 手动执行「Format Document」，看看是否有错误提示。

确认 Black 已安装在当前项目使用的解释器中：

which python # 或 py -V 环境检查 python -m pip show black

10.2 VS Code 提示找不到 Black

  • 如果在 VS Code 自带的终端中运行找不到，但在系统终端中能找到，很可能是：
    • VS Code 当前使用的解释器不同；
    • 或 PATH 没有指向 Black 安装位置。
  • 解决：
    • 重新选择解释器（Python: Select Interpreter），选中安装了 Black 的那个环境。
    • 尽量使用项目内虚拟环境，并在 VS Code 终端中激活它。

检查终端中是否能运行：

black --version

10.3 Black 修改了很多代码，看不习惯

建议的过渡策略：

  1. 先在一个小项目或新模块上试用 Black，熟悉风格。
  2. 在老项目中，可以先对单个目录或文件手动格式化，而不是一次性改全仓库。
  3. 团队协作建议一次性全局格式化并单独提一个 PR，让后续代码评审不被大量“格式 diff”干扰。

十一、总结步骤速查

如果你只想快速配置好，可以按下面 checklist 操作：

  1. 打开 VS Code，选择虚拟环境为 Python 解释器（Python: Select Interpreter）。
  2. 安装 VS Code 的 Python 扩展（ms-python.python）。

在 pyproject.toml 中添加 Black 配置（可选但推荐）：

[tool.black] line-length = 100 target-version = ["py310"]

启用保存自动格式化（推荐）：

"[python]": { "editor.formatOnSave": true, "editor.defaultFormatter": "ms-python.python" }

在设置中选择 Black 为格式化器：

"python.formatting.provider": "black"

在项目虚拟环境中安装 Black：

python -m venv .venv source .venv/bin/activate # 或对应平台命令 pip install black

配置完成后，写一段乱排版的 Python 代码，按 Ctrl+S 保存，你就能看到 Black 自动把它“修理得整整齐齐”。

Read more

【AI大模型】DeepSeek + 通义万相高效制作AI视频实战详解

【AI大模型】DeepSeek + 通义万相高效制作AI视频实战详解

目录 一、前言 二、AI视频概述 2.1 什么是AI视频 2.2 AI视频核心特点 2.3 AI视频应用场景 三、通义万相介绍 3.1 通义万相概述 3.1.1 什么是通义万相 3.2 通义万相核心特点 3.3 通义万相技术特点 3.4 通义万相应用场景 四、DeepSeek + 通义万相制作AI视频流程 4.1 DeepSeek + 通义万相制作视频优势 4.1.1 DeepSeek 优势 4.1.2 通义万相视频生成优势 4.2

By Ne0inhk
【DeepSeek微调实践】DeepSeek-R1大模型基于MS-Swift框架部署/推理/微调实践大全

【DeepSeek微调实践】DeepSeek-R1大模型基于MS-Swift框架部署/推理/微调实践大全

系列篇章💥 No.文章01【DeepSeek应用实践】DeepSeek接入Word、WPS方法详解：无需代码，轻松实现智能办公助手功能02【DeepSeek应用实践】通义灵码 + DeepSeek：AI 编程助手的实战指南03【DeepSeek应用实践】Cline集成DeepSeek：开源AI编程助手，终端与Web开发的超强助力04【DeepSeek开发入门】DeepSeek API 开发初体验05【DeepSeek开发入门】DeepSeek API高级开发指南（推理与多轮对话机器人实践）06【DeepSeek开发入门】Function Calling 函数功能应用实战指南07【DeepSeek部署实战】DeepSeek-R1-Distill-Qwen-7B：本地部署与API服务快速上手08【DeepSeek部署实战】DeepSeek-R1-Distill-Qwen-7B：Web聊天机器人部署指南09【DeepSeek部署实战】DeepSeek-R1-Distill-Qwen-7B：基于vLLM 搭建高性能推理服务器10【DeepSeek部署实战】基于Ollama快速部署Dee

By Ne0inhk

DeepSeek各版本说明与优缺点分析_deepseek各版本区别

DeepSeek各版本说明与优缺点分析 DeepSeek是最近人工智能领域备受瞩目的一个语言模型系列，其在不同版本的发布过程中，逐步加强了对多种任务的处理能力。本文将详细介绍DeepSeek的各版本，从版本的发布时间、特点、优势以及不足之处，为广大AI技术爱好者和开发者提供一份参考指南。 1. DeepSeek-V1：起步与编码强劲 DeepSeek-V1是DeepSeek的起步版本，这里不过多赘述，主要分析它的优缺点。 发布时间： 2024年1月 特点： DeepSeek-V1是DeepSeek系列的首个版本，预训练于2TB的标记数据，主打自然语言处理和编码任务。它支持多种编程语言，具有强大的编码能力，适合程序开发人员和技术研究人员使用。 优势： * 强大编码能力：支持多种编程语言，能够理解和生成代码，适合开发者进行自动化代码生成与调试。 * 高上下文窗口：支持高达128K标记的上下文窗口，能够处理较为复杂的文本理解和生成任务。 缺点： * 多模态能力有限：该版本主要集中在文本处理上，缺少对图像、语音等多模态任务的支持。 * 推理能力较弱：尽管在自然语言

By Ne0inhk

用DeepSeek和Cursor从零打造智能代码审查工具：我的AI编程实践

💂 个人网站:【 摸鱼游戏】【神级代码资源网站】【星海网址导航】摸鱼、技术交流群👉 点此查看详情 引言：AI编程革命下的机遇与挑战 GitHub统计显示，使用AI编程工具的开发者平均效率提升55%，但仅有23%的开发者能充分发挥这些工具的潜力。作为一名全栈工程师，我曾对AI编程持怀疑态度，直到一次紧急项目让我彻底改变了看法。客户要求在72小时内交付一个能自动检测代码漏洞、优化性能的智能审查系统，传统开发方式根本不可能完成。正是这次挑战，让我探索出DeepSeek和Cursor这对"黄金组合"的惊人潜力。 一、工具选型：深入比较主流AI编程工具 1.1 为什么最终选择DeepSeek+Cursor？ 经过两周的对比测试，我们发现不同工具在代码审查场景的表现差异显著： 工具代码理解深度响应速度定制灵活性多语言支持GitHub Copilot★★★☆★★★★★★☆★★★★Amazon CodeWhisperer★★☆★★★☆★★★★★★☆DeepSeek★★★★☆★★★★★★★☆★★★★☆Cursor★★★☆★★★★☆★★★★★★★★ 关键发现： * Dee

By Ne0inhk