VSCode Python开发高效工作流：轻量、可塑与无感的工程实践

weixin_30550081

434人浏览 · 2026-05-24 14:22:01

weixin_30550081 · 2026-05-24 14:22:01 发布

1. 为什么我坚持用 VSCode 写 Python？不是情怀，是实打实的效率账

我从 2016 年开始用 VSCode 做 Python 开发，那会儿还在用 Sublime Text 和 Atom。第一次把一个 300 行的爬虫脚本在 VSCode 里调试通，只用了 17 分钟——而之前在 Sublime 里，光配好调试环境就花了两天。这不是玄学，是工具链咬合度带来的真实时间差。很多人一上来就问“VSCode 和 PyCharm 哪个好”，我的回答永远是：如果你每天写 Python 不超过 2 小时，PyCharm 的启动速度和内存占用会让你怀疑人生；如果你要同时维护 Django、FastAPI、数据清洗脚本和 Jupyter 探索性分析，VSCode 的模块化架构能让你在同一个窗口里切换身份，不卡顿、不重启、不丢上下文。

核心关键词就三个： 轻量、可塑、无感 。轻量不是指它体积小（其实它不小），而是指它的“心智负担”极低——你不需要记住“这个功能藏在哪一级菜单里”，90% 的操作靠 Ctrl+Shift+P （命令面板）输入关键词就能直达；可塑是指它没有预设的开发范式，你可以把它变成纯文本编辑器、Jupyter 实验室、Django 调试台，甚至嵌入式 Python 终端；无感则是最高级的体验：当你写代码时，它不该存在。它不该弹窗打断你的思路，不该在你按 Enter 后多缩进两格让你删三次，不该在你刚写完 def 就强行补全一堆你根本不需要的参数。VSCode 的 Python 扩展生态，恰恰是在“智能”和“克制”之间找到了那个微妙的平衡点。

我见过太多新手被 PyCharm 的“智能提示”反向驯化：IDE 提示你加类型注解，你就真去加；提示你拆函数，你就机械地拆；结果代码越来越“规范”，可逻辑越来越绕。而 VSCode 的 Pylance 引擎，它的提示是“建议型”的——它告诉你 user_id: int 更安全，但如果你写 user_id = request.args.get('id') ，它不会报错，只会悄悄在变量名下画一条灰线，鼠标悬停才显示“可能为 None”。这种“提醒但不强制”的设计，对学习者更友好，也更贴近真实工程场景。它不替你思考，但永远在你思考的旁边递上一杯水。

这套工作流我用了七年，从单人脚本到百人协作的金融风控平台，从树莓派上的传感器采集到 AWS 上跑的实时推荐服务，底层逻辑没变过： Python 解释器是心脏，VSCode 是神经中枢，所有扩展都是可插拔的感官器官 。今天这篇指南，不讲“怎么安装”，而是带你算清楚每一笔效率账：为什么选 Flake8 而不是 Pylint？为什么 Black 格式化要关掉 --skip-string-normalization ？为什么 Jupyter 内核一定要手动指定路径而不是依赖自动发现？这些细节背后，全是我在上百个项目里踩坑、记录、验证后沉淀下来的硬经验。接下来的内容，每一行配置、每一个快捷键、每一次右键菜单的选择，都对应着一个具体的问题场景和明确的解决目标。我们不堆概念，只聊“你按下这个键之后，电脑到底做了什么”。

2. 环境搭建：从零开始的每一步，都藏着避坑密码

2.1 Python 安装：别迷信 Anaconda，也别硬刚源码编译

很多人一上来就装 Anaconda，理由很朴素：“听说它自带包，省事”。这话对一半。Anaconda 确实省了 pip install numpy pandas matplotlib 的时间，但它埋了三个深坑：第一，它默认的 base 环境会污染系统 PATH，导致你在终端里敲 python 时，实际调用的是 Anaconda 的 Python，而 VSCode 里却可能选中了系统 Python，结果 import torch 在终端成功，在 IDE 里报错；第二，Conda 的包管理比 pip 慢得多，更新一个包动辄三分钟，而 pip install --upgrade requests 通常三秒搞定；第三，也是最致命的，Anaconda 的 conda-forge 渠道里，某些科学计算包（比如 numba ）的 Windows 版本经常有 ABI 兼容问题，导致 import numba 直接 segmentation fault。

