直接运行文件找不到项目包

问题：VSCode 点击 ▶ 运行 Python 文件找不到项目包

报错：ModuleNotFoundError: No module named 'portfolio'

根因

python file.py 运行时，Python 只把文件所在目录加入 sys.path，不会把项目根目录加入。所以 from portfolio.xxx import yyy 找不到包。

python -m portfolio.plan.etf_demo 则会把当前工作目录加入 sys.path，所以能正常工作。

三类场景及解决方案

场景一：VSCode 创建的项目

项目特征：通常是 Python 扩展的 New Project 模板生成的，结构简单，有虚拟环境
最佳方案：根目录创建 .env 文件

PYTHONPATH=D:\path\to\project

VSCode 会自动加载 .env，无需额外配置。

场景二：Git 拉取的项目（推荐）

项目特征：通常有 setup.py / pyproject.toml / setup.cfg
最佳方案：执行 pip install -e .（以可编辑模式安装项目包）

pip install -e .

这是 Python 标准做法，安装后包全局可导入，不再依赖 PYTHONPATH。所有运行方式（▶、F5、命令行）都能正常工作。

场景三：PyCharm 项目在 VSCode 打开（当前项目）

项目特征：PyCharm 通过 "Sources Root" 自动把源码目录加入 PYTHONPATH，VSCode 不识别此标记
最佳方案：项目级 .vscode/settings.json + .env 双重保障

.vscode/settings.json：

{
    "python.envFile": "${workspaceFolder}/.env",
    "terminal.integrated.env.windows": {
        "PYTHONPATH": "D:\\path\\to\\project"
    }
}

.env：

PYTHONPATH=D:\path\to\project

python.envFile：Python 扩展在运行文件时加载 .env 的环境变量
terminal.integrated.env.windows：所有 VSCode 终端都设置 PYTHONPATH
双重保障，任意一个生效就能解决

其他运行方式

模块模式（推荐日常开发）：python -m portfolio.plan.etf_demo，从项目根目录运行，不需要任何配置
F5 调试：创建 .vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Module",
            "type": "debugpy",
            "request": "launch",
            "module": "portfolio.plan.etf_demo"
        }
    ]
}

优先级建议

有 setup.py/pyproject.toml → pip install -e .（最规范）
无包管理文件 → .vscode/settings.json + .env（最通用）
临时运行 → python -m（无需配置）