Python获取当前文件目录：__file__、cwd与pathlib避坑指南

脚本在本地跑得好好的，一放到别的机器上或者换个目录执行就报“文件找不到”，这大概是每个写 Python 的人都遇到过的场景。问题的根子往往只有一个：Python 获取当前文件目录这一步写得太随意。有人随手一个os.getcwd()，有人抄来一段os.path.dirname(__file__)，看着都能跑，实际行为差别巨大。这篇内容就是把这件小事彻底拆开讲透：从__file__、os.getcwd()、sys.argv[0]三个“当前”到底指什么，到os.path与pathlib两套写法的取舍，再到打包成单文件、在 notebook 里运行、被别的模块 import、多进程调度这些真实场景下该怎么兜底。文中所有代码都可以直接复制改项目名使用，踩坑部分是我这几年在若干项目里真实撞过的墙。不管你是刚学 Python 几个月、还在和相对路径较劲的新手，还是已经写了几年、想把项目结构规范一遍的老手，都能从里面挑到能立刻用上的东西。

1. 路径这件事，为什么值得单独拎出来讲

1.1 换台机器就报错的脚本，问题多半出在这一行

我见过太多类似的项目：本地调试一切正常，交到别人手里第一句话就是“跑不起来”。打开日志一看，错误五花八门——FileNotFoundError: 'config.yaml'、No such file or directory: './logs/app.log'、ModuleNotFoundError绕了一圈其实是读配置失败。追进去看代码，基本都是这种写法：

with open("conf/settings.yaml", "r", encoding="utf-8") as f: cfg = yaml.safe_load(f)

这行代码没有任何语法问题，问题在于它用的是相对路径，而相对路径的参照物是进程的当前工作目录（current working directory，简称 cwd），不是你脚本文件所在的目录。你在项目根目录下敲python src/main.py，cwd 就是项目根目录，conf/settings.yaml刚好能对上；别人在上一层目录敲python myproject/src/main.py，cwd 变成上一层，同样的代码就找不到了。

这就是为什么“获取当前文件目录”看起来是个一行代码的小事，实际上决定了整个项目能不能被可靠地复现。一个合格的 Python 项目，所有内部资源的定位都应该以代码文件自身的位置为锚点，而不是以“用户在哪个目录下敲命令”为锚点。前者是确定的，后者完全不可控。

理解这一点之后，判断标准就很简单了：凡是项目自带的资源（配置、模板、静态文件、SQL 脚本），一律用文件路径锚定；凡是用户指定的输入输出（命令行参数、日志目录），才允许走 cwd。这条分界线划清楚，后面所有写法的选择都有了依据。

1.2 三个“当前”，混着用就会出事

新手最容易犯的错，是把三个完全不同的概念当成同一个东西。我习惯把它们叫“三个当前”：

• 当前工作目录（cwd）：进程启动时继承的环境，会随os.chdir()改变。os.getcwd()拿到的就是它，open("a.txt")这种相对路径也是以它为基准。
• 当前文件的目录：这段代码写在哪个.py文件里，那个文件所在的目录。拿它需要__file__这个模块级变量。
• 程序入口的目录：你敲python xxx.py时那个 xxx.py 的位置，或者打包之后可执行文件的位置。sys.argv[0]指向它。

三者在最简单的情况下（在项目根目录下python main.py，且代码就写在 main.py 里）恰好重合，所以很多人写了半年都没意识到它们是不同的东西。一旦代码被拆成多模块、被第三方 import、被打包、被调度器调用，这个“恰好重合”立刻破裂，bug 就冒出来了。

举个具体的例子说明差异有多致命。假设项目结构是这样：

myproject/ ├── main.py ├── core/ │ └── loader.py └── conf/ └── app.yaml

main.py里import core.loader之后调用loader.load()，而loader.py里写的是open("conf/app.yaml")。你在myproject/下执行python main.py，cwd 是myproject/，conf/app.yaml找得到，一切正常。但如果哪天有人写了个调度脚本在/opt/runner/下python /path/to/myproject/main.py，cwd 变成/opt/runner/，loader.py那行直接崩。

正确的写法应该是在loader.py里用__file__反推：Path(__file__).resolve().parent.parent / "conf" / "app.yaml"。这样无论谁在哪儿调用，只要文件结构不变，路径就永远对。多做一层.parent是因为 loader.py 在core/子目录里，需要往上跳一级到项目根。这种“往上跳”的写法配合固定的目录约定，是长期维护性最好的方案。

