vscode连不上树莓派python环境，主因未使用remote-ssh扩展而仅用sftp；须启用树莓派ssh、安装remote-ssh扩展、手动ssh免密登录、手动指定远程python解释器路径、配置launch.json的pathmappings映射本地与远程项目路径。
VSCode怎么连上树莓派的Python环境
连不上，多半是没走 SSH 远程开发通道，而是只开了 SFTP 同步——那只是传文件，不是真连接。VSCode 的 Remote-SSH 扩展才是关键，它让编辑器直接运行在树莓派上，python、pip、venv 全部调用远端命令，补全和调试才真正生效。
- 必须在树莓派上启用 SSH：
sudo systemctl enable ssh && sudo systemctl start ssh - 本地 VSCode 安装官方扩展：
Remote - SSH（不是Remote - SSH: Editing Configuration Files那个子扩展） - 连接前先手动 SSH 通一次：
ssh pi@192.168.x.x，确认能免密登录（否则 VSCode 会卡在密码输完后无响应） - 连接成功后，在远程窗口里打开终端，执行
which python3，确保路径是树莓派上的真实路径（比如/usr/bin/python3），而不是本地的
Python解释器选不对，自动补全就失效
VSCode 默认不会自动识别树莓派里的 Python 解释器，即使你看到 python3 命令可用，也得手动指定解释器路径，否则 import 补全、类型提示、linting 全都掉链子。
- 按
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入并选择：Python: Select Interpreter - 选
Enter interpreter path...→Browse→ 手动导航到树莓派上的/usr/bin/python3或虚拟环境里的./venv/bin/python - 别选
Python 3.9 (Global)这类本地解释器选项——那是你本机的，对树莓派项目完全无效 - 如果用了
venv，务必在远程终端里先激活再创建：python3 -m venv venv，然后选venv/bin/python；直接在本地建好再同步过去，路径和依赖会错乱
调试时断点不命中？检查 launch.json 的路径映射
树莓派和你本地文件系统结构不同，VSCode 调试器找不到源码位置，断点就灰了。根本原因是 launch.json 缺少 pathMappings，调试器不知道“我本地打开的 main.py 对应树莓派上哪个路径”。
- 在远程项目根目录下建
.vscode/launch.json，内容必须包含pathMappings字段 - 示例（假设你在本地把项目克隆到
/Users/me/pi-project，树莓派上在/home/pi/pi-project）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Current File",
"type": "python",
"request": "launch",
"module": "python",
"justMyCode": true,
"pathMappings": [
{
"localRoot": "/Users/me/pi-project",
"remoteRoot": "/home/pi/pi-project"
}
]
}
]
}
/Home/pi 和 /home/pi 是两个地方launch.json 后，重启调试会话（不能只点“重新启动”）树莓派资源吃紧，VSCode Remote 突然卡死或断连
树莓派 4B（尤其 2GB 版）跑 VSCode Remote + Python + 调试器 + 终端，内存很容易爆。不是插件问题，是物理限制——code-server 模式更轻量，但原生 Remote-SSH 是最稳的，得靠精简来扛住。
- 关掉所有非必要扩展：特别是
Pylance（开typeCheckingMode: basic就够）、GitLens、图标主题类扩展 - 在远程设置中禁用文件监视：
"files.watcherExclude": {"**/.git/objects/**": true, "**/venv/**": true} - 避免在远程打开整个
/home/pi目录，只打开具体项目文件夹（比如/home/pi/sensor-app） - 如果频繁断连，检查树莓派是否启用了休眠：
sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target
路径映射写错、解释器没切到远程、SSH 没配免密——这三个点卡住的人最多。其他都是优化项，先跑通再调快。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
