[故障复盘] 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 显示问题：

gitconfig --global core.quotePathfalse

但 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

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

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

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

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

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

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下）：

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

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

编辑pycharm.sh：

vimpycharm.sh

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

# === Fix Chinese Filename Encoding ===exportLANG=zh_CN.utf8exportLC_ALL=zh_CN.utf8# =====================================

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

步骤 3：重启后端服务

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

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

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

步骤 4：验证

重新通过客户端连接。

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

---

5. 避坑指南 (Key Takeaways)

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

---