[故障复盘] PyCharm 远程开发：中文文件名“隐身”与无法创建文件的排查

$故障复盘$ PyCharm 远程开发：中文文件名"隐身"与无法创建文件的排查

1. 问题背景 (The Symptoms)

在使用 PyCharm 进行 Remote Development (远程开发) 连接 Linux 服务器时，遇到了诡异的中文文件名处理问题。

环境：
Client: Windows (PyCharm Gateway)
Host: Linux Server (CentOS/Ubuntu), Root 用户
IDE: PyCharm Professional (Remote Mode)
现象一：Git 显示乱码

执行 git ls-tree 时，中文文件名显示为八进制编码，如 "knowledge-base/data/\345\207\217..."。
现象二：文件在 IDE 中"隐身"

虽然在服务器文件系统（通过 ls）和 VS Code 中能正常看到类似 测试QA.xlsx 这种中文文件，但在 PyCharm 的 Project 视图中，该文件完全消失。
现象三：无法创建中文文件 (关键)

尝试在 PyCharm 中新建名为 测试.txt 的文件时，直接报错：Invalid file name: '测试.txt'。

2. 排查过程 (Troubleshooting)

2.1 Git 配置排除

首先解决了 Git 输出乱码的问题，确认不是单纯的 Git 显示问题：

bash 复制代码

git config --global core.quotePath false

但 PyCharm 依然无法索引该文件，说明是 IDE 层面的问题。

2.2 锁定 JVM 环境问题

由于 PyCharm 后端是运行在 JVM 上的，怀疑是 Java 的 NIO (New IO) 无法处理 UTF-8 路径。

尝试在 Host 端 的 VM Options 中添加强制编码参数：

-Dfile.encoding=UTF-8
-Dsun.jnu.encoding=UTF-8

检查进程参数确认注入成功：

bash 复制代码

ps -ef | grep java | grep encoding
# 输出显示参数已存在，但问题依旧。

2.3 深入系统底层：环境变量丢失

最关键的一步排查。虽然 Linux 系统本身的 locale -a 显示支持 zh_CN.utf8，且终端中 echo $LANG 也是正常的，但我们需要确认 PyCharm 进程本身 到底处于什么环境。

通过读取进程的 environ 文件（PID 为 PyCharm 后端进程号）：

bash 复制代码

xargs -0 -L1 < /proc/20096/environ | grep -E "LANG|LC_"

结果：无任何输出。

结论：PyCharm 的后端进程处于"裸奔"状态，丢失了 LANG 和 LC_ALL 环境变量。此时 Linux 默认回退到 POSIX 或 C 环境，导致 JVM 认为系统不支持非 ASCII 字符，从而抛出 InvalidPathException 并拒绝加载/创建中文文件。

3. 根因分析 (Root Cause)

JetBrains Remote Development 的后端服务在通过 SSH 启动或作为后台服务运行时，并没有加载用户的 Shell 配置文件 （如 .bashrc 或 .profile），导致进程启动时的 Locale 环境缺失。

当 JVM 检测到 LANG=C 时，即便手动指定了 -Dsun.jnu.encoding=UTF-8，底层的文件系统调用依然会受到操作系统的限制。

4. 解决方案 (The Fix)

最稳妥的方案是修改 PyCharm 后端的启动入口脚本，强行注入环境变量。

步骤 1：找到安装目录

在服务器上找到 Remote Dev 的安装路径（通常在 ~/.cache 下）：

bash 复制代码

# 示例路径，需根据实际情况调整
cd ~/.cache/JetBrains/RemoteDev/dist/xxxxxxxx_pycharm/bin/

步骤 2：修改启动脚本 `pycharm.sh`

编辑 pycharm.sh：

bash 复制代码

vim pycharm.sh

在文件的 第 2 行 （即 #!/bin/sh 下方），插入以下内容：

bash 复制代码

# === Fix Chinese Filename Encoding ===
export LANG=zh_CN.utf8
export LC_ALL=zh_CN.utf8
# =====================================

注意：zh_CN.utf8 需根据 locale -a 的实际输出填写。

步骤 3：重启后端服务

这一步必须彻底，否则旧的进程会一直占坑。

bash 复制代码

# 杀掉所有 JetBrains 相关进程
pkill -f jetbrains
# 或者
kill -9 <PID>

也可以直接在PyCharm的启动界面上直接点击停止运行。

步骤 4：验证

重新通过客户端连接。

新建文件 ：测试.txt 创建成功。现在可以正常创建带有中文的文件而不会报错了。
显示文件 ：右键文件夹 -> Reload from Disk，原本消失的 Excel 文件恢复显示。

5. 避坑指南 (Key Takeaways)

不要只看客户端配置 ：Remote Development 模式下，本地可以通过 Help -> Edit Custom VM Options 修改配置，但这只影响 Client（显示端）。真正干活的是 Host（服务端），必须去服务器上改。
不要相信 echo $LANG ：你在终端看到的变量，不代表后台进程也能吃到。使用 /proc/<PID>/environ 才是查证进程环境变量的最佳方法。
JVM 参数不是万能的 ：在 Linux 下，操作系统级别的 Locale 设置优先级极高，它决定了底层系统调用如何处理文件名。环境变量 (LANG) + JVM 参数 (sun.jnu.encoding)一起考虑到才是正解。

[故障复盘] PyCharm 远程开发：中文文件名“隐身”与无法创建文件的排查