1.3 不同运行方式下，行为差异有多大

为了把这件事说清楚，我把常见的几种运行方式实测了一遍，对比__file__、os.getcwd()、sys.argv[0]三者的取值：

这张表里有几个点特别值得注意。第一，__file__在交互式环境里压根不存在，直接引用会抛NameError，所以线上代码里写__file__一定要有兜底分支，否则 notebook 用户和调试用户会第一个来找你。第二，python -m和python xxx.py下sys.argv[0]的含义不一样，用-m方式启动时它指向的是模块路径形式，做路径推导会踩坑。第三，打包之后__file__指向的是一个临时解压目录，程序退出就没了，拿它当数据存储位置等于数据全丢。

还有一个容易被忽略的细节：__file__在某些情况下是相对路径。比如用python main.py在当前目录启动，__file__可能就是main.py而不是/home/user/proj/main.py。直接对它用os.path.dirname()会得到空字符串''，然后os.path.join('', 'conf')就变成conf，又退化成相对路径了。这就是为什么几乎所有正确的写法都会先套一层os.path.abspath()或Path.resolve()——这一步不是可有可无的修饰，是把相对锚点转成绝对锚点的必要动作。

2. 六种取目录的写法，逐个拆开看

2.1 最经典的 os.path 三板斧，以及它的历史包袱

先说最广为流传的写法，几乎每篇教程都会给你这个：

import os BASE_DIR = os.path.dirname(os.path.abspath(__file__)) CONFIG_PATH = os.path.join(BASE_DIR, "conf", "app.yaml")

三层嵌套，拆开看每一步都有明确的意图。__file__拿到当前模块的文件标识（可能是相对形式），os.path.abspath()把它转成绝对路径并顺带规范化掉..和.，os.path.dirname()去掉文件名只留目录部分。这套组合的好处是兼容性好，Python 2 时代就能用，现在任何环境都不会出问题。

但它有两个我实打实踩过的坑。第一个是abspath()不解析软链接。如果你把项目目录通过软链接挂到别的地方，abspath(__file__)得到的是软链接路径而不是真实路径，之后基于它拼出来的资源路径在某些工具链下会失效（尤其是那些会做路径白名单校验的场景）。解决办法是换成os.path.realpath()，它会把沿途所有符号链接展开成真实物理路径。

第二个坑是dirname的行为。os.path.dirname("/a/b/c.py")返回/a/b，看着没问题；但如果文件在根目录下，os.path.dirname("/c.py")返回的是/，而BASE_DIR拼的时候如果直接用字符串相加就会得到//conf这种双斜杠路径，虽然大多数系统能容忍，但在日志里很难看，个别严格解析的工具会拒绝。

提示：abspath和realpath只差一个词，行为差很多。判断标准是：你需要的是“逻辑位置”就用abspath，需要的是“真实物理位置”就用realpath。做资源加载、特别是资源目录可能被映射或链接过的情况，一律用realpath，出问题的概率低得多。

os.path.join也值得多说一句。它的规则是：如果后面的参数是绝对路径，前面的会被丢弃。os.path.join("/a", "/b")得到的是/b而不是/a/b。这个特性在拼接用户输入时是安全隐患，在拼接固定常量时又容易造成困惑。我的习惯是只在拼接“确定性常量片段”时用它，绝不用它拼任何来自外部输入的字符串。

2.2 realpath 与 resolve：软链接场景下的分水岭

接着上面说，os.path.realpath(__file__)是在abspath基础上的升级版，它会做两件事：转绝对路径 + 展开符号链接。写成完整的一句：

import os BASE_DIR = os.path.dirname(os.path.realpath(__file__))

这一行目前在老派项目里出现频率最高，我认为它是os.path这套 API 里最稳的单行写法。原因很简单：它同时解决了相对路径和软链接两个问题，而且不依赖任何第三方库。

什么情况下软链接的差异会真的咬你一口？我遇到过两次。一次是在某台机器上，项目目录被做成了指向另一个存储卷的链接，代码里用abspath算出来的路径去读资源，程序本身能跑，但同一份路径传给下游一个外部工具做校验时，那个工具按真实路径做了前缀比对，直接判定为非法路径。另一次更隐蔽：某个自动化流程先cd到链接目录再启动程序，abspath和realpath得到的是两个不同前缀，日志文件的落盘位置和预期不符，排查了半天才发现是链接没展开。