我的方案是： 系统 Python + venv + pip ，三件套组合拳。Windows 用户直接去 python.org 下载最新稳定版（注意勾选 “Add Python to PATH”），macOS 用户用 Homebrew： brew install python ，Linux 用户用 apt install python3 python3-venv 。关键动作来了：安装完立刻打开终端，执行：

python -m venv ~/venvs/py311
source ~/venvs/py311/bin/activate  # macOS/Linux
# 或者 Windows: ~/venvs/py311/Scripts/activate.bat
pip install --upgrade pip setuptools wheel

这一步创建了一个干净、隔离的 Python 环境，路径固定在 ~/venvs/py311 。为什么路径要固定？因为 VSCode 的 Python 扩展在项目根目录下找不到 .venv 或 venv 文件夹时，会自动扫描你硬盘上所有已知的虚拟环境路径。如果路径不固定，它可能扫到你三年前为某个废弃项目创建的、早已损坏的环境，然后死活不让你选正确的那个。固定路径，等于给 VSCode 一个确定的“寻宝地图”。

提示：不要用 py -3.11 -m venv myenv 这种带版本号的命令。Windows 的 py 启动器在某些企业网络环境下会被组策略禁用，导致 py 命令根本不存在。直接用 python -m venv ，兼容性 100%。

2.2 VSCode 安装：拒绝“一键傻瓜”，拥抱 CLI 启动

VSCode 官网下载安装包，这步没得选。但安装完别急着双击图标启动。打开终端，执行：

code --version
code --list-extensions

如果第一条命令报 command not found ，说明你漏掉了安装时的“Add to PATH”选项。这时候别卸载重装，直接去 VSCode 的菜单栏： Shell Command: Install 'code' command in PATH （Windows/macOS 都有这个选项）。这个动作会在你的 shell 配置文件（ .zshrc 或 .bash_profile ）里追加一行 export PATH="$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin" （macOS）或类似路径（Windows）。这是后续所有高效操作的基础——没有 code 命令，你就失去了“在任意文件夹里一键打开当前项目”的能力。

注意：安装完 VSCode 后，首次启动会弹出“是否允许访问辅助功能”的系统级授权框。必须点“允许”，否则后续的屏幕阅读器支持、键盘焦点管理会失效，导致 F5 调试时焦点乱跳。这个授权在 macOS 的“系统设置 > 隐私与安全性 > 辅助功能”里可以手动添加，但首次弹窗时点“允许”是最省事的。

2.3 第一个 Python 文件：从 `print("Hello World")` 到真正理解“解释器选择”

新建文件、保存为 hello.py 、按 Ctrl+F5 运行……这看似简单的三步，背后是 VSCode 最容易被误解的核心机制。很多人以为“运行”就是执行 python hello.py ，其实不然。VSCode 的“运行”按钮，本质是调用它当前选中的 Python 解释器（interpreter）来执行。这个解释器，不是你系统里装的那个 Python，而是 VSCode 记录的一个绝对路径，比如 /Users/you/venvs/py311/bin/python 。

验证方法：在 hello.py 文件里写：

import sys
print(sys.executable)
print(sys.path[0])

然后按 Ctrl+Shift+P ，输入 Python: Select Interpreter ，你会看到一个列表，里面可能有：

/usr/bin/python3 （系统 Python）
/Users/you/anaconda3/bin/python （Anaconda）
/Users/you/venvs/py311/bin/python （你刚创建的）

必须手动选中第三个 。为什么？因为 sys.path[0] 输出的是当前脚本所在目录，而 sys.executable 才是真正执行代码的 Python 可执行文件路径。只有当这两个路径指向同一个虚拟环境时，你 pip install 的包才能被正确导入。我见过太多人在这里栽跟头：在终端里 pip install requests 成功，但在 VSCode 里 import requests 报 ModuleNotFoundError ，根源就是解释器选错了。

