Windows 路径与换行符:六个坑的实测复现

Git Bash 与 Python 之间传路径踩过的六类坑:路径前缀被吃掉、冒号变 NTFS 数据流、尾部空格被吞、换行符被改写,附复现命令与实测输出。

目录
  1. 一、坑 1:/c/Users 进了 Python 就变样
  2. 二、坑 2:文件夹名里的冒号 = NTFS 备用数据流
  3. 三、坑 3:其他非法字符是硬失败,冒号是特例
  4. 四、坑 4:尾部空格和点会被静默吞掉
  5. 五、坑 5:write_text 会悄悄改写换行符
  6. 六、坑 6:长路径反而没炸,但别指望它
  7. 七、组合故障:为什么会"成功但全错"
  8. 八、一张检查清单
  9. 下一步

Windows 上做命令行开发,路径和换行符是最容易连环出事的两件事。它们单独都不致命,但组合起来会产生"命令成功、结果全错"的静默故障。下面六个坑我都在这台机器上重新跑了一遍,输出是实测的。

环境:Windows + Git Bash(git version 2.56.0.windows.4.niugit)+ Python 3.14.8 + Node v22.19.0。

一、坑 1:/c/Users 进了 Python 就变样

在 Git Bash 里 /c/Users/admin 是最自然的写法。但把它传给 Windows 原生程序时,MSYS 会做路径转换,行为还不一致。

实测:

bash
python -c "import sys; print('argv1=', repr(sys.argv[1]))" /c/Users/admin
# argv1= 'C:\\Users\\admin'      ← 被 MSYS 转成了原生路径

看起来"帮了大忙"。但把它放进 Python 字符串里才是灾难:

bash
python -c "from pathlib import Path; print(Path('/c/Users/admin').exists())"
# False
python -c "from pathlib import Path; print(Path(r'C:\\Users\\admin').exists())"
# True

原因:作为命令行参数传进去的路径会被转换;但写在代码字面量里的 '/c/Users/admin' 就是一个普通的绝对路径字符串,Windows 上没有 /c/ 这个盘。

我当时以为:Git Bash 里所有 /c/... 都会被自动转换,写哪都一样。 实际是:只有作为进程参数跨边界时才会转;写进脚本里的字符串不会。

正确做法:脚本里一律写原生路径 C:\\Users\\admin(Python 里用 raw string),只在命令行上使用 /c/...。Git Bash 自带 cygpath 可以在两边互转,写脚本时用它最稳:

bash
cygpath -w /c/Users/admin      # C:\Users\admin
cygpath -u 'C:\Users\admin'   # /c/Users/admin

二、坑 2:文件夹名里的冒号 = NTFS 备用数据流

这个坑我原本不信,实测之后才服。在 Git Bash 里执行 touch 'a:b.txt' 会"成功",但落盘的不是你以为的文件。

bash
printf 'MAIN'   > plain.txt
printf 'STREAM' > 'plain.txt:hidden'
ls -l
text
-rwxrwxrwx 1 admin None 4 Nov 20 22:11 plain.txt
-rwxrwxrwx 1 admin None 6 Nov 20 22:11 plain.txthidden

ls 把冒号显示掉了,看起来像两个正常文件。但读一下就露馅:

bash
wc -c < plain.txt        # 4   ← 只有 MAIN
cat 'plain.txt:hidden'   # STREAM

Python 里更明显:

python
from pathlib import Path
p = Path("plain.txt")
print(p.stat().st_size)    # 4
print(p.read_text())       # 'MAIN'
print(Path("plain.txt:hidden").read_text())  # 'STREAM'

plain.txt:hidden 不是独立文件,是 plain.txt 的一个备用数据流(ADS)。它不占目录条目、不出现在常规遍历里、复制/打包时经常丢失。

危险场景:任何在文件名里带时间戳冒号的命名习惯,例如 backup-2026-11-20:22:11.txt。你以为在备份,实际写进了主文件的隐藏流里,cp 一下就没了。

正确做法:文件名里永远不用冒号,时间戳统一用 -。

三、坑 3:其他非法字符是硬失败,冒号是特例

我以为所有 Windows 非法字符行为一致。实测不一致:

想创建的文件名退出码实际结果
a:b.txt0静默变成 ADS,主文件不变
a?b.txt1创建失败
a*b.txt1创建失败
a<b.txt1创建失败
a|b.txt1创建失败

只有冒号是"成功但语义不同",其余都是明确的非 0。所以只有冒号需要专门警惕。

四、坑 4:尾部空格和点会被静默吞掉

这一条比冒号更隐蔽,因为它连"看起来不一样"都没有。实测:

