Codex 跨系统小工具避坑指南：从能跑到结果对的实战修复

1. 跨系统小工具为什么总在“能跑”和“结果对”之间翻车

用 Codex 这类 AI 编程助手写跨系统小工具，最让人抓狂的不是它写不出来，而是它写出来的东西在你这台机器上跑得挺欢，换一台机器、换一个系统、换一个目录，结果就悄悄变了样。程序没报错，退出码是 0，日志也没红字，但输出的文件少了几行、路径拼错了、时间戳差了八小时、编码从 UTF-8 变成了 GBK。这种“能跑但结果不对”的问题，比直接崩溃难查十倍，因为它不给你任何显式信号。

我自己用 Codex CLI 在 Windows 和 Linux 之间来回折腾小工具，踩过的坑基本都集中在几个地方：路径分隔符、换行符、文件编码、环境变量、依赖版本、以及 AI 生成代码时默认假设的运行环境。Codex 很聪明，但它默认你用的是它训练数据里最常见的那套环境，而跨系统场景恰恰是“最常见”覆盖不到的地方。所以这篇文章不是讲怎么让 Codex 帮你写代码，而是讲怎么在它写完代码之后，把那些“看起来对、跑起来也对、结果就是不对”的坑一个个堵上。

适合谁看？如果你用 Codex、Codex CLI 或者任何 AI 助手写过需要在 Windows 和 Linux/macOS 之间共享的 Python 小工具，或者你正在做跨平台的脚本、数据处理、文件批处理，这篇内容能帮你省下大量对着输出结果发呆的时间。核心关键词就几个：Codex、跨系统、Codex CLI、Python、Windows，围绕它们展开。

先说一个最典型的场景。你让 Codex 写一个“遍历目录下所有 CSV，合并成一个文件”的脚本。它给你一段用os.listdir加open(..., 'w')的代码，在 Linux 上跑得好好的。拿到 Windows 上一跑，文件是生成了，但用 Excel 打开全是乱码，而且行尾多了一堆奇怪符号。你去查代码，逻辑没问题，语法没问题，可结果就是不对。问题出在open默认编码在 Windows 上是 GBK，在 Linux 上是 UTF-8，而 Codex 生成代码时很少主动指定encoding='utf-8'。这就是“能跑但结果不对”的经典案例。

再比如路径拼接。Codex 经常直接写path + "/" + filename，在 Linux 上没问题，在 Windows 上虽然 Python 大多能兼容正斜杠，但一旦这个路径被传给某些 Windows 原生工具或者写进配置文件，反斜杠和正斜杠混用就会出问题。更隐蔽的是os.path.join和pathlib.Path的混用，Codex 有时会在同一个脚本里两种都用，导致路径对象和字符串来回转换时丢失信息。

还有一个高频坑是换行符。Python 的open在文本模式下，Windows 会把\n写成\r\n，Linux 保持\n。如果你的工具生成的文件要跨系统传输或者被另一个程序解析，换行符不一致就会导致解析失败或者多出空行。Codex 生成的代码通常不会显式设置newline=''，这就埋下了隐患。

这些问题的共同点是：它们都不是语法错误，也不是逻辑错误，而是环境假设错误。Codex 基于海量代码训练，它生成的代码反映的是“统计上最常见”的写法，而跨系统场景要求的是“显式指定、不依赖默认值”的写法。这两者之间有天然鸿沟。你要做的，就是在 Codex 生成代码之后，系统性地检查那些依赖默认行为的地方，把它们全部改成显式声明。

我后来总结了一套检查清单，每次 Codex 写完跨系统工具，我就按这个清单过一遍：文件打开有没有指定 encoding，路径拼接有没有统一用 pathlib，换行符有没有显式控制，环境变量有没有做存在性判断，依赖版本有没有锁定，命令行参数有没有处理 Windows 和 Unix 的差异。这套清单帮我省了很多返工时间，后面会逐条展开。

2. Codex 生成跨系统代码时的默认假设与真实环境差异

2.1 Codex 的训练偏好：为什么它总写出“Linux 优先”的代码