pathlib里对应的是Path.resolve()，但它和realpath有一个历史差异需要注意。Python 3.6 之前，resolve()要求路径必须存在，路径不存在会抛FileNotFoundError；3.6 起改成默认strict=False，不存在的路径也能解析。如果你维护的代码要兼容很老的版本，或者依赖“路径不存在就报错”这个行为，就要显式传strict=True。现在主流的 3.8 以上版本默认行为是宽松的，绝大多数场景直接用就行。

from pathlib import Path BASE_DIR = Path(__file__).resolve().parent

对比一下两行代码，pathlib版本明显更好读。Path(__file__)把字符串变对象，.resolve()一步完成绝对化和软链接展开，.parent取父目录。语义一层层读下来就是“这个文件的真实路径的父目录”，和你想表达的意思完全对应，不需要在脑子里做dirname(abspath(x))这种反向推导。

2.3 pathlib：新项目我基本只写这一种

说说我为什么在 3.6 之后的新项目里基本只用pathlib。最直接的理由是路径拼接不用再担心分隔符。os.path.join和/在 POSIX 下等价，但在 Windows 上前者会用反斜杠，后者也自动适应当前平台。用/拼接的代码在两种系统上都能跑，而且读起来像路径本身，不用在脑子里翻译。

from pathlib import Path BASE_DIR = Path(__file__).resolve().parent CONF_DIR = BASE_DIR / "conf" CONFIG_PATH = CONF_DIR / "app.yaml" if not CONFIG_PATH.exists(): raise SystemExit(f"配置文件缺失: {CONFIG_PATH}") text = CONFIG_PATH.read_text(encoding="utf-8")

这里用read_text()替代了open()+ 上下文管理器，一行完成读文件。exists()、is_file()、is_dir()、suffix、stem、name这些属性和方法把原来需要os.path.xxx一堆函数才能做的事收进了对象里，代码短了不止一点。

但pathlib也不是万能的，有两个地方我还是会切回os.path或os。第一是某些老库的接口只接受字符串，pathlib对象传进去会报类型错，得手动str(p)转一下。第二是涉及文件权限、符号链接创建、os.walk这类底层操作时，os模块的接口更直接，绕pathlib反而啰嗦。这是实用主义的选择，不是非要统一到一种风格。

还有一个小细节值得提：Path(__file__).parent和Path(__file__).resolve().parent在大部分情况下结果一样，但当__file__是相对路径且你的 cwd 和文件所在目录不同时，前者得到的是相对路径的父目录（可能是个空路径.），后者才是真正的绝对目录。所以永远别省略.resolve()，这一层保险几乎零成本，能挡掉一整类和环境相关的问题。

2.4 os.getcwd()：不是不能用，是别用错地方

os.getcwd()被骂得很多，但我觉得这是冤枉的。它没有问题，问题在于很多人拿它去干它不该干的事。它的语义非常明确：返回进程当前的工作目录。注意是“进程的”，不是“脚本的”，也不是“项目的”。

它适合的场景有这么几类。一是做命令行工具时，用户不传路径参数，默认就用当前目录作为操作对象，这符合 shell 的直觉。二是需要在日志里记录“这次运行是从哪儿发起的”，用于复现问题特别好用。三是临时文件、下载目录、用户指定的输出路径这类东西，用 cwd 做基准是合理的。

它不适合的场景也很明确：定位项目自带的任何资源。因为 cwd 完全由调用方控制，你的代码对它没有任何约束力。还有一种情况要特别小心——程序运行过程中如果调用了os.chdir()，os.getcwd()的返回值就变了，后续所有相对路径的基准也跟着变。这种隐式状态变化在多人协作的项目里是灾难，我的建议是除极特殊情况外，项目代码里禁止使用os.chdir()，要切换目录就用subprocess传cwd=参数，或者干脆所有路径都用绝对路径。

import os from pathlib import Path # 适合：命令行工具的默认操作目录 work_dir = Path(os.getcwd()) # 适合：日志里记录调用上下文 print(f"[boot] cwd={work_dir}, argv={sys.argv}")