bash
: > 'trail.txt   '     # 尾部三个空格
: > 'dotend.txt.'      # 尾部一个点
echo "exit=$?"         # exit=0
ls -1 | grep -E 'trail|dotend' | cat -A
text
dotend.txt$
trail.txt$

cat -A 把每行尾显示为 $。可以看到:空格和点都已经不见了,而退出码是 0。

Win32 的路径规范化会裁掉尾部的空格与点。后果是:你按 'trail.txt ' 写的检查(比如 [ -f 'trail.txt ' ])在某些路径下可能失败,而文件其实在那儿——名字少了三个字符。

正确做法:任何从外部输入(CSV 列名、用户输入、文件名解析)拿到的路径,先做一次 trim。

五、坑 5:write_text 会悄悄改写换行符

这是最容易造成"整个文件在 diff 里全红"的原因。

先看探测方法——必须读原始字节,不能靠编辑器显示:

python
from pathlib import Path
b = Path("target.txt").read_bytes()
crlf = b.count(b"\r\n")
bare_lf = b.count(b"\n") - crlf
print("CRLF=%d 裸LF=%d" % (crlf, bare_lf))

然后是对比实验。Python 3 的 Path.write_text 默认会把 \n 转成平台换行符:

python
from pathlib import Path
s = "x" + chr(10) + "y" + chr(10)
Path("w_default.txt").write_text(s, encoding="utf-8")
Path("w_nonl.txt").write_text(s, encoding="utf-8", newline="")

实测字节:

text
w_default.txt  {'bytes': 6, 'CRLF': 2, 'bareLF': 0}  b'x\r\ny\r\n'
w_nonl.txt     {'bytes': 4, 'CRLF': 0, 'bareLF': 2}  b'x\ny\n'

内容一模一样的两个字符串,落盘字节不同。如果原文件是 LF(这在 Windows 上很常见——我实测过三个 DSH 配置文件全是 LF),你用默认参数改一个字,整个文件就会变成"每行都改了"。

顺带验证:text 模式读进来再写回,CRLF 会被保留(实测 rewritten.txt 仍是 CRLF 3 处),因为 text 模式做了 universal newline 转换。所以真正危险的是跨工具的那一步——用 A 工具读、B 工具写。

正确做法:

python
# 改动前先探测,写回时保持原样
raw = p.read_bytes()
crlf = raw.count(b"\r\n"); lf = raw.count(b"\n") - crlf
nl = "" if crlf == 0 else None      # LF→保持LF;CRLF→交给平台默认
p.write_text(new_text, encoding="utf-8", newline=nl)

六、坑 6:长路径反而没炸,但别指望它

我原以为 260 字符上限会拦住深层目录。实测逐级建 12 层,每级 26 字符:

text
第 1级 累计路径  29 字符  OK
...
第12级 累计路径 337 字符  OK
绝对路径长度: 364
绝对路径写入 OK

337 字符照样建成功,说明这台机器已启用长路径支持(Win10 1607+ 的策略)。

这不是好消息,而是更危险的消息:同一份脚本在你机器上能跑,在没开长路径的机器上会失败,而错误信息通常只说"文件名太长",不提去改策略。所以不要依赖现在能跑通这件事。

七、组合故障:为什么会"成功但全错"

这几个坑单独看都能忍,组合起来就是事故:

text
用 /c/... 写路径  → 脚本里 Path 检查失败 → 走了 else 分支 → 生成空文件
文件名带冒号      → 写进 ADS → 后续 cp/pack 丢失 → 备份其实不存在
尾部空格被吞      → 按原名检查失败 → 误判"文件没生成" → 重复生成
write_text 默认   → 换行符被改写 → diff 全红 → review 时看不清真实改动

四件事的退出码可能全是 0。

八、一张检查清单

检查点命令/写法
脚本内路径写 C:\\... 原生路径,或用 cygpath -w 转换
文件名非法字符不用 : ? * < > |;时间戳用 -
尾部空格/点输入路径先 trim,再拼文件名
换行符改动前 read_bytes() 数 \r\n,写回传 newline=""
长路径不依赖能跑通,压平目录层级
验证改完 git diff --stat,行数异常立刻查换行符

下一步

把这六条做成一个 pre-commit 检查脚本,比记在脑子里可靠。最小版本三行就够:

bash
git diff --stat | tail -1                                    # 行数异常就人工看
python -c "import sys,pathlib;b=pathlib.Path(sys.argv[1]).read_bytes();print('CRLF',b.count(b'\r\n'))" somefile.md
ls -1 | grep -nE ' +$|:$' || echo "无尾部空格/冒号文件名"

最后留一句值得单独记的教训:在 Windows 上,"命令成功"和"事情做对了"是两个独立命题。