实操心得：VSCode 的解释器选择是“项目级”的。你在一个文件夹里选了 py311 ，关闭 VSCode，再打开另一个文件夹，它会重新扫描并可能选中别的解释器。所以， 每个 Python 项目根目录下，务必放一个 .vscode/settings.json 文件，内容为 ：
{
  "python.defaultInterpreterPath": "/Users/you/venvs/py311/bin/python"
}
这样，无论你从哪打开这个文件夹，VSCode 都会自动加载这个配置，永不迷路。

3. 核心扩展与配置：不是装得越多越好，而是每一件都精准命中痛点

3.1 Python 扩展包：Pylance、Jupyter、isort 的协同逻辑

VSCode Marketplace 里搜 “Python”，第一个结果是 Microsoft 官方的 “Python” 扩展。安装它，就自动连带装上了 Pylance、Jupyter、isort 三个子扩展。但很多人不知道，这三个组件的职责边界非常清晰，且存在严格的加载顺序：

Pylance 是语言服务器（Language Server），负责代码补全、跳转定义、类型检查。它不执行代码，只“看”代码。
Jupyter 是内核管理器（Kernel Manager），负责连接、启动、通信 Jupyter Notebook/Lab 的 Python 内核。它不渲染图表，只管“管道”。
isort 是代码整理器（Code Formatter），专门处理 import 语句的排序和分组。它不碰函数体，只动 import 。

它们的协同关系是：当你在 .py 文件里写 import numpy as np ，Pylance 实时检查 numpy 是否在当前解释器的 sys.path 里；当你打开 .ipynb 文件，Jupyter 扩展根据你选中的内核（比如 python3.11 ）启动对应的 ipykernel 进程；当你按 Shift+Alt+F 格式化代码，isort 会先于 black 运行，确保所有 import 语句按字母顺序排列，且标准库、第三方库、本地库严格分三段。

关键配置：Pylance 默认开启“类型检查”，这会导致大型项目（如 Django）加载极慢。在 settings.json 里加：
"python.analysis.typeCheckingMode": "off",
"python.analysis.autoSearchPaths": false,
"python.analysis.extraPaths": ["./src"]
关闭全局类型检查，但允许你手动指定 src 目录为源码路径。这样既保住了补全速度，又不失对自定义模块的识别能力。

3.2 Indent Rainbow 与 Python Indent：两个解决同一问题的“左膀右臂”

Python 的缩进是语法的一部分，不是风格偏好。 Indent Rainbow 和 Python Indent 看似功能重叠，实则分工明确：

Indent Rainbow 是“视觉校验员”。它给每一级缩进涂上不同颜色（1 级蓝、2 级绿、3 级黄……），让你一眼看出 if 块里是不是多缩进了一格，或者 for 循环结尾少缩进了一格。它不修改代码，只改变显示。
Python Indent 是“行为矫正器”。当你在 if condition: 后按 Enter ，它会自动计算下一行应该缩进 4 个空格；当你在缩进的代码行末尾按 Enter ，它会自动保持相同缩进；当你按 Shift+Enter ，它会自动退回到上一级缩进。它直接干预你的键盘输入行为。

我同时启用两者，因为它们解决的是不同维度的问题：前者防“眼误”，后者防“手误”。实测下来， Python Indent 在处理多层嵌套的字典推导式时特别稳，比如：

# 你只需要敲：
data = {k: v for k, v in items.items() if k.startswith('a')}

# Python Indent 会确保 for 和 if 的缩进层级完全对齐，不会出现：
data = {k: v for k, v in items.items() 
if k.startswith('a')}  # 错！if 缩进错误

注意： Python Indent 的默认行为是“按 Tab 键插入空格”，但很多老 Python 人习惯用 Tab 键切换缩进层级。你可以在 settings.json 里加：
"editor.detectIndentation": false,
"editor.insertSpaces": true,
"editor.tabSize": 4,
"editor.trimAutoWhitespace": true
强制关闭自动检测缩进，统一用 4 个空格，并在行尾自动删除多余空格——这是 PEP 8 的硬性要求。