顺带说一个容易混淆的点：os.getcwd()和os.path.abspath(".")在正常情况下返回值一致，但前者是系统调用拿真实值，后者是走路径解析逻辑。在一些特殊文件系统（比如某些挂载点或已经删除的目录）上两者可能不一致，排查诡异问题时可以拿来交叉验证。

2.5 sys.argv[0] 与 inspect：定位“入口”而不是“本文件”

前面几种方法解决的都是“我这段代码在哪个文件里”。但有一类需求问的是另一个问题：用户启动的是哪个脚本。这时候该用sys.argv[0]。

import sys import os SCRIPT_DIR = os.path.dirname(os.path.abspath(sys.argv[0]))

这个写法在“单文件脚本分发给别人用”的场景下最合适。比如你写了一个小工具分发出去，用户可能在任意目录下用绝对路径调用它，你希望工具生成的输出文件放在工具旁边而不是用户当前目录，用sys.argv[0]就对了。

它有几个明确的短板，用之前得心里有数。第一，python -m package.module启动时sys.argv[0]指向的是模块路径形式，不是文件系统路径，拿它做dirname会得到意料之外的结果。第二，被别的程序 import 时，sys.argv[0]是主程序的路径，跟你这个模块一点关系没有。第三，在交互式环境里它可能是空字符串或者内核相关的参数。

还有一个更冷门的inspect方案，可以直接拿到当前栈帧对应的文件：

import inspect import os def get_frame_dir() -> str: frame = inspect.currentframe() if frame is None or frame.f_code.co_filename == "<stdin>": return os.getcwd() return os.path.dirname(os.path.abspath(frame.f_code.co_filename))

这套写法在写装饰器、日志工具、调试辅助函数时特别有用，因为它能拿到调用者的文件位置，而不是定义者的。但它有明显的代价：创建帧对象有性能开销，而且在某些优化过的运行环境或冻结打包的场景下不可靠。我的原则是只在调试和框架层用，业务代码不用。

2.6 交互式环境与 notebook 的兜底写法

前面提过，__file__在 Jupyter、IPython、REPL 里是不存在的，直接用会抛NameError。如果你的代码既要在正常脚本里跑，又要在 notebook 里做实验，就必须写兜底：

from pathlib import Path def get_base_dir(fallback_to_cwd: bool = True) -> Path: try: return Path(__file__).resolve().parent except NameError: if fallback_to_cwd: return Path.cwd() raise RuntimeError("当前环境没有 __file__，无法定位脚本目录")

这个函数的意图是一句话能说清的：优先用文件位置，拿不到就退回到 cwd。加了个fallback_to_cwd开关是因为两种情况的需求不同——做数据探索时退回 cwd 很方便，做生产部署时静默退回反而会掩盖问题，应该直接报错让人发现。

notebook 场景还有一层要注意：notebook 的Path.cwd()通常是你启动 Jupyter 服务的那个目录，不一定等于.ipynb文件所在的目录。如果 notebook 放在notebooks/子目录里而服务是从项目根启动的，cwd就是项目根。想要拿到.ipynb自身的位置，只能借用内核提供的变量，或者干脆在 notebook 顶部手动设一个常量：

# notebook 第一格：显式声明基准目录，比任何自动推导都可靠 BASE_DIR = Path.cwd() # 或 Path("/abs/path/to/project") DATA_DIR = BASE_DIR / "data"

我现在的习惯是——生产代码里必须能自动定位，notebook 里第一格显式写死一个BASE_DIR。看着不够优雅，但它把不确定性摆在明面上，比一堆自动推导逻辑更让人放心。

3. 落到真实场景：四类典型用法与参数权衡

3.1 配置与资源文件的定位，顺序不能乱

资源定位这块，我总结出一个固定的优先级链，值得抄进项目模板里。第一优先是从环境变量拿，允许部署时覆盖；第二是从文件位置推导；第三才是当前工作目录。

import os from pathlib import Path def locate_config(filename: str = "app.yaml") -> Path: # 1. 环境变量优先，方便容器化部署时挂载外部配置 env_path = os.environ.get("APP_CONFIG") if env_path: p = Path(env_path).expanduser().resolve() if p.is_file(): return p # 2. 项目内 conf 目录，以本文件位置为锚点 base = Path(__file__).resolve().parent for candidate in (base / "conf" / filename, base.parent / "conf" / filename): if candidate.is_file(): return candidate # 3. 最后兜底当前目录 cwd_candidate = Path.cwd() / filename if cwd_candidate.is_file(): return cwd_candidate raise FileNotFoundError(f"在预期位置均未找到配置文件: {filename}")

