ModuleNotFoundError的根本原因是Python解释器未将目标文件夹纳入模块搜索路径（sys.path），解决关键是通过Sources Root标记或规范包结构（含__init__.py）让Python明确识别该目录为有效模块路径。
ModuleNotFoundError 是你第一次尝试导入项目外文件夹时最常遇到的报错，根本原因不是 PyCharm 有问题，而是 Python 解释器压根没看到那个文件夹。解决它不靠“猜路径”，而要明确告诉 Python：“这个目录，算我的”。
为什么直接 import 会报错
Python 运行时只认三类路径：sys.path 里的目录、当前脚本所在目录、标准库路径。你拖进来的文件夹如果没出现在这三处，import utils 就必然失败——哪怕它在项目窗口里看着离 main.py 只隔一层。
常见错误现象：
- PyCharm 编辑器里有代码补全、能跳转，但运行时报
ModuleNotFoundError: No module named 'utils' - 手动加
sys.path.append(...)后能跑，但换台电脑或用命令行运行就崩 - 在 Jupyter 里能 import，PyCharm 里却不行（因为 Jupyter 自动把当前 notebook 目录加进了
sys.path）
标记为 Sources Root 是最快落地的方案
这是 PyCharm 提供的“路径感知”机制，不改代码、不碰 sys.path，只改 IDE 的元信息，对运行时无副作用。
操作步骤：
立即学习“Python免费学习笔记（深入）”；
- 在 Project 工具窗口中，右键点击目标文件夹（比如
src或lib） - 选 Mark Directory as → Sources Root
- 该文件夹图标变成蓝色，且右下角出现
sources标签 - 之后所有子模块都能用绝对导入，例如从项目根目录下的
main.py写from src.utils.helper import load_config
注意：这个设置只影响 PyCharm 的解析和运行行为，生成的 .idea 配置不会污染代码本身，别人拉你仓库照样能跑——只要他们也用 PyCharm 或按标准包结构组织。
想脱离 PyCharm 也能跑？必须做成 Python 包
如果你的代码要发给别人、上服务器、或者 CI/CD 流水线里执行，就不能依赖 PyCharm 的 Sources Root。此时唯一可靠的方式是让 Python 自己认出这是个包。
华为云 Python SDK 查询工具。自动发现已安装 SDK 的服务包、Client类、API 方法、入参详情、类信息（__init__ 参数、属性、类型、描述），支持关键字搜索，快速定位目标 API 使用方法。
关键动作只有两个：
- 在目标文件夹里放一个空的
__init__.py文件（哪怕内容是空行，也得存在） - 确保入口脚本（如
main.py）在项目根目录下运行，而不是在子目录里双击执行
例如项目结构是：
myproject/
├── main.py
└── utils/
├── __init__.py
└── db.py
那么在终端里必须 cd 到 myproject/，再运行 python main.py；不能 cd 进 utils 然后 python ../main.py，否则 Python 找不到 utils 包。
别乱用 sys.path.append —— 它只适合临时调试
硬编码路径（比如 sys.path.append(r'C:\Users\me\code\mylib')）看起来立竿见影，但实际埋了三个雷：
- 路径写死，换环境就得改代码
- 不同系统路径分隔符不同（
\vs/），容易引发UnicodeDecodeError或路径拼接错误 - 多个
sys.path.append可能导致模块被重复加载，尤其用了相对导入时会报ValueError: attempted relative import beyond top-level package
真要用，至少写成动态的：
import sys from pathlib import Path sys.path.append(str(Path(__file__).parent / ".." / "external_lib"))
但这也只是权宜之计。上线前务必换成包结构或 Sources Root 方案。
真正麻烦的从来不是“怎么加一行 import”，而是路径意识没建立起来——Python 不是靠文件位置猜模块，而是靠 sys.path 和包定义找模块。谁控制了这两样，谁就控制了导入行为。