Codex 这类模型在训练时，语料里 Linux 和 macOS 的代码占比远高于 Windows。这不是猜测，从它生成代码的习惯就能看出来：它默认用/做路径分隔符，默认文件编码是 UTF-8，默认换行是\n，默认 shell 是 bash，默认有/tmp目录，默认环境变量用$VAR而不是%VAR%。这些默认在 Linux 上完全正确，在 Windows 上就未必。

举个例子，你让 Codex 写一个“读取配置文件并输出到临时目录”的脚本。它很可能写出这样的代码：

import os import tempfile config_path = os.path.expanduser("~/.myapp/config.json") tmp_path = "/tmp/myapp_output.txt" with open(config_path) as f: data = f.read() with open(tmp_path, "w") as f: f.write(data)

这段代码在 Linux 上没问题。在 Windows 上，~/.myapp/config.json里的~可能不会被正确展开，/tmp目录根本不存在，open的默认编码是 GBK，写入中文会乱码。Codex 不会主动告诉你这些，因为它生成的代码在它的“世界观”里是自洽的。

更麻烦的是，Codex 有时会混合使用不同风格的 API。比如它可能同时用os.path和pathlib，或者同时用subprocess.call和subprocess.run。在单一系统上这些混用通常没事，但跨系统时，不同 API 对路径、编码、换行的处理方式不同，混用就会导致行为不一致。