这段代码里有几个细节是我调试出来的。expanduser()是为了支持~/config/app.yaml这种写法，不加的话~会被当成普通目录名。resolve()放在is_file()之前，确保软链接和相对路径都被处理干净。循环里放了两个候选位置，是因为开发时的目录结构和安装后的结构经常不一致——开发时conf/和代码同级，安装后可能被放到上层。把两种可能都列上，比事后 debug 省事。

注意：expanduser()和expandvars()是两个不同的东西。前者展~，后者展$HOME这类环境变量。用户输入的路径两种都可能出现，安全一点的写法是两个都调一遍：Path(os.path.expandvars(env_path)).expanduser()。

3.2 打包成单文件后，路径会变成什么样

这是我认为最需要提前想清楚的场景。用 PyInstaller 之类的工具打成单文件后，运行时会先把内容解压到系统临时目录，__file__指向的就是那个临时目录。你如果拿它当数据存储位置，程序一退出数据就没了，而且每次启动路径还都不一样。

判断是不是打包环境，标准做法是检查sys.frozen：

import sys from pathlib import Path def app_root() -> Path: if getattr(sys, "frozen", False): # 打包后：数据放在可执行文件旁边，而不是临时解压目录 return Path(sys.executable).resolve().parent return Path(__file__).resolve().parent BASE_DIR = app_root() DATA_DIR = BASE_DIR / "data" DATA_DIR.mkdir(parents=True, exist_ok=True)

getattr(sys, "frozen", False)这个写法比hasattr更紧凑，也避免了一个坑：有些环境下frozen属性存在但值是False，用hasattr判断会误判。

还有一个问题很多人第一次打包才会遇到：只读资源怎么带进去。现在主流工具支持用--add-data把资源打进包里，但打进去之后读的时候要走sys._MEIPASS这个临时目录，而写的时候必须写到可执行文件旁边。也就是说读和写的基准是两个不同的目录，这个分离必须在代码里显式体现：

def resource_path(relative: str) -> Path: """只读资源：打包后从临时解压目录读，开发时从源码目录读""" if getattr(sys, "frozen", False) and hasattr(sys, "_MEIPASS"): return Path(sys._MEIPASS) / relative return Path(__file__).resolve().parent / relative

把“读资源”和“写数据”拆成两个函数，是我从一次线上事故里学来的。那次是把模板文件也当成了可写资源，打包后写入临时目录，程序关掉模板改动全没了，用户以为保存成功。从那以后我在项目里强制区分resource_path()和app_root()，谁读谁写一眼能看出来。

3.3 日志、缓存、临时文件的落盘位置

数据落盘的位置选择，本质上是在回答“这个东西的生命周期该跟谁绑定”。跟程序绑定就用app_root()，跟用户绑定就用Path.home()，跟系统绑定就用tempfile。

import tempfile from pathlib import Path # 用户级数据：跨版本保留，放用户目录 USER_HOME = Path.home() USER_CACHE = USER_HOME / ".myapp" / "cache" USER_CACHE.mkdir(parents=True, exist_ok=True) # 会话级临时文件：系统负责清理，别自己管 with tempfile.TemporaryDirectory() as tmp: tmp_path = Path(tmp) (tmp_path / "work.txt").write_text("hello", encoding="utf-8")

tempfile.TemporaryDirectory()用with包起来，退出时自动递归删除，比自己写try/finally干净得多。tempfile还提供了mkstemp()、NamedTemporaryFile()这些，但要注意 Windows 上文件被占用时删除会失败，用TemporaryDirectory()这种目录级的方式能绕开大部分问题。

Path.home()在容器里经常返回/root或者意料之外的值，如果你的程序要在容器里跑，最好允许用环境变量覆盖用户目录的基准。这一条不是理论推测，是实际部署时撞到过——容器里的HOME被设成了一个不存在的路径，mkdir直接报权限错。

3.4 被 import、跨进程调用时的边界