3.3 autoDocstring：不是生成文档，而是建立代码契约

autoDocstring 扩展的价值，远不止于“快速生成 """ 注释”。它的核心作用是 在函数签名和文档字符串之间建立双向契约 。当你写：

def calculate_tax(amount: float, rate: float) -> float:
    """Calculate tax amount.
    
    Args:
        amount: The pre-tax amount.
        rate: Tax rate as decimal (e.g., 0.08 for 8%).
        
    Returns:
        The tax amount.
    """
    return amount * rate

autoDocstring 会实时解析函数签名里的 amount: float, rate: float 和 -> float ，并自动填充到 Args 和 Returns 区域。更重要的是，当你后续修改函数签名，比如把 rate 改成 tax_rate: float ， autoDocstring 会高亮提示你文档里的 rate 参数名已过期，需要同步更新。

这解决了 Python 开发中最隐蔽的“文档腐烂”问题：代码改了，文档忘了改，结果新同事照着旧文档传参， calculate_tax(100, 0.08) 看起来没问题，但实际函数签名已是 calculate_tax(amount, tax_rate) ，导致静默的逻辑错误。

实操技巧： autoDocstring 支持多种文档格式（Google、NumPy、reStructuredText）。在 settings.json 里指定：
"autoDocstring.docstringFormat": "google",
"autoDocstring.includeName": false,
"autoDocstring.includeType": true
Google 格式最易读； includeName: false 避免在文档里重复函数名（ calculate_tax ）； includeType: true 强制把类型注解（ float ）写进文档，让契约更完整。

4. 深度配置：Linting、Formatting、Debugging 的黄金参数组合

4.1 Linting：Flake8 是起点，不是终点

VSCode 的 Python 扩展默认提供 Pylint、Flake8、pycodestyle 三种 linter。我选 Flake8，原因很实在： 它快、准、不啰嗦 。Pylint 功能全面但太重，一个 500 行的文件扫描要 8 秒，且大量“建议类”警告（比如“函数名太短”）干扰核心问题；pycodestyle 只检查 PEP 8，漏掉逻辑错误。

但原生 Flake8 有个硬伤：它默认不检查未使用的变量（ unused variable 'x' ）和未定义的名称（ undefined name 'y' ）。这恰恰是新手最常见的两类错误。解决方案是给 Flake8 加两个插件：

pip install flake8-unused-arguments flake8-undefined-variable

然后在项目根目录创建 .flake8 配置文件：

[flake8]
max-line-length = 88
extend-ignore = E203, W503
select = C,E,F,W,B,B950
per-file-ignores = __init__.py:F401

max-line-length = 88 ：Black 格式化的默认行宽，保持 linting 和 formatting 一致。
extend-ignore ：忽略 PEP 8 中关于冒号前后空格的争议性规则（E203）和反斜杠续行（W503），避免和 Black 冲突。
select ：C（复杂度）、E（错误）、F（flake8 自身）、W（警告）、B（bug 类）、B950（行过长）——覆盖所有关键问题。
per-file-ignores ：在 __init__.py 里忽略 F401（未使用导入），因为 __init__.py 的主要作用就是暴露接口，导入但不使用是正常行为。

提示：VSCode 的 Flake8 配置必须和你终端里 flake8 . 的配置完全一致，否则会出现“VSCode 里没报错，CI 流水线却失败”的尴尬。把 .flake8 文件放在项目根目录，VSCode 会自动识别。

4.2 Formatting：Black 的“不妥协”哲学与必要妥协

Black 是 Python 社区事实上的格式化标准，它的口号是“无需配置，所见即所得”。但这句话有个前提： 你接受它的全部规则 。比如，Black 会把：

result = some_function(
    arg1, arg2,
    arg3, arg4
)

强制格式化为：

result = some_function(arg1, arg2, arg3, arg4)

这对简单函数很清爽，但对带大量关键字参数的函数（如 pandas.read_csv ）就灾难了：

# Black 强制压成一行（超长！）
df = pd.read_csv("data.csv", sep=",", header=0, index_col=None, usecols=["a", "b", "c"], dtype={"a": "str"})

# 正确做法：告诉 Black “这里必须换行”
df = pd.read_csv(
    "data.csv",
    sep=",",
    header=0,
    index_col=None,
    usecols=["a", "b", "c"],
    dtype={"a": "str"},
)

如何让 Black 尊重你的换行意图？答案是 # fmt: on/off 注释：

# fmt: off
df = pd.read_csv(
    "data.csv",
    sep=",",
    header=0,
    index_col=None,
    usecols=["a", "b", "c"],
    dtype={"a": "str"},
)
# fmt: on

VSCode 的 Black 配置在 settings.json 里：

"python.formatting.provider": "black",
"python.formatting.blackArgs": [
    "--line-length", "88",
    "--skip-string-normalization"
],
"editor.formatOnSave": true,
"editor.formatOnType": false

--skip-string-normalization 是关键：它禁止 Black 把 'hello' 自动改成 "hello" ，或把多行字符串的引号格式化，避免破坏正则表达式和 SQL 字符串的原始语义。
formatOnType: false 是为了性能：实时格式化会拖慢大文件编辑， formatOnSave 足够。

实操心得：在团队项目里，必须把 pyproject.toml 作为 Black 的唯一配置源，而不是 VSCode 设置。在 pyproject.toml 里写：
[tool.black]
line-length = 88
skip-string-normalization = true
include = '\.pyi?$'
exclude = '''
/(
    \.git
  | __pycache__
  | build
)/
'''
这样，VSCode、CI 流水线、同事的编辑器，全部遵循同一份配置，杜绝“格式化地狱”。

4.3 Debugging：从 `print()` 到条件断点的思维跃迁

VSCode 的调试器强大到让人忘记 print() 的存在。但新手常犯一个错误：在 for i in range(1000): 循环里，对每一行都加断点，结果调试器卡死。真正的高手用的是 条件断点（Conditional Breakpoint） 和 日志点（Logpoint） 。

条件断点 ：右键点击行号左侧的红点，选择 “Edit Breakpoint”，输入 i == 999 。这样，调试器只在 i 等于 999 时暂停，前面 998 次循环全速执行。
日志点 ：按 Ctrl+Shift+P ，输入 “Debug: Toggle Log Point”，在行号旁输入 i = {i}, value = {data[i]} 。它不会暂停程序，只在调试控制台输出日志，效果等同于 print(f"i = {i}, value = {data[i]}") ，但无需修改源码，且可随时开关。

更高级的技巧是 “仅此一次”断点 ：在断点上右键，选择 “Hit Count”，设为 “Break when hit count is equal to”，输入 1 。这相当于“执行到这一行就停，不管循环多少次”，适合调试初始化逻辑。

关键配置：VSCode 的 launch.json 调试配置，默认是 console: "integratedTerminal" 。这会导致 input() 函数无法从调试终端读取输入。必须改成：
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "module": "debugpy",
      "justMyCode": true,
      "console": "integratedTerminal",
      "subProcess": true,
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}
subProcess: true 允许调试器捕获子进程（如 subprocess.run ）， env.PYTHONPATH 确保调试时能正确导入本地模块。

5. 高阶实战：Jupyter、Git、AI 辅助的无缝工作流

5.1 Jupyter Notebook：在 VSCode 里做“真·交互式开发”

VSCode 的 Jupyter 支持，远不止于“在编辑器里打开 .ipynb 文件”。它的核心价值在于 打破 .py 和 .ipynb 的壁垒 。你可以把一个 .py 文件，当成一个“隐藏的 notebook”来用。

操作步骤：

打开任意 .py 文件（比如 analysis.py ）。
在代码行上方，点击 “+ Code” 按钮（或按 Ctrl+Shift+P 输入 “Jupyter: Insert Cell Above”）。
这个 .py 文件就变成了一个混合体：普通 Python 代码 + 可执行的 cell。

好处是什么？ 版本控制友好 。 .ipynb 文件是 JSON 格式，Git diff 一团糟；而 .py 文件是纯文本， git diff 清晰显示你改了哪一行代码。更重要的是，你可以把探索性分析（Jupyter）和生产代码（ .py ）写在同一个文件里，用 # %% 分隔：

# %%
import pandas as pd
df = pd.read_csv("data.csv")

# %%
df.head()

# %%
# 这是生产代码，会被打包进模块
def clean_data(df):
    return df.dropna()

VSCode 会自动识别 # %% 为 cell 分隔符，并提供和 notebook 完全一致的运行、调试、变量查看功能。这才是数据科学家该有的工作流：探索用 cell，封装用函数，一切都在一个 .py 文件里完成。

注意：VSCode 的 Jupyter 内核必须手动指定。不要依赖“自动选择”，因为自动选择可能选中系统 Python，而你的数据分析包（如 plotly ）只装在 py311 环境里。按 Ctrl+Shift+P ，输入 “Jupyter: Select Interpreter”，手动选中 /Users/you/venvs/py311/bin/python 。这个选择会保存在 .ipynb 文件的元数据里，确保每次打开都用对环境。

5.2 Git 集成：从“提交代码”到“重构自信”的质变

VSCode 的 Git 面板（ Ctrl+Shift+G ）最大的价值，不是让你少敲几条命令，而是 把 Git 操作可视化、原子化、可逆化 。比如，你想把一个函数从 utils.py 移到 core.py ，传统做法是：

剪切函数代码
粘贴到 core.py
在 utils.py 里删掉函数
git add utils.py core.py
git commit -m "move function"

这个过程风险极高：万一粘贴错了，或者忘了删 utils.py 里的旧代码，Git 记录的就是一个“脏”状态。

VSCode 的正确姿势是：

在 utils.py 里选中函数，按 F2 （重命名），输入新名字 core.move_function 。
VSCode 会自动在 core.py 里创建 move_function 函数，并在 utils.py 里替换所有调用。
打开 Git 面板，你会看到 utils.py 和 core.py 都有修改，但修改内容是“精确的函数移动”，不是“随机的文本增删”。
点击 core.py 左侧的 + 号，只暂存这个文件； utils.py 的修改先不暂存。
提交，消息写 “feat(core): add move_function”。

这个流程里， F2 重命名是 Git 感知的“重命名操作”，不是“删除+新增”，Git 的 git log --follow 能完整追踪函数的历史。这才是专业级重构的底气。

提示：VSCode 的 Git 面板右上角有个 “...” 菜单，里面有 “Stage Selected Ranges”（暂存选中范围）。当你只改了一个函数的几行，不想暂存整个文件时，选中这几行，右键选择这个选项，Git 只记录这几行的变更，极大提升代码审查（Code Review）的精准度。

5.3 GitHub Copilot：不是写代码的“外挂”，而是思考的“加速器”

Copilot 的最大误区，是把它当“自动补全升级版”。实际上，它的正确用法是 用自然语言描述“我要做什么”，让它生成“怎么做”的骨架，然后你来审核、修改、注入业务逻辑 。

比如，你要写一个函数，从字符串里提取所有邮箱地址。不要自己写正则，而是：

在函数定义处，写注释：

# Extract all email addresses from a text string using regex
def extract_emails(text: str) -> List[str]:

按 Ctrl+Enter ，Copilot 会生成完整的函数体，包括 import re 和正则表达式。
你做的不是“复制粘贴”，而是：
- 检查正则是否覆盖了 user+tag@domain.co.uk 这类复杂邮箱；
- 把 re.findall 改成 re.finditer ，以便获取匹配位置；
- 加上 @lru_cache 装饰器，避免重复编译正则。

Copilot 的价值，在于把“查文档、写样板、拼语法”这些机械劳动外包出去，让你的脑力 100% 聚焦在“这个业务规则到底该怎么实现”上。我测试过，用 Copilot 写一个带异常处理的 API 调用函数，平均节省 4 分钟；而不用它，光查 requests 文档和 try/except 最佳实践就要 3 分钟。

关键配置：Copilot 的提示质量极度依赖上下文。在 settings.json 里加：
"github.copilot.advanced": {
  "inlineSuggest.enable": true,
  "showSuggestionsInComments": true,
  "suggestAtCursor": true
},
"editor.suggest.showInlineDetails": true
开启内联建议、注释内建议、光标处建议，并显示详细文档。这样，当你在注释里写 # Send POST request to /api/v1/users with JSON body ，Copilot 会直接在你光标下方给出 requests.post(...) 的完整调用，参数名、类型、示例值一应俱全。

6. 常见问题排查：那些让你抓狂半小时，其实只需改一行配置的故障

6.1 “ImportError: No module named XXX” —— 90% 是路径和解释器的战争

现象：终端里 python script.py 运行正常，VSCode 里按 F5 就报 ImportError 。

排查步骤：

在 VSCode 的 script.py 里加 import os; print(os.getcwd()) ，确认当前工作目录是你期望的项目根目录。
加 import sys; print('\n'.join(sys.path)) ，确认你的包路径（如 ./src ）在 sys.path 列表里。
按 Ctrl+Shift+P ，输入 Python: Select Interpreter ，确认选中的是你 pip install 包的那个环境（比如 ~/venvs/py311/bin/python ）。

如果 sys.path 里没有 ./src ，在项目根目录的 .vscode/settings.json 里加：

"python.defaultInterpreterPath": "/path/to/your/venv/bin/python",
"python.defaultExtraPaths": ["./src"]

根本原因：VSCode 的 Python 扩展默认只把当前文件所在目录和解释器的 site-packages 加入 sys.path ，不会自动包含 src 这样的源码目录。 defaultExtraPaths 就是专门解决这个问题的。

6.2 “Debugger not working” —— 检查 `launch.json` 的三个致命字段

现象：按 F5 启动调试，VSCode 显示 “Starting debugger”，然后就卡住，无响应。

检查 launch.json 的这三个字段：

"module": "debugpy" ：必须存在，且值为 "debugpy" 。旧版配置可能是 "python" ，已废弃。
"console": "integratedTerminal" ：如果设为 "internalConsole" ，在某些 macOS 版本上会卡死。
"justMyCode": true ：如果设为 false ，调试器会尝试进入 site-packages 里的第三方库源码，导致无限加载。

一个最小可用的 launch.json ：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "module": "debugpy",
      "justMyCode": true,
      "console": "integratedTerminal",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}

6.3 “Jupyter kernel dies immediately” —— 内核路径权限的隐形杀手

现象：点击 “Select Kernel”，选中 Python 3.11 ，VSCode 显示 “Connecting to kernel…”，然后报错 “Kernel died, restarting”。

根本原因：VSCode 启动 Jupyter 内核时，用的是它自己的用户权限，而你的虚拟环境（ ~/venvs/py311 ）可能属于另一个用户，或者权限被锁死。

解决方案：

终端里执行 ls -la ~/venvs/py311/bin/ ，确认 python 文件有可执行权限（ -rwxr-xr-x ）。
如果没有，执行 chmod +x ~/venvs/py311/bin/python 。
更彻底的方案：在 ~/.jupyter/jupyter_notebook_config.py 里加：
```
import os
c.NotebookApp.kernel_spec_manager_class = 'jupyter_client.kernelspec.KernelSpecManager'
c.KernelSpecManager.ensure_native_kernel = False
```
这会强制 Jupyter 使用 ipykernel 而不是系统内核，绕过权限问题。

6.4 “Copilot suggestions are irrelevant” —— 上下文窗口的容量陷阱

现象：Copilot 给的代码建议完全不相关，比如你在写数据库查询，它建议你写 print("hello") 。

原因：Copilot 的上下文窗口（Context Window）有限，它只能看到你当前文件的“最近 200 行”和“光标附近 50 行”。如果你的文件太大（>1000 行），或者光标离关键代码太远，它就“失忆”了。

解决方法：

把光标移到你要写代码的位置（比如函数定义下方）。
按 Ctrl+K Ctrl+I （Copilot: Open Chat），在聊天框里用自然语言描述需求，比如 “Write a SQLAlchemy query to get users with status='active'”。
Copilot 会基于整个对话历史生成建议，准确率飙升。