VSCode的Python调试必须手动配置launch.json，因其决定F5运行行为；需正确设置args（各参数独立）、cwd（工作目录）、program（脚本路径）、env/envFile（环境变量）及python解释器路径，否则易报错或行为异常。
VSCode 的 Python 启动配置靠 launch.json 驱动，不是靠 settings.json —— 后者只管编辑体验，前者才决定“按下 F5 时到底怎么跑你的脚本”。
为什么 launch.json 必须手动配，不能只靠默认生成
VSCode 自动生成的 launch.json（比如选“Python: 当前文件”）只填了最简字段：program、console、justMyCode。但真实项目几乎都绕不开这些：
- 命令行参数（
args）—— 比如--config config.yaml --verbose - 工作目录（
cwd）—— 脚本依赖相对路径读取数据或写日志，不设就报FileNotFoundError - 环境变量（
env或envFile）—— 如CUDA_VISIBLE_DEVICES=0或加载.env里的密钥 - 解释器路径（
python字段）—— 默认用全局解释器，但项目用虚拟环境时必须显式指定
漏掉任一项，F5 一按就报错或行为异常，且错误信息往往不直接指向配置问题。
args 字段怎么写才不会被 shell 解析错
很多人把终端里能跑通的命令直接塞进 args，比如："args": ["--data_dir ./dataset --epochs 20"] —— 这会当成一个整体字符串传给 argparse，导致解析失败。
立即学习“Python免费学习笔记（深入）”；
正确做法是每个参数单独成项，空格不写进字符串里：
{
"args": ["--data_dir", "./dataset", "--epochs", "20", "--lr", "0.0005"]
}
注意：
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 布尔型参数如
--debug直接写"--debug"，不用带值 - 路径尽量用
${workspaceFolder}变量，避免硬编码（如"${workspaceFolder}/data"） - 如果参数本身含空格（比如文件名
"my file.txt"），必须用双引号包裹整个字符串，且launch.json里要转义："\"my file.txt\""
cwd 和 program 的路径逻辑容易搞反
program 是你要运行的 Python 文件路径，cwd 是它执行时的当前工作目录 —— 二者独立，但常被混用。
典型错误场景：
- 脚本里写了
open("config.json")，但config.json在项目根目录，而program是src/train.py，此时必须设"cwd": "${workspaceFolder}"，否则找不到文件 -
program写成"${workspaceFolder}/src/train.py"没问题，但若cwd错设为"${workspaceFolder}/src"，可能导致日志写到错目录或导入失败 -
${file}只在调试当前打开文件时安全；批量调试多个脚本时，必须显式写死program路径，否则切换文件后 F5 就跑错脚本
env 和 envFile 别同时用，优先选后者
env 适合临时加一两个变量（如 "CUDA_VISIBLE_DEVICES": "0"），但密钥、数据库地址等敏感或大量变量，硬编码进 JSON 很危险也难维护。
更稳妥的做法是用 envFile 指向本地 .env 文件：
"envFile": "${workspaceFolder}/.env"
注意：
-
.env文件内容格式必须是KEY=VALUE（无空格、无引号），例如：DATABASE_URL=sqlite:///db.sqlite -
envFile不会覆盖env，两者合并生效；但若键名重复，env里的值会覆盖envFile中的 -
.env必须放在gitignore里，别提交到仓库
复杂项目里，launch.json 的坑不在语法，而在路径、作用域和变量替换的隐式行为 —— 多数报错其实不是代码问题，而是调试上下文没对齐。