最后说一个隐蔽的场景：你的模块被别的程序 import 时，__file__仍然是你自己这个文件的路径，这一点是好消息，行为是确定的。但它依赖的cwd却是主程序启动时的值，这就出现了一个混合状态——文件锚点是准的，cwd 是别人的。

这种混合状态最容易在写库的时候翻车。如果你的库里有open("templates/x.html")这种写法，在作者自己的测试脚本里能跑，一到用户手里就崩，因为用户的 cwd 完全是另一回事。所以发布出去的库，代码里绝对不能出现任何裸相对路径，这是硬规矩。

多进程场景还有一层。用multiprocessing的spawn模式（Windows 默认、macOS 默认）启动子进程时，子进程会重新 import 主模块，__file__的解析会重新走一遍。在 Linux 上默认是fork，子进程继承父进程状态，包括已经chdir过的 cwd。这个平台差异会导致“同样的代码在 Linux 上正常、在 Windows 上找不到文件”。规避方法仍然是那条：所有路径在进程启动阶段就解析成绝对路径，作为参数传给子进程，别让子进程自己做路径推导。

from pathlib import Path from multiprocessing import Pool BASE_DIR = Path(__file__).resolve().parent def worker(task): target = BASE_DIR / "data" / f"{task}.txt" # 模块级常量已是绝对路径 return target.read_text(encoding="utf-8") if __name__ == "__main__": with Pool(4) as pool: print(pool.map(worker, ["a", "b", "c"]))

BASE_DIR定义在模块级、用绝对路径，这一个小动作就消掉了跨平台的进程差异。看着平淡，但它省掉的排查时间是以小时计的。

4. 踩坑实录与排查速查表

4.1 五个高频错误与现场还原

第一个：__file__是相对路径导致dirname返回空串。现象是os.path.join(os.path.dirname(__file__), "conf")在某些启动方式下得到conf而不是绝对路径，接着open()按 cwd 解析，报文件不存在。原因就是前面说的__file__有时是相对形式。修法只有一个：外面套abspath或resolve。

第二个：中文路径在 Windows 上出问题。表现是路径明明存在，os.path.exists()却返回False，或者读文件报编码错。根源是某些老版本环境里文件系统的编码和控制台编码不一致。稳妥做法是用pathlib处理路径，读文件时显式指定encoding="utf-8"，不要依赖系统默认编码——open()不传encoding时会用 locale 编码，在 Windows 上常常是gbk，跨机器必然出问题。

# 不推荐：依赖系统默认编码 with open(path) as f: text = f.read() # 推荐：显式指定 with open(path, "r", encoding="utf-8") as f: text = f.read() # 或者用 pathlib，一行搞定 text = Path(path).read_text(encoding="utf-8")

第三个：软链接没展开导致下游校验失败。前面提过，abspath不展开链接，某些场景下路径前缀比对会失败。修法是换realpath或resolve()。

第四个：打包后路径指向临时目录。现象是程序第一次能读到内置资源，重启后配置改了却没生效，或者写入的数据第二天不见了。原因是读写都跑了__file__。修法是区分resource_path()和app_root()，前面给了代码。

第五个：路径拼接用了字符串加法。BASE + "/conf/" + name这种写法看着没问题，实际会在几个地方翻车：Windows 上混用分隔符虽然大多数情况能容错但日志里很乱；BASE结尾如果已经有斜杠就变成双斜杠；路径里有空格时命令行传参会被拆开。老老实实用os.path.join或/运算符，两秒钟的事。

4.2 问题速查表

把上述问题整理成一张表，出问题时按现象对号入座，比从头读代码快得多：

4.3 几条我写在项目规范里的硬规矩

踩了足够多的坑之后，我把几条约束直接写进了团队的项目规范，新人入职第一天就会看到。第一条：业务代码中出现裸相对路径即视为缺陷，代码评审时直接打回。这条规矩推行了半年，路径相关的线上问题基本绝迹。

第二条：路径工具函数集中在一个模块里，不要在十几个文件里各自写os.path.dirname(__file__)。集中之后的好处是出问题只改一处，而且新同事能一眼看到项目对路径的约定。

第三条：所有open()必须显式传encoding。这条规矩的收益超出预期，因为它顺带解决了跨平台读文件的一大类问题。我会在pyproject.toml或 lint 配置里加规则自动检查，靠人记是记不住的。

