Windows下import报错“ModuleNotFoundError”常因MAX_PATH限制（260字符）导致长路径被截断，需启用系统长路径支持、缩短路径或用GetShortPathNameW转换；IDE正常而命令行失败是因环境路径差异。
Windows下import报错“ModuleNotFoundError: No module named 'xxx'”但路径明明存在
这通常不是模块真丢了，而是Python在解析sys.path中长路径时被Windows的MAX_PATH限制（260字符）截断或跳过。尤其当项目嵌套深、虚拟环境路径带长用户名、或用pip install -e .开发安装时极易触发。
- 先验证是否是路径长度问题：用
os.path.abspath(__file__)打印出报错模块的实际绝对路径，数一下字符数——超240就高度可疑 - 临时绕过：在Python启动前设置环境变量
SET PYTHONPATH=C:\short\path\to\your\package，比改sys.path更早生效 - 根本解法：启用Windows长路径支持（需管理员权限运行PowerShell）：
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 - 注意：该注册表项仅对Windows 10 1607+和Windows Server 2016+生效，旧系统必须靠缩短路径或映射驱动器（如
subst X: C:\very\long\real\path）
使用pathlib.Path拼接路径时import仍失败
pathlib本身不解决加载问题，它只负责生成路径字符串；真正卡住的是importlib.util.spec_from_file_location()或imp.load_source()这类底层加载逻辑——它们最终调用Windows API打开文件，此时长路径限制才起作用。
- 不要依赖
pathlib.Path.resolve()后直接传给importlib.util.spec_from_file_location()，它不会自动绕过MAX_PATH - 若必须动态导入，优先用
importlib.util.spec_from_file_location(name, str(short_path))，其中short_path需提前用GetShortPathNameW（通过ctypes调用）转换，例如：from ctypes import wintypes, windll; windll.kernel32.GetShortPathNameW(long_path, short_buffer, buffer_len) - 更稳妥的做法是：把待加载模块软链接到短路径目录（Windows 10 1703+支持
mklink /D），再让sys.path指向该链接
PyCharm或VS Code调试时路径正常，命令行运行却报错
IDE通常会自动注入PYTHONPATH或修改sys.path为相对短路径，而命令行直接执行python main.py走的是原始sys.path，暴露真实长度问题。
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 检查IDE的“Run Configuration”里是否勾选了“Add content roots to PYTHONPATH”或类似选项——这相当于悄悄帮你做了路径映射
- 统一环境：在命令行中也用
-m方式运行，例如python -m mypackage.main，此时Python按包结构查找，不依赖sys.path中的长绝对路径 - 避免在
__init__.py里写sys.path.append(os.path.join(os.path.dirname(__file__), '..', 'lib'))这种硬拼路径的代码，改用importlib.resources.files('mypackage').joinpath('../lib')（Python 3.9+）或importlib_resources回填
打包成exe后长路径模块找不到
PyInstaller、cx_Freeze等工具在打包时会把模块路径固化进exe，如果构建机开启了长路径支持而目标机没开，运行时依然会失败。
立即学习“Python免费学习笔记（深入）”；
- PyInstaller用户：加
--add-data显式包含模块，并在代码中用sys._MEIPASS拼接，而不是依赖原始路径；同时确保构建和目标系统长路径策略一致 - cx_Freeze用户：在
build_exe_options中设include_files=[('src/mymodule', 'mymodule')]，避免用通配符扫描长路径目录 - 关键提醒：无论哪种打包工具，都别在
hook-文件里用os.walk()遍历深层目录——它会在构建阶段就触碰长路径，导致打包失败而非运行失败
pathlib能自动适配系统限制。路径长度问题从来不是Python层能单方面解决的，得从Windows系统策略、工具链行为、代码加载模式三处同时控制。 
