路径分隔符、换行符、包名大小写、环境变量四类问题需统一处理：用pathlib.Path替代字符串拼接，文本文件操作加newline=""参数，requirements.txt全小写，环境变量用os.getenv+pathlib.Path.home()兼容跨平台。
路径分隔符硬编码会直接报错
Windows 用 /，一旦代码里写死 "dataconfig.json" 或 r"dataconfig.txt"，到 Linux 就变成 dataconfig.json —— 文件根本打不开，FileNotFoundError 是最常撞上的墙。
- 一律改用 os.path.join()：os.path.join("data", "config.json")
- 更推荐 pathlib.Path（Python 3.4+）：Path("data") / "config.json"，自动处理分隔符且支持链式操作
- 特别注意配置文件读取、日志路径、临时目录拼接这些高频出事点
- __file__ 的路径也要过一遍 Path(__file__).parent，别直接字符串切片
换行符和文本模式打开文件不兼容
Windows 默认用
换行，Linux 是
。如果用 open("log.txt", "w") 写日志，再用 shell 工具（如 grep、sed）处理，可能匹配失败或显示异常；更隐蔽的是 CSV 或 JSON 文件在 Linux 下被当成二进制乱码。
- 文本文件统一加 newline="" 参数：open("data.csv", "r", newline="")
- 写文件时也带上：open("out.txt", "w", newline="")，让 csv.writer 和 json.dump 正确处理换行
- 避免用 "rb"/"wb" 处理纯文本——除非你真在处理二进制协议
- Git 用户顺手配下 core.autocrlf=input（Linux/macOS），防止提交带
的文件
依赖包名大小写和安装方式差异
Windows 对包名大小写不敏感（pip install PyYAML 和 pyyaml 都行），Linux 的 pip 严格区分，且部分包在不同平台编译逻辑不同（比如含 C 扩展的 psycopg2、numpy）。
- 全部用小写写 requirements.txt：pyyaml==6.0.1，别混用 PyYAML
- 生成时用 pip freeze --all > requirements.txt（Windows 上也跑这句），避免漏掉底层依赖
- Linux 上优先装 psycopg2-binary 而非源码版，省去编译 PostgreSQL dev headers 的麻烦
- venv 环境本身不能跨平台复制，必须在目标系统重装：python -m venv venv && source venv/bin/activate && pip install -r requirements.txt环境变量和启动脚本行为不一致
Windows 的 .bat 和 Linux 的 .sh 不互通；%USERPROFILE% 在 Linux 是空的，$HOME 在 Windows 命令行里压根不存在；还有 PATH 分隔符（; vs :）导致找不到可执行文件。
- 别在代码里拼 os.environ["USERPROFILE"] + "\AppData\Local"，改用 pathlib.Path.home() / "AppData" / "Local"（Windows）或 pathlib.Path.home() / ".config"（Linux）
- 启动逻辑收进 Python 主入口（如 main.py），用 if __name__ == "__main__": 控制，别依赖 shell 脚本传参逻辑
- 环境变量统一用 os.getenv("CONFIG_DIR", str(Path.home() / ".myapp")) 提供 fallback
- 如果必须用脚本，Windows 用 start.bat（调用 python main.py），Linux 用 start.sh（#!/bin/sh + python3 main.py），别试图写跨平台 shell
换行，Linux 是
。如果用 open("log.txt", "w") 写日志，再用 shell 工具（如 grep、sed）处理，可能匹配失败或显示异常；更隐蔽的是 CSV 或 JSON 文件在 Linux 下被当成二进制乱码。
- 文本文件统一加 newline="" 参数：open("data.csv", "r", newline="")
- 写文件时也带上：open("out.txt", "w", newline="")，让 csv.writer 和 json.dump 正确处理换行
- 避免用 "rb"/"wb" 处理纯文本——除非你真在处理二进制协议
- Git 用户顺手配下 core.autocrlf=input（Linux/macOS），防止提交带
的文件
依赖包名大小写和安装方式差异
Windows 对包名大小写不敏感（pip install PyYAML 和 pyyaml 都行），Linux 的 pip 严格区分，且部分包在不同平台编译逻辑不同（比如含 C 扩展的 psycopg2、numpy）。
- 全部用小写写 requirements.txt：pyyaml==6.0.1，别混用 PyYAML
- 生成时用 pip freeze --all > requirements.txt（Windows 上也跑这句），避免漏掉底层依赖
- Linux 上优先装 psycopg2-binary 而非源码版，省去编译 PostgreSQL dev headers 的麻烦
- venv 环境本身不能跨平台复制，必须在目标系统重装：python -m venv venv && source venv/bin/activate && pip install -r requirements.txt环境变量和启动脚本行为不一致
Windows 的 .bat 和 Linux 的 .sh 不互通；%USERPROFILE% 在 Linux 是空的，$HOME 在 Windows 命令行里压根不存在；还有 PATH 分隔符（; vs :）导致找不到可执行文件。
- 别在代码里拼 os.environ["USERPROFILE"] + "\AppData\Local"，改用 pathlib.Path.home() / "AppData" / "Local"（Windows）或 pathlib.Path.home() / ".config"（Linux）
- 启动逻辑收进 Python 主入口（如 main.py），用 if __name__ == "__main__": 控制，别依赖 shell 脚本传参逻辑
- 环境变量统一用 os.getenv("CONFIG_DIR", str(Path.home() / ".myapp")) 提供 fallback
- 如果必须用脚本，Windows 用 start.bat（调用 python main.py），Linux 用 start.sh（#!/bin/sh + python3 main.py），别试图写跨平台 shell
.bat 和 Linux 的 .sh 不互通；%USERPROFILE% 在 Linux 是空的，$HOME 在 Windows 命令行里压根不存在；还有 PATH 分隔符（; vs :）导致找不到可执行文件。
- 别在代码里拼 os.environ["USERPROFILE"] + "\AppData\Local"，改用 pathlib.Path.home() / "AppData" / "Local"（Windows）或 pathlib.Path.home() / ".config"（Linux）
- 启动逻辑收进 Python 主入口（如 main.py），用 if __name__ == "__main__": 控制，别依赖 shell 脚本传参逻辑
- 环境变量统一用 os.getenv("CONFIG_DIR", str(Path.home() / ".myapp")) 提供 fallback
- 如果必须用脚本，Windows 用 start.bat（调用 python main.py），Linux 用 start.sh（#!/bin/sh + python3 main.py），别试图写跨平台 shell
路径、换行、包名、环境变量——这四块不动手改，光复制文件过去跑不起来是常态。尤其是 pathlib 替换字符串拼接和 newline="" 这两个动作，看着小，卡住人最多。
