应使用 pathlib.Path 替代字符串拼接和 os.path.join，因其自动适配分隔符、支持运算符拼接、可 resolve() 规范化路径、具备类型安全与路径校验能力，是 Python 3.4+ 跨平台路径处理唯一靠谱做法。
直接用 os.path.join() 或 pathlib.Path 替代字符串拼接，能解决 90% 的路径报错。硬编码 "data\config.json" 或 "data/config.json" 在跨平台时必然失败——这不是“可能出问题”，而是“一定出问题”。
路径分隔符写死会导致 FileNotFoundError
Windows 用反斜杠 \，Linux/macOS 用正斜杠 /，但 Python 不允许你在字符串里随意混用或依赖系统自动转换。
- 错误写法：
"logs" + os.sep + "app.log"—— 看似用了os.sep，但字符串拼接仍易出错（比如开头多一个/导致绝对路径） - 正确写法：
Path("logs") / "app.log"或os.path.join("logs", "app.log") - 特别注意：
__file__的父目录别用os.path.dirname(__file__)后再拼接，改用Path(__file__).parent - 日志、临时文件、配置加载路径，全是高发区；一旦写成
r"conf\settings.yaml"，Linux 下直接FileNotFoundError
文本文件换行符不一致引发解析失败
Windows 写入的 \r\n 在 Linux 下被当二进制处理，csv.reader 或 json.load 可能跳行、报 JSONDecodeError，甚至 shell 工具（grep、awk）匹配失效。
- 读 CSV/JSON/TXT 时必须加
newline=""参数：open("data.csv", "r", newline="") - 写文件同样要加：
open("out.json", "w", newline="")，否则json.dump()可能插入多余空行 - 别用
"rb"/"wb"处理纯文本——除非你明确在对接二进制协议 - Git 用户建议全局设
git config --global core.autocrlf input，避免提交带\r\n的文件
配置目录和环境变量跨平台不可硬编码
os.environ["USERPROFILE"] + "\AppData\Roaming" 在 Linux 下是空值；~/Library/Preferences 在 Windows 上根本不存在。这类路径写死，程序启动就静默失败或写到错误位置。
立即学习“Python免费学习笔记（深入）”；
- 用户配置目录统一用
platformdirs.user_config_dir("myapp")（推荐）或appdirs.user_config_dir("myapp") - 环境变量取值别假设键名存在：
os.getenv("CONFIG_DIR", str(Path.home() / ".config" / "myapp")) - 权限操作（如
os.chmod()）在 Windows 上基本无效——别指望它限制文件读写，ACL 才是正解 - 启动脚本别混用
.bat和.sh；入口逻辑收进 Python，用sys.platform做最小分支判断
requirements.txt 包名大小写与安装行为差异
Windows 的 pip 对包名大小写不敏感（pip install PyYAML 和 pyyaml 都行），Linux 严格区分；更麻烦的是含 C 扩展的包（如 psycopg2、numpy）在不同平台编译逻辑不同。
-
requirements.txt全部小写：pyyaml==6.0.1，别出现PyYAML或Pyyaml - 生成时统一用
pip freeze --all > requirements.txt，避免漏掉底层依赖 - Linux 上优先装
psycopg2-binary，而非源码版——省去装 PostgreSQL dev headers 的麻烦 -
venv目录不能复制迁移，目标机必须重装：python -m venv venv && source venv/bin/activate && pip install -r requirements.txt
最常被忽略的不是路径怎么写，而是「配置文件路径是否真可写」——platformdirs.user_config_dir() 返回的目录，Linux 下可能因 umask 默认不可写，macOS 沙盒环境下甚至根本拒绝创建。动手前先 os.makedirs(..., exist_ok=True) 并捕获 PermissionError，比事后 debug 强十倍。