第四条：目录创建统一用mkdir(parents=True, exist_ok=True)。parents=True让多级目录一次建完，exist_ok=True避免并发时的竞态报错。少了这两个参数，多进程同时建目录时会抛FileExistsError，这个 bug 极难复现。

5. 我自己项目里用的那套模板

5.1 一个可以直接抄的路径工具模块

说了这么多写法，最后把我实际在用的东西摊出来。新建项目时我第一个文件就是core/paths.py，内容大致如下：

"""项目统一路径入口：所有目录在这里定义，其他模块只允许 import 这里。""" import sys from pathlib import Path def _is_frozen() -> bool: return bool(getattr(sys, "frozen", False)) def app_root() -> Path: """可写数据的基准目录：打包后在可执行文件旁，开发时在项目根。""" if _is_frozen(): return Path(sys.executable).resolve().parent return Path(__file__).resolve().parent.parent def resource_root() -> Path: """只读资源的基准目录：打包后指向临时解压目录。""" if _is_frozen() and hasattr(sys, "_MEIPASS"): return Path(sys._MEIPASS) return Path(__file__).resolve().parent.parent ROOT = app_root() RES_ROOT = resource_root() CONF_DIR = ROOT / "conf" DATA_DIR = ROOT / "data" LOG_DIR = ROOT / "logs" TEMPLATE_DIR = RES_ROOT / "templates" def ensure_dirs() -> None: for d in (DATA_DIR, LOG_DIR): d.mkdir(parents=True, exist_ok=True) def conf(name: str) -> Path: p = CONF_DIR / name if not p.is_file(): raise FileNotFoundError(f"配置缺失: {p}") return p

这个模块有几个设计考虑值得说明。第一，模块级就调app_root()把结果缓存在常量里，避免每次调用都走一遍resolve()，那是有系统调用开销的。第二，ensure_dirs()单独抽出来而不是在 import 时自动执行，因为有些场景（比如只做单元测试）不需要创建目录，import 时带副作用会让测试变脏。第三，conf()里带了存在性检查并报出完整路径，出错时日志里直接能看到找了哪个地方，省掉一轮沟通。

用起来是这样的：

from core.paths import conf, DATA_DIR cfg_path = conf("app.yaml") output = DATA_DIR / "result.csv"

调用方拿到的永远是绝对路径对象，不存在任何相对路径的歧义。有人会问为什么不直接在模块顶部ensure_dirs()一把梭，我的理由是副作用要显式化——一个import就悄悄在磁盘上建目录，在容器和只读文件系统里会直接崩，还得查半天。

5.2 写进规范里的几条约定，以及我对这套东西的看法

除了代码模板，还有几条约定是我反复强调的。其一，不要在函数内部写Path(__file__)，全部走paths模块，这样将来项目结构变了，只改一个文件。其二，命令行参数里的路径一律用Path(x).expanduser().resolve()处理一遍再使用，用户可能传相对路径、可能带~、可能是软链接，统一规范化之后再往下传，后面的代码就不用操心这些。其三，日志里打印路径时打出绝对路径，排查问题时省掉“这个相对路径到底是相对于谁”的推理环节。

关于.resolve()的性能，有人担心调用太频繁。实测下来，单次resolve()在现代系统上是微秒级，一个程序启动时调用几十次完全不影响体验。真正有性能影响的是在紧循环里反复解析，那种情况才需要把结果提到循环外。为了省这点开销而牺牲路径的确定性，是典型的捡芝麻丢西瓜。

再补一个我最近才用上的小技巧：如果想让路径在日志和报错信息里更好读，可以对Path做相对化处理。Python 3.12 提供了Path.relative_to(other, walk_up=True)，可以算出相对于项目根的路径，打印出来是conf/app.yaml这种清爽形式，而不是一长串绝对路径。老版本就自己写个函数，os.path.relpath()也能达到类似效果。这个不影响功能，但对日志可读性提升明显，尤其是路径很深的时候。

最后说一句我自己的体会。路径处理这活儿看着琐碎，但它有个特点：做对了没有任何存在感，做错了到处冒烟。我现在接手任何项目，第一件事就是翻一遍有没有裸相对路径，有的话先改掉再看别的。这一步花的时间通常不超过半小时，但能省掉的排查时间往往以天计。上面那套模板和规矩，是我用若干次凌晨排查换来的，你直接抄走就好，不用再交一遍学费。