我的应对策略是：Codex 生成代码后，先做一次“环境假设审计”。把所有依赖默认行为的地方标出来，然后逐个改成显式声明。具体来说，就是搜这几个关键词：open(、os.path、subprocess、tempfile、os.environ、sys.platform。每一个出现的地方，都要问自己：这里的行为在 Windows 和 Linux 上一样吗？如果不一样，我有没有显式控制？

2.2 Windows 与 Unix 的六大核心差异点

跨系统小工具出问题，九成以上集中在六个差异点上。我把它们整理成一张表，方便你对照检查。

这张表看着简单，但每一个都是高频坑。比如大小写敏感性，你在 Windows 上写import MyModule，文件叫mymodule.py，Windows 不区分大小写，能跑。拿到 Linux 上，直接ModuleNotFoundError。Codex 生成 import 语句时，通常按它“记忆”里的模块名来写，不一定和你实际文件名大小写一致。

再比如可执行文件后缀。Codex 写subprocess.run(["ffmpeg", ...])，在 Linux 上没问题，在 Windows 上如果 ffmpeg 不在 PATH 里，或者实际文件名是ffmpeg.exe，就可能找不到。更隐蔽的是，有些工具在 Windows 上是.bat脚本，Codex 不知道，直接按无后缀调用，结果失败。

环境变量这块也容易翻车。Codex 可能写出os.environ["HOME"]，在 Linux 上没问题，在 Windows 上HOME通常不存在，应该用USERPROFILE。或者它写os.environ["PATH"]，这个在两个系统上都有，但路径分隔符不同：Windows 用;，Unix 用:。如果你要拼接 PATH，不区分系统就会出错。

2.3 一个真实翻车案例：CSV 合并工具的输出差异

我拿一个实际项目来说。需求很简单：遍历指定目录下所有 CSV 文件，合并成一个总文件，保留表头，输出到指定路径。Codex 生成的代码大概是这样：

import os import csv def merge_csv(input_dir, output_file): all_rows = [] header = None for filename in os.listdir(input_dir): if filename.endswith(".csv"): filepath = input_dir + "/" + filename with open(filepath, "r") as f: reader = csv.reader(f) rows = list(reader) if header is None: header = rows[0] all_rows.extend(rows[1:]) with open(output_file, "w") as f: writer = csv.writer(f) writer.writerow(header) writer.writerows(all_rows) merge_csv("./data", "./merged.csv")

在 Linux 上跑，输出正常。在 Windows 上跑，问题一堆：input_dir + "/" + filename虽然 Python 能识别，但如果input_dir以反斜杠结尾，就会变成data\/file.csv，某些情况下会出问题；open没指定编码，中文 CSV 读进来是乱码；open写文件没指定newline=''，csv 模块在 Windows 上会多写一个\r，导致每行末尾多一个空行。

修复后的代码：

import os import csv from pathlib import Path def merge_csv(input_dir, output_file): input_path = Path(input_dir) all_rows = [] header = None for filepath in sorted(input_path.glob("*.csv")): with open(filepath, "r", encoding="utf-8-sig", newline="") as f: reader = csv.reader(f) rows = list(reader) if not rows: continue if header is None: header = rows[0] all_rows.extend(rows[1:]) with open(output_file, "w", encoding="utf-8", newline="") as f: writer = csv.writer(f) writer.writerow(header) writer.writerows(all_rows) merge_csv("./data", "./merged.csv")

改动点：用pathlib.Path统一路径操作，用glob替代listdir加字符串判断，显式指定encoding，显式指定newline=""，用utf-8-sig读取以兼容带 BOM 的 CSV。这些改动都不复杂，但如果不做，跨系统结果就是不对。

注意：utf-8-sig在读取时会自动去掉 BOM，写入时如果不需要 BOM 就用utf-8。很多 Windows 上生成的 CSV 带 BOM，Linux 工具读的时候会把 BOM 当成内容的一部分，导致第一列列名多出几个不可见字符。

3. 用 Codex CLI 搭建跨系统工具的实操流程

3.1 环境准备：Windows 上的 Python 与 Codex CLI 安装要点

在 Windows 上折腾 Codex CLI 和 Python，第一步是把环境搞干净。Python 安装建议直接从官网下载最新稳定版，安装时勾选“Add Python to PATH”，这一步很关键，否则后面命令行里调不到 python。安装完成后，用python --version和pip --version确认。如果系统里有多个 Python 版本，建议用py -3来明确调用，避免版本混乱。

Codex CLI 的安装，按官方文档走就行。装完之后，先跑一个最简单的命令确认能正常调用。如果遇到 “unable to locate the codex cli binary or required runtime components” 这类提示，通常是 PATH 没配好，或者安装过程中缺少运行时组件。我的经验是：先把终端关掉重开，让 PATH 生效；如果还不行，检查安装目录有没有加到系统环境变量里。

Windows Terminal 比传统 cmd 好用很多，建议用它来跑 Codex CLI。它支持更好的复制粘贴、多标签、以及 UTF-8 显示。如果你在 cmd 里跑 Codex CLI 发现中文输出乱码，换成 Windows Terminal 通常就能解决。另外，Windows 的脚本如果双击闪退，不要慌，在终端里手动跑一遍，看报错信息。闪退通常是因为脚本执行完就关窗口，或者中间有未捕获异常。

还有一个容易忽略的点：Windows 上的换行符和编码。如果你用 Codex CLI 生成脚本文件，然后用记事本打开，可能看到的是乱码或者换行不对。建议用 VS Code 或者 Notepad++ 来查看和编辑，它们能正确识别 UTF-8 和 LF/CRLF。VS Code 右下角可以切换换行符和编码，这个功能在跨系统调试时非常有用。

3.2 让 Codex 生成代码时主动声明跨系统约束

Codex 不会读心术，你给它的提示越明确，它生成的代码越靠谱。我的做法是在提示里直接写清楚跨系统要求。比如不要只说“写一个合并 CSV 的脚本”，而是说“写一个 Python 脚本，在 Windows 和 Linux 上都能运行，合并目录下所有 CSV，显式指定 UTF-8 编码，使用 pathlib 处理路径，输出文件换行符用 \n”。

这样 Codex 生成代码时就会把这些约束考虑进去。实测下来，明确提示后，Codex 生成encoding='utf-8'和pathlib的概率大幅提升。你还可以在提示里要求它“不要依赖任何系统默认值”，这句话很管用，能逼它把很多隐式行为改成显式声明。

另一个技巧是让 Codex 生成代码后，再让它自己审查一遍。你可以追加一句：“检查这段代码在 Windows 和 Linux 上运行时可能产生不同结果的地方，列出来并修复。” Codex 通常能找出几个明显的问题，比如编码、路径、换行。虽然它不一定能找全，但能帮你覆盖大部分常见坑。

如果你用的是 Codex CLI，可以把这些约束写进一个模板文件，每次生成代码时引用。比如建一个cross_platform_rules.md，里面列出你的跨系统要求，然后在提示里说“遵循 cross_platform_rules.md 中的约束”。这样不用每次重复输入，效率高很多。

3.3 生成后的第一轮审查：五个必查项

Codex 生成代码后，不要直接跑。先做一轮静态审查，重点看五个地方。这五个地方覆盖了大部分跨系统问题，花几分钟检查，能省下后面几小时的调试。

第一，文件打开操作。搜open(，看每一个有没有指定encoding。如果没有，根据用途补上utf-8或utf-8-sig。如果涉及 CSV，还要看有没有newline=""。

第二，路径操作。搜os.path和字符串拼接的/或\。如果有，考虑改成pathlib.Path。pathlib在 Windows 和 Linux 上行为一致，而且支持/运算符拼接，代码更干净。

第三，外部命令调用。搜subprocess和os.system。看调用的命令在 Windows 上是否存在，是否需要加.exe后缀，参数格式是否兼容。如果命令在两个系统上名字不同，需要做条件判断。

第四，环境变量读取。搜os.environ和os.getenv。看读取的变量在目标系统上是否存在，是否需要 fallback。比如HOME在 Windows 上要用USERPROFILE替代。

第五，换行符处理。搜write和writelines。如果写入的是文本文件，考虑是否需要显式控制换行符。对于要跨系统传输的文件，统一用\n通常更安全。

这五个检查项做完，大部分“能跑但结果不对”的问题就能提前发现。我习惯把这五项做成一个 checklist，每次 Codex 生成代码后过一遍，形成肌肉记忆后很快。

4. 核心差异点的代码级修复与参数计算

4.1 路径处理：从字符串拼接到 pathlib 的彻底迁移

路径问题是跨系统工具的头号杀手。Codex 生成的代码里，路径处理通常有三种写法：字符串拼接、os.path.join、pathlib。字符串拼接最危险，os.path.join好一些但仍有坑，pathlib最安全。我的建议是统一用pathlib，彻底放弃前两种。

字符串拼接的问题在于，它依赖开发者手动处理分隔符。Codex 可能写dir + "/" + file，在 Linux 上没问题，在 Windows 上 Python 虽然能识别正斜杠，但如果这个路径被传给外部程序或者写入配置文件，就可能出问题。更糟的是，如果dir本身以分隔符结尾，就会产生双分隔符，某些工具会解析失败。

os.path.join会根据当前系统自动选择分隔符，比字符串拼接好。但它返回的是字符串，和pathlib.Path对象混用时需要转换。而且os.path.join在 Windows 上遇到绝对路径参数时会“吃掉”前面的路径，比如os.path.join("C:\\data", "/etc/passwd")会返回/etc/passwd，这个行为在跨系统时很容易让人困惑。

pathlib.Path是 Python 3.4 之后的标准做法。它用/运算符拼接，自动处理分隔符，支持glob、exists、read_text、write_text等便捷方法。跨系统场景下，pathlib的行为一致性最好。比如：

from pathlib import Path base = Path("data") filepath = base / "subdir" / "file.csv" print(filepath) # Windows: data\subdir\file.csv, Linux: data/subdir/file.csv

pathlib还提供了as_posix()方法，在需要把路径传给只接受正斜杠的外部工具时，可以转换。比如调用某些命令行工具时，用str(path.as_posix())更安全。

迁移到pathlib时，注意几个细节。Path.glob返回的是生成器，需要遍历。Path.read_text和write_text默认编码是系统默认，跨系统时仍要显式指定encoding。Path.mkdir的parents=True可以创建多级目录，exist_ok=True避免目录已存在时报错。这些在 Codex 生成的代码里经常缺失，需要手动补上。

4.2 编码与换行：显式声明如何避免结果漂移

编码和换行是“能跑但结果不对”的两大隐形推手。它们不会让程序崩溃，但会让输出结果在另一个系统上变得不可用。Codex 生成的代码通常不指定这两个参数，因为它默认系统默认值就是对的。跨系统场景下，这个假设不成立。

编码方面，Python 的open在文本模式下，如果不指定encoding，会用locale.getpreferredencoding()的返回值。在中文 Windows 上，这通常是 GBK 或 CP936；在 Linux 上，通常是 UTF-8。同一个脚本，在 Windows 上读 UTF-8 文件会乱码，在 Linux 上读 GBK 文件也会乱码。解决办法只有一个：所有文本文件操作都显式指定encoding='utf-8'。如果文件可能带 BOM，读取时用utf-8-sig。

换行方面，Python 的open在文本模式下，写入时会把\n转换成系统默认换行符。Windows 转成\r\n，Linux 保持\n。如果你生成的文件要给另一个系统上的程序读，换行符不一致就可能导致解析问题。比如一个按行解析的脚本，在 Linux 上读 Windows 生成的文件，每行末尾会多一个\r，如果没做 strip，就会出问题。

解决办法是在open时指定newline=""。这个参数在读取时不做换行符转换，在写入时也不做转换，\n就是\n。对于 CSV 文件，newline=""是必须的，否则 csv 模块在 Windows 上会多写\r。对于普通文本文件，如果你希望输出统一用\n，也建议指定newline=""，然后手动控制换行符。

# 读取时不做换行转换 with open("input.txt", "r", encoding="utf-8", newline="") as f: content = f.read() # 写入时统一用 \n with open("output.txt", "w", encoding="utf-8", newline="") as f: f.write(content.replace("\r\n", "\n"))

提示：newline=""在读取时会把\r\n原样保留，所以如果你要按行处理，记得用splitlines()而不是split("\n")，splitlines()能正确处理各种换行符。

4.3 环境变量与外部命令：跨系统调用的兼容写法

环境变量和外部命令是跨系统工具的另一大雷区。Codex 生成的代码经常直接读os.environ["HOME"]或者调用subprocess.run(["ls", ...])，这些在 Linux 上没问题，在 Windows 上就翻车。

环境变量方面，Windows 和 Unix 的变量名不同。HOME在 Unix 上存在，Windows 上通常用USERPROFILE。TMPDIR在 Unix 上用，Windows 上用TEMP或TMP。PATH两个系统都有，但分隔符不同：Windows 用;，Unix 用:。如果你要拼接 PATH，必须区分系统。

安全的做法是写一个辅助函数，按系统返回正确的变量：

import os import sys def get_home(): if sys.platform == "win32": return os.environ.get("USERPROFILE", os.path.expanduser("~")) return os.environ.get("HOME", os.path.expanduser("~")) def get_temp_dir(): if sys.platform == "win32": return os.environ.get("TEMP", os.environ.get("TMP", ".")) return os.environ.get("TMPDIR", "/tmp")

外部命令方面，Windows 上的可执行文件通常带.exe后缀，有些工具是.bat或.cmd。Codex 生成的subprocess.run(["ffmpeg", ...])在 Windows 上如果 ffmpeg 不在 PATH 里，就会FileNotFoundError。解决办法是用shutil.which先查找命令是否存在，或者用sys.platform判断后加后缀。

import shutil import subprocess import sys def find_executable(name): if sys.platform == "win32": for ext in ["", ".exe", ".bat", ".cmd"]: path = shutil.which(name + ext) if path: return path else: path = shutil.which(name) if path: return path raise FileNotFoundError(f"找不到可执行文件: {name}") exe = find_executable("ffmpeg") subprocess.run([exe, "-i", "input.mp4", "output.mp4"], check=True)

另外，subprocess在 Windows 上默认用shell=False，如果命令是.bat脚本，可能需要shell=True或者显式调用cmd /c。但shell=True有安全风险，如果命令参数来自用户输入，可能被注入。跨系统工具里，尽量用列表形式传参，避免shell=True。

5. 常见问题与排查技巧实录

5.1 问题速查表：症状、原因与修复

跨系统工具的问题往往症状相似但原因不同。我整理了一张速查表，按症状查原因，再按原因找修复方法。这张表是我自己踩坑后总结的，覆盖了大部分高频问题。

这张表建议存下来，遇到问题先对照查。大部分问题都能在表里找到对应项。如果表里没有，再往下深挖。

5.2 排查思路：从“结果不对”倒推环境差异

排查“能跑但结果不对”的问题，最有效的方法是从结果倒推。不要一上来就看代码，先看输出结果哪里不对。是内容少了？多了？乱码了？格式变了？然后根据症状定位到具体的环境差异。

比如输出文件在 Windows 上打开正常，在 Linux 上打开多出空行。这明显是换行符问题，去查open有没有newline=""。如果输出文件在 Linux 上正常，在 Windows 上中文乱码，那是编码问题，去查encoding。如果输出文件在两个系统上都正常，但内容顺序不一样，那可能是os.listdir的顺序问题，Windows 和 Linux 的目录遍历顺序不同，需要显式排序。

还有一个技巧是加日志。在关键步骤打印中间结果，比如文件路径、编码、换行符、环境变量值。然后在两个系统上分别跑，对比日志差异。差异点就是问题所在。Codex 生成的代码通常没有日志，你需要自己加。加日志不丢人，跨系统调试时日志是最可靠的工具。

如果问题实在难查，可以用二分法。把脚本拆成几段，逐段运行，看哪一段开始出现差异。或者用最小复现：把可疑代码单独抽出来，写一个几行的小脚本，在两个系统上跑，对比结果。最小复现能排除干扰因素，快速定位问题。

5.3 独家避坑技巧：我踩过的五个坑

第一个坑：os.listdir的顺序。Windows 和 Linux 返回的文件顺序不同，而且都不保证有序。如果你的工具依赖文件顺序，必须显式sorted()。我写过一个合并工具，在 Linux 上输出顺序正常，在 Windows 上顺序全乱，查了半天才发现是listdir的锅。

第二个坑：pathlib的glob大小写。在 Windows 上，glob("*.csv")会匹配.CSV，在 Linux 上不会。如果你的目录里有大写扩展名的文件，跨系统结果就不一致。解决办法是用glob("*")然后手动过滤，或者用glob("*.csv")加glob("*.CSV")合并。

第三个坑：subprocess的cwd参数。在 Windows 上，如果cwd路径包含空格，且没有正确引用，命令会失败。用pathlib的Path对象传给cwd通常没问题，但如果是字符串，要确保没有多余引号。

第四个坑：tempfile的默认目录。tempfile.gettempdir()在 Windows 上返回C:\Users\...\AppData\Local\Temp，在 Linux 上返回/tmp。如果你把临时文件路径写进输出，跨系统就不一致。如果输出需要可移植，用相对路径或者显式指定目录。

第五个坑：Codex CLI 的更新。Codex CLI 更新后，生成的代码风格可能变化。我有一次更新后，Codex 开始默认用pathlib，但有些地方又混用os.path，导致代码风格不统一。解决办法是更新后先跑几个测试用例，确认生成质量没有下降。

注意：跨系统工具开发时，尽量在两个系统上都跑一遍测试。不要只在 Windows 上跑通就以为没问题。如果条件允许，用虚拟机或者容器跑另一个系统，成本不高但能省很多事。

6. 工具选型与工作流优化

6.1 编辑器与终端：VS Code + Windows Terminal 的组合

跨系统开发，工具选对了能省一半力气。我的主力组合是 VS Code 加 Windows Terminal。VS Code 的跨平台一致性很好，在 Windows 和 Linux 上界面和快捷键基本一致。它的 Python 插件能自动识别虚拟环境，调试功能也强。右下角可以切换文件编码和换行符，这个功能在跨系统调试时非常实用。

Windows Terminal 比传统 cmd 和 PowerShell 都好用。它支持 UTF-8 显示，中文不会乱码。多标签功能让你可以同时开多个终端，一个跑 Windows 命令，一个跑 WSL 命令。复制粘贴也更顺手。如果你还在用 cmd，强烈建议换掉。

VS Code 的settings.json里可以配置默认编码和换行符。我通常设"files.encoding": "utf8"和"files.eol": "\n"，这样新建文件默认就是 UTF-8 加 LF，减少跨系统问题。对于已有文件，VS Code 会保留原编码和换行符，不会强制转换。

调试 Python 时，VS Code 的launch.json可以配置环境变量和工作目录。跨系统调试时，把工作目录设成相对路径，环境变量按系统分别配置。这样同一套调试配置在两个系统上都能用。

6.2 依赖管理：锁定版本与虚拟环境

跨系统工具出问题，有时不是代码的锅，而是依赖版本的锅。同一个库，Windows 和 Linux 上安装的版本可能不同，行为也可能不同。解决办法是用虚拟环境加版本锁定。

Python 的venv是标准做法。在项目目录下python -m venv .venv，然后激活。Windows 上激活用.venv\Scripts\activate，Linux 上用source .venv/bin/activate。激活后安装依赖，版本会记录在requirements.txt里。但requirements.txt默认只记录直接依赖，不记录间接依赖的版本。建议用pip freeze > requirements.txt锁定所有版本。

更现代的做法是用pyproject.toml加poetry或pip-tools。这些工具能生成锁定文件，确保两个系统上安装的依赖版本完全一致。如果项目简单，requirements.txt加pip freeze也够用。

还有一个细节：有些库在 Windows 和 Linux 上的依赖不同。比如pywin32只在 Windows 上需要，uvloop只在 Linux 上需要。在requirements.txt里可以用环境标记：

pywin32; sys_platform == "win32" uvloop; sys_platform != "win32"

这样安装时会自动跳过不适用于当前系统的包。

6.3 测试策略：在两个系统上跑同一套用例

跨系统工具没有测试，就等于在赌。我的做法是写一套简单的测试用例，在两个系统上都跑。测试不需要很复杂，覆盖核心功能就行。比如合并 CSV 的工具，测试用例包括：空目录、单文件、多文件、中文内容、带 BOM 的文件、不同换行符的文件。

用pytest写测试很方便。测试数据放在tests/data目录下，测试代码用tmp_path创建临时目录，避免污染工作区。断言输出文件的编码、换行符、内容是否符合预期。

import csv from pathlib import Path def test_merge_csv(tmp_path): input_dir = tmp_path / "input" input_dir.mkdir() (input_dir / "a.csv").write_text("name,age\nAlice,30\n", encoding="utf-8") (input_dir / "b.csv").write_text("name,age\nBob,25\n", encoding="utf-8") output = tmp_path / "merged.csv" merge_csv(input_dir, output) content = output.read_text(encoding="utf-8") assert "Alice" in content assert "Bob" in content assert "\r" not in content

这个测试在 Windows 和 Linux 上都能跑，断言了内容和不含\r。如果换行符控制不对，测试就会失败。把测试跑在两个系统上，能提前发现大部分跨系统问题。

如果条件有限，至少在一个系统上跑测试，然后在另一个系统上手动验证核心功能。手动验证虽然累，但比出了问题再查要省时间。

7. 从 Codex 生成到跨系统交付的完整检查清单

7.1 代码生成阶段的提示词模板

让 Codex 生成跨系统代码，提示词里要把约束写清楚。我常用的模板是这样的：

用 Python 写一个跨系统脚本，要求： 1. 在 Windows 和 Linux 上都能运行 2. 所有文件操作显式指定 encoding='utf-8' 3. 路径操作统一用 pathlib.Path 4. 写入文件时指定 newline=''，换行符统一用 \n 5. 外部命令调用前用 shutil.which 检查是否存在 6. 环境变量读取按 sys.platform 分支处理 7. 不要依赖任何系统默认值 8. 代码里加必要注释，说明跨系统注意事项

这个模板覆盖了大部分跨系统坑。Codex 按这个模板生成的代码，质量明显比默认生成的高。你还可以根据项目特点追加要求，比如“处理 CSV 时用 utf-8-sig 读取”“输出文件按文件名排序”等。

生成后，让 Codex 自己审查一遍：“检查这段代码在 Windows 和 Linux 上运行时可能产生不同结果的地方，列出来并修复。” 这一步能再筛掉一些漏网之鱼。

7.2 交付前的最终验证步骤

代码写完、测试跑完，交付前还有几步验证。第一步，在两个系统上分别跑一遍完整流程，对比输出文件。用diff或者fc命令对比，看内容是否完全一致。如果文件是二进制或者编码不同，用md5sum或certutil -hashfile对比哈希。

第二步，检查输出文件的编码和换行符。用 VS Code 打开，看右下角显示的编码和换行符是否符合预期。或者用 Python 读进来，检查\r是否存在。

第三步，检查路径。把输出文件复制到另一个系统，看能否正常打开和使用。如果路径写进了配置文件，检查路径分隔符是否兼容。

第四步，检查依赖。在干净的环境里安装依赖，跑一遍。确保没有遗漏的依赖，也没有系统特定的依赖被硬编码。

第五步，检查日志和错误处理。如果工具在另一个系统上失败，错误信息是否清晰？有没有把系统特定的错误直接抛给用户？好的错误处理能让排查事半功倍。

7.3 持续维护：Codex CLI 更新后的回归测试

Codex CLI 更新后，生成的代码风格可能变化。我遇到过更新后 Codex 开始默认用pathlib，但有些地方又混用os.path，导致代码风格不统一。还有一次更新后，Codex 生成的代码里encoding参数时有时无，需要手动补。

我的做法是维护一套回归测试用例，每次 Codex CLI 更新后，用同样的提示词生成代码，跑测试用例，看是否通过。如果失败，对比新旧代码，看是哪里变了。这样能快速发现更新带来的行为变化，及时调整提示词或手动修复。

回归测试不需要很复杂，覆盖核心功能就行。关键是每次更新后都跑一遍，形成习惯。跨系统工具的稳定性，靠的就是这种持续验证。

提示：Codex CLI 的更新日志值得看一眼，里面通常会提到生成行为的变化。如果更新日志说“改进了跨平台代码生成”，那正好，测试一下是否真的改进了。如果没说，更要测试，因为可能悄悄变了。

8. 个人实操体会与后续扩展方向

我用 Codex 写跨系统工具这段时间，最大的体会是：AI 生成的代码是起点，不是终点。Codex 能帮你快速搭出框架，但跨系统的细节必须自己把控。那些“能跑但结果不对”的问题，本质上都是环境假设问题，而 Codex 的环境假设和你的真实环境之间，永远有差距。

另一个体会是，显式优于隐式。所有依赖默认行为的地方，都是潜在的跨系统坑。把编码、换行、路径、环境变量全部显式声明，代码会啰嗦一点，但跨系统稳定性会好很多。我现在的习惯是，Codex 生成代码后，先搜open(、os.path、subprocess、os.environ，逐个检查，该改的改，该加的加。

还有一个实用技巧：把常用的跨系统辅助函数抽成一个模块，比如cross_platform.py，里面放get_home()、get_temp_dir()、find_executable()、read_text()、write_text()这些函数。Codex 生成代码时，让它引用这个模块。这样跨系统处理逻辑集中在一处，维护起来方便，也不容易遗漏。

后续如果要把这个工具扩展成更复杂的应用，可以考虑几个方向。一是加配置文件支持，用configparser或toml，注意配置文件本身的编码和路径处理。二是加日志，用logging模块，日志文件统一用 UTF-8 和 LF。三是打包成可执行文件，用pyinstaller，注意打包时把依赖和资源文件带上，并在两个系统上分别打包测试。四是加命令行参数解析，用argparse，注意 Windows 和 Linux 的参数传递差异。

跨系统工具的开发，说到底就是跟环境差异做斗争。Codex 帮你写代码，你帮 Codex 补环境。两者配合好了，工具就能在两个系统上都跑出正确结果。这个过程需要耐心，但一旦形成工作流，效率会高很多。