vs code 中无法从同目录文件导入模块，通常因 python 解释器未将当前工作目录加入 sys.path，需通过配置环境变量、创建可安装包或正确使用 -m 方式运行来解决。
在 Python 中，模块导入依赖于 sys.path —— 一个决定“从哪找模块”的路径列表。Python 默认不会自动将当前工作目录（Current Working Directory, CWD）加入 sys.path，尤其在 VS Code 中，即使 .py 文件与被导入文件位于同一文件夹，若执行方式或解释器环境配置不当，from test_file import Rock 仍会触发 Import "test_file" could not be resolved（Pylance 报错）或运行时 ModuleNotFoundError。
✅ 正确做法：优先使用 -m 模块模式运行
确保项目结构清晰，并以包（package）形式组织代码：
my_project/ ├── __init__.py # 使目录成为 Python 包 ├── main.py # 入口脚本（含 from test_file import Rock） └── test_file.py # 定义 class Rock
⚠️ 关键前提：main.py 不能直接双击运行或用 python main.py 执行，而应从 my_project 的父目录下，以模块方式调用：
cd .. # 进入 my_project 的上一级 python -m my_project.main
此时 Python 将 my_project 视为顶层包，main.py 中的 from test_file import Rock（或更规范的 from .test_file import Rock）才能被正确解析。
立即学习“Python免费学习笔记（深入）”；
✅ 替代方案（按推荐度排序）
| 方案 | 操作 | 适用场景 | 注意事项 |
|---|---|---|---|
| 1. 配置 VS Code 工作区 Python 路径 | 在 .vscode/settings.json 中添加： "python.defaultInterpreterPath": "./venv/bin/python" 并确保 venv 激活且 PYTHONPATH 包含当前目录 |
快速调试单文件项目 | 可配合 "python.envFile": ".env" 设置 PYTHONPATH=. |
| 2. 创建可安装包（推荐长期项目） | 添加 pyproject.toml： toml [build-system] requires = ["setuptools"] build-backend = "setuptools.build_meta" 然后执行 pip install -e . | 多模块、可复用项目 | 需要 __init__.py，安装后任意位置均可导入 |
||
| 3. 运行时动态追加路径（仅限开发/学习） | 在 main.py 开头插入： import sys; from pathlib import Path; sys.path.insert(0, str(Path(__file__).parent)) |
临时绕过限制 | ❌ 不推荐用于生产或团队协作，破坏可移植性 |
⚠️ 常见误区澄清
- from .test_file import Rock 是相对导入，仅在包内模块中有效，不能用于直接运行的脚本（如 python main.py），否则报 SystemError: Parent module '' not loaded。
- macOS 系统更新通常不直接影响 Python 导入机制，但可能重置终端默认 shell 或 VS Code 的 Python 解释器选择，建议检查 VS Code 左下角 Python 解释器路径是否指向预期虚拟环境。
- Pylance 报错（reportMissingImports）是静态分析警告，有时与实际运行结果不一致；可先运行脚本验证是否真报错，再针对性修复。
✅ 一句话总结
不要依赖“同目录即自动可导入”，而应主动构建包结构 + 使用 python -m 运行，或通过 pip install -e . 将项目注册为可导入包——这是符合 Python 最佳实践、跨平台稳定、且被 VS Code/Pylance 完全支持的标准方案。
