Python基础入门之模块搜索路径sys.path用法详解

import sys

# sys.path是一个列表，包含Python搜索模块的所有目录
print("Python模块搜索路径：")
for i, path in enumerate(sys.path):
    print(f"  [{i}] {path}")

# 典型的输出（Windows）：
#   [0]                          # 空字符串 = 当前目录
#   [1] D:\my_project           # 脚本所在的目录
#   [2] C:\Python311\python311.zip
#   [3] C:\Python311\DLLs
#   [4] C:\Python311\Lib        # 标准库
#   [5] C:\Python311
#   [6] C:\Python311\Lib\site-packages  # 第三方库

import sys
import os

# 查看sys.path
for path in sys.path:
    print(f"  {path} {'(存在)' if os.path.exists(path) else '(不存在)'}")

# 检查某个模块的位置
import math
print(f"math模块的位置: {math.__file__}")
# 例如: C:\Python311\Lib\lib-dynload\math.cp311-win_amd64.pyd

import json
print(f"json模块的位置: {json.__file__}")
# 例如: C:\Python311\Lib\json\__init__.py

# 检查自定义模块
# import my_module
# print(f"my_module的位置: {my_module.__file__}")

import sys

# sys.path是一个普通列表，可以直接操作

# 方式一：append——添加到最后（优先级最低）
sys.path.append("/path/to/my/modules")
print(f"添加后: {sys.path[-1]}")

# 方式二：insert——添加到指定位置（优先级高）
# 插入到最前面——优先级最高
sys.path.insert(0, "/path/to/custom/lib")
print(f"插入到最前面: {sys.path[0]}")

# 方式三：使用环境变量PYTHONPATH（不用改代码）
# Windows: set PYTHONPATH=D:\my_libs;%PYTHONPATH%
# Linux/Mac: export PYTHONPATH=/home/user/my_libs:$PYTHONPATH

# ⚠️ 注意：
# 1. sys.path的修改只在当前进程有效——程序退出后消失
# 2. 添加到sys.path的路径必须存在且可读
# 3. 路径中的目录如果不存在，不会报错，只是找不到模块时会困惑

# 安全添加路径
def safe_add_path(path):
    """安全地添加模块搜索路径"""
    path = os.path.abspath(path)
    if os.path.exists(path) and path not in sys.path:
        sys.path.insert(0, path)
        print(f"✓ 添加路径: {path}")
    else:
        print(f"⚠ 跳过: {path}")

# ⌨️ 常见场景：项目结构如下
# my_project/
# ├── main.py
# ├── src/
# │   ├── __init__.py
# │   ├── core.py
# │   └── utils.py
# └── tests/
#     └── test_core.py

# 问题：tests/test_core.py 怎么导入 src/core.py？

# 方法一：在sys.path中添加项目根目录
import sys
import os

# 获取项目根目录（test_core.py的父目录的父目录）
project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
if project_root not in sys.path:
    sys.path.insert(0, project_root)

from src.core import some_function

# 方法二：使用相对导入（需要包结构）
# from ..src.core import some_function

# 方法三：更好的方式——以包的方式安装项目
# pip install -e .  (开发模式安装)
# 这样不需要修改sys.path

# 当遇到 "ModuleNotFoundError: No module named 'xxx'" 时，
# 按以下步骤排查：

# 步骤一：确认模块名是否正确
# 文件名是 my_module.py → import my_module（不是my_module.py）

# 步骤二：确认模块在当前目录或sys.path中
import sys
# 检查模块文件是否存在
import os
module_name = "my_module"
for path in sys.path:
    module_path = os.path.join(path, f"{module_name}.py")
    if os.path.exists(module_path):
        print(f"找到模块: {module_path}")
        break
else:
    print(f"在sys.path的所有路径中都找不到 {module_name}.py")

# 步骤三：检查是否有命名冲突
# 如果你有一个 random.py，它会遮蔽标准库的random！
# print(random.__file__)  # 看看实际导入了哪个文件

# 步骤四：检查文件权限
# 确保.py文件有读取权限

# 步骤五：对于包，检查__init__.py
# 如果你的模块是 mypackage/mymodule.py
# 确保mypackage目录下有__init__.py（即使为空）

import sys
import site

# 查看site-packages路径
print("site-packages目录：")
for path in site.getsitepackages():
    print(f"  {path}")

# 查看用户级的site-packages
print(f"\n用户目录: {site.getusersitepackages()}")

# pip安装的包都放在这里
# 如果pip install后还是找不到模块
# 可能是安装了多个Python版本，pip对应的是另一个Python

# 检查当前Python和pip的对应关系
# $ python --version
# $ pip --version        # 确保pip对应这个Python版本
# $ pip show 包名        # 查看安装位置