PyCharm + 远程调试路径映射总结（以 diffusers 为例）

🎯 背景说明

在远程服务器上执行以下命令：

bash 复制代码

git clone https://github.com/huggingface/diffusers.git
pip install -e .

在 PyCharm 本地 调试远程代码时，会同时出现 3 个 diffusers 目录：

路径	位置	说明
🟢 `/Users/tht/CodeSpace/SSH/GXN_haitong/YICHU1029/diffusers`	本地同步目录	你在 PyCharm 打开的工程目录，与远程目录实时同步
🟡`/Users/tht/Library/Caches/JetBrains/PyCharm2025.2/remote_sources/279053531/809553791/diffusers`	PyCharm 缓存目录（只读）	PyCharm 自动下载的远程镜像，用于符号定位；修改不会生效
🔵 `/home/u2024030000/jupyterlab/code/yichu1029/diffusers`	远程服务器运行目录	远程环境中实际执行的代码；`pip install -e .` 指向此目录

✅ 正确做法：配置 Path Mappings

为避免 Debug 时跳入缓存目录（🟡），

必须在 PyCharm 中建立本地同步目录（🟢）与远程运行目录（🔵）的一一映射。

打开菜单：

Run → Edit Configurations → Path Mappings
运行 → 编辑配置 → 路径映射

添加以下两条映射关系：

本地路径 (Local Path)	远程路径 (Remote Path)	说明
`/Users/tht/CodeSpace/SSH/GXN_haitong/YICHU1029/diffusers/src/diffusers`	`/home/u2024030000/jupyterlab/code/yichu1029/diffusers/src/diffusers`	🎯 核心映射：确保 Debug 时跳到本地真实源码（`__init__.py` 所在位置）
`/Users/tht/CodeSpace/SSH/GXN_haitong/YICHU1029/diffusers`	`/home/u2024030000/jupyterlab/code/yichu1029/diffusers`	🧩 辅助映射：帮助 PyCharm 识别项目结构、索引文件

🧠 原理说明

pip install -e . 在远程 Python 环境中注册路径：
复制代码
```
/home/u2024030000/jupyterlab/code/yichu1029/diffusers/src/diffusers
```
当执行 import diffusers 时，Python 实际加载的就是该路径；
若 PyCharm 未配置此映射，就会退回缓存目录（🟡）；
通过配置 src/diffusers → src/diffusers，PyCharm 能正确对应到
/Users/tht/CodeSpace/SSH/GXN_haitong/YICHU1029/diffusers/src/diffusers，

从而在本地直接调试同步的源码 ✅。

🔍 验证步骤

在远程服务器上执行：

bash 复制代码

python -c "import diffusers, os; print(diffusers.__file__)"

输出应为：

复制代码

/home/u2024030000/jupyterlab/code/yichu1029/diffusers/src/diffusers/__init__.py

在本地对应文件中加入：
python 复制代码
```
print(">>> Using LOCAL-SYNC diffusers ✅")
```
在 PyCharm 中运行或 Debug，若看到该输出，说明路径映射成功。

💡 三个目录的作用总结

类型	完整路径	是否可修改	作用
🟢 本地同步目录	`/Users/tht/CodeSpace/SSH/GXN_haitong/YICHU1029/diffusers`	✅ 可以修改	本地开发的主目录，与远程自动同步
🟡 缓存目录	`/Users/tht/Library/Caches/JetBrains/PyCharm2025.2/remote_sources/279053531/809553791/diffusers`	🚫 不可修改	PyCharm 自动生成的只读副本
🔵 远程目录	`/home/u2024030000/jupyterlab/code/yichu1029/diffusers`	✅ 实际执行	远程 Python 环境中运行的真实代码

✅ 最简结论

必须配置的核心映射：

复制代码

/Users/tht/CodeSpace/SSH/GXN_haitong/YICHU1029/diffusers/src/diffusers
    ↔
/home/u2024030000/jupyterlab/code/yichu1029/diffusers/src/diffusers

推荐的辅助映射：

复制代码

/Users/tht/CodeSpace/SSH/GXN_haitong/YICHU1029/diffusers
    ↔
/home/u2024030000/jupyterlab/code/yichu1029/diffusers

绝不要编辑：

复制代码

/Users/tht/Library/Caches/JetBrains/PyCharm2025.2/remote_sources/279053531/809553791/diffusers

🧩 路径关系总览

text 复制代码

本地同步目录（🟢）
│
└── /Users/tht/CodeSpace/SSH/GXN_haitong/YICHU1029/diffusers/src/diffusers
        ↑
        │  Path Mapping
        ↓
远程运行目录（🔵）
└── /home/u2024030000/jupyterlab/code/yichu1029/diffusers/src/diffusers

📘 总结：

PyCharm 在远程调试时默认进入只读缓存；

通过配置映射
/Users/.../diffusers/src/diffusers ↔ /home/.../diffusers/src/diffusers，

即可让 Debug 跳转到本地同步源码，修改实时生效。