Python项目必备：用pathlib库告别文件路径处理的坑

52次阅读

共计 9338 个字符，预计需要花费 24 分钟才能阅读完成。

刚帮同事看一个自动化脚本，发现文件路径处理部分写得特别复杂，各种 os.path.join、os.path.abspath 混着用，还时不时遇到 Windows 和 Linux 路径斜杠的问题。这让我想起了自己刚接触 Python 时，也在这块吃过不少苦头。其实，Python 3.4 以后引入的 pathlib 库，能让这些操作变得异常优雅且健壮，今天咱们就一起来实操一遍，一劳永逸地解决路径难题。

pathlib 的核心思想是把文件系统路径抽象成 Path 对象。这意味着你不再需要像处理普通字符串那样拼接、拆分路径，而是可以像操作其他 Python 对象一样，调用它的方法，利用面向对象的特性。

实操第一步：创建 Path 对象

创建 Path 对象非常简单，直接把路径字符串传给 Path() 构造函数就行。它会自动根据当前操作系统处理路径分隔符，让你彻底告别和 / 的烦恼。

from pathlib import Path

# 1. 当前工作目录
current_dir = Path('.')
print(f"当前目录 Path 对象: {current_dir}")
print(f"绝对路径: {current_dir.resolve()}") # resolve() 会返回绝对路径并消除所有符号链接

# 2. 指定路径
data_folder = Path('data/raw_data')
print(f"指定相对路径 Path 对象: {data_folder}")

# 3. 绝对路径
log_file = Path('/var/log/my_app.log') # 在 Linux/macOS
# 或者 log_file = Path('C:/ProgramData/MyApp/log.txt') # 在 Windows
print(f"指定绝对路径 Path 对象: {log_file}")

# 4. 用户主目录 (常用！不用再手动找 HOME 变量了)
home_dir = Path.home()
print(f"用户主目录 Path 对象: {home_dir}")

# 小提醒：我刚接触时，总以为 Path 对象就是字符串，直接拼接就完事了，# 结果发现不行，pathlib 有它自己的一套优雅的拼接方式，后面会讲到。# 另外，Path 对象本身是可哈希的，可以作为字典的键，这是普通字符串路径不具备的优势。

经验总结： Path 对象是 pathlib 的基石。创建它时，无论是相对路径、绝对路径，甚至是用户主目录，都有简洁明了的方式。理解它是一个“路径对象”而不是简单的字符串，是掌握 pathlib 的第一步。

以前用 os.path.join 拼接路径，需要各种注意字符串类型、斜杠方向。pathlib 用一个非常 Pythonic 的方式解决了这个问题：使用 / 运算符。

实操第二步：路径拼接

from pathlib import Path

base_dir = Path('/Users/zhangsan/projects')
project_name = 'my_python_app'
config_file = 'config.ini'

# 1. 使用 / 运算符拼接路径，无论是目录还是文件，都像搭积木一样自然
project_path = base_dir / project_name
config_path = project_path / 'settings' / config_file

print(f"项目路径: {project_path}")
print(f"配置文件路径: {config_path}")

# 2. 拼接 Path 对象和字符串
data_folder = Path('data')
daily_report = data_folder / 'reports' / '2023-10-27_report.csv'
print(f"日报路径: {daily_report}")

# 3. 跨平台自动处理：你不需要关心是 Windows 的  还是 Linux 的 /
# pathlib 会自动根据操作系统进行调整，代码写一次，全平台通用。windows_path = Path("C:/Users") / "Admin" / "Documents" # 即使在 Linux 上写 Windows 风格，它也能正确处理为当前系统路径。print(f"跨平台路径示例: {windows_path}")

# 小提醒：以前用 os.path.join 时，一不小心就遇到跨平台斜杠问题，# 比如在 Windows 上拼接出 / 的路径导致文件找不到，pathlib 内部帮你处理好了，省心！

实操第三步：路径分解与获取信息

Path 对象提供了丰富的属性，让你轻松获取路径的各个部分，比如文件名、扩展名、父目录等，省去了 os.path.basename、os.path.splitext 等复杂的组合。

from pathlib import Path

file_path = Path('/home/user/documents/report.2023.pdf')

# 1. 获取文件名 (带扩展名)
file_name = file_path.name
print(f"文件名 ( 带扩展名): {file_name}") # report.2023.pdf

# 2. 获取文件名 (不带扩展名，也叫“主干名”)
stem = file_path.stem
print(f"文件名 ( 不带扩展名): {stem}") # report.2023

# 3. 获取文件扩展名 (带点)
suffix = file_path.suffix
print(f"文件扩展名: {suffix}") # .pdf

# 4. 获取所有扩展名 (针对多重扩展名，如 .tar.gz)
multi_ext_file = Path('archive.tar.gz')
suffixes = multi_ext_file.suffixes
print(f"所有扩展名: {suffixes}") # ['.tar', '.gz']

# 5. 获取父目录 (直接返回 Path 对象)
parent_dir = file_path.parent
print(f"父目录 Path 对象: {parent_dir}") # /home/user/documents

# 6. 获取所有父目录 (一个 Path 对象的元组)
parents = file_path.parents
print(f"所有父目录: {list(parents)}") # [Path('/home/user/documents'), Path('/home/user'), Path('/home'), Path('/')]

# 7. 获取路径的各个组成部分 (元组)
parts = file_path.parts
print(f"路径组成部分: {parts}") # ('/', 'home', 'user', 'documents', 'report.2023.pdf')

# 8. 修改扩展名 (返回一个新的 Path 对象)
new_extension_path = file_path.with_suffix('.txt')
print(f"修改扩展名后的路径: {new_extension_path}") # /home/user/documents/report.2023.txt

# 小提醒：Path.stem 对于处理像 `report.2023.pdf` 这种带多个 `.` 的文件名时非常方便，# 它只会取最后一个 `.` 之前的部分。如果想获取 `report`，你可能需要组合 `stem` 和 `suffix`。

经验总结： pathlib 的 / 运算符让路径拼接变得前所未有的简单和直观，彻底解决了跨平台兼容性问题。同时，Path 对象丰富的属性让你能像解析一个数据结构一样，轻松获取路径的各种信息，告别了 os.path 里一堆函数组合的复杂操作。

pathlib 不仅能处理路径本身，还能直接对路径指向的文件或目录进行操作，这大大简化了文件系统的交互。

实操第四步：创建、检查与删除文件 / 目录

from pathlib import Path
import os
import shutil # 用于清理测试目录

# 1. 定义一个测试目录
test_base_dir = Path('my_pathlib_test')
# 确保测试环境干净
if test_base_dir.exists():
    shutil.rmtree(test_base_dir) # 递归删除目录及其内容

# 2. 创建目录 (支持递归创建)
# 我平时用 mkdir() 时，习惯加上 parents=True 和 exist_ok=True，# 不然要是父目录不存在或者目录已存在，程序就报错了。# # 这里加 parents=True, exist_ok=True 是因为之前写自动化脚本时，忘记创建中间目录，导致报错，多踩几次就记住了。(test_base_dir / 'sub_dir' / 'another_sub').mkdir(parents=True, exist_ok=True)
print(f"目录'{test_base_dir / 'sub_dir' / 'another_sub'}'已创建。")

# 3. 创建文件 (如果文件不存在则创建，存在则不操作)
file_a = test_base_dir / 'file_a.txt'
file_b = test_base_dir / 'sub_dir' / 'file_b.json'
file_a.touch()
file_b.touch()
print(f"文件'{file_a}'和'{file_b}'已创建。")

# 4. 检查文件 / 目录是否存在
print(f"'{file_a}' 存在吗? {file_a.exists()}")
print(f"'{test_base_dir /'non_existent_file.txt'}' 存在吗? {(test_base_dir / 'non_existent_file.txt').exists()}")
print(f"'{test_base_dir}' 是目录吗? {test_base_dir.is_dir()}")
print(f"'{file_a}' 是文件吗? {file_a.is_file()}")

# 5. 删除文件
file_a.unlink() # 相当于 os.remove()
print(f"文件'{file_a}'已删除。")
print(f"'{file_a}' 存在吗? {file_a.exists()}")

# 6. 删除空目录
(test_base_dir / 'sub_dir' / 'another_sub').rmdir() # 只能删除空目录
print(f"空目录'{test_base_dir / 'sub_dir' / 'another_sub'}'已删除。")

# 7. 清理测试目录 (递归删除，pathlib 本身没有类似 shutil.rmtree 的方法)
shutil.rmtree(test_base_dir)
print(f"测试目录'{test_base_dir}'已清理。")

实操第五步：读写文件

pathlib 提供了方便的 read_text()、write_text()、read_bytes()、write_bytes() 方法，省去了 open()、read()、write() 的繁琐。

from pathlib import Path
import json

test_file = Path('my_data.txt')
json_file = Path('config.json')

# 1. 写入文本
test_file.write_text("Hello, pathlib!nThis is a test line.")
print(f"已向'{test_file}'写入文本。")

# 2. 读取文本
content = test_file.read_text()
print(f"从'{test_file}'读取内容:n{content}")

# 3. 写入二进制数据 (例如图片、视频，或需要特定编码的文本)
binary_data = b'x00x01x02x03'
test_file.write_bytes(binary_data)
print(f"已向'{test_file}'写入二进制数据。")

# 4. 读取二进制数据
read_binary = test_file.read_bytes()
print(f"从'{test_file}'读取二进制内容: {read_binary}")

# 5. 写入 JSON 数据 (结合 json 模块)
config_data = {"name": "My App", "version": "1.0", "settings": {"debug": True}}
json_file.write_text(json.dumps(config_data, indent=4))
print(f"已向'{json_file}'写入 JSON 数据。")

# 6. 读取 JSON 数据
read_config = json.loads(json_file.read_text())
print(f"从'{json_file}'读取 JSON 内容: {read_config}")
print(f"Debug 模式: {read_config['settings']['debug']}")

# 清理
test_file.unlink()
json_file.unlink()

实操第六步：遍历目录

遍历目录是文件操作中的常见需求，pathlib 提供了 iterdir()、glob() 和 rglob() 等方法，比 os.listdir 结合 os.path.join 要方便得多。

from pathlib import Path
import shutil

# 创建测试目录结构
test_root = Path('temp_project')
(test_root / 'src').mkdir(parents=True, exist_ok=True)
(test_root / 'docs').mkdir(parents=True, exist_ok=True)
(test_root / 'data' / 'raw').mkdir(parents=True, exist_ok=True)
(test_root / 'data' / 'processed').mkdir(parents=True, exist_ok=True)

(test_root / 'src' / 'main.py').touch()
(test_root / 'src' / 'utils.py').touch()
(test_root / 'docs' / 'README.md').touch()
(test_root / 'docs' / 'LICENSE.txt').touch()
(test_root / 'data' / 'raw' / 'sample.csv').touch()
(test_root / 'data' / 'processed' / 'output.json').touch()
(test_root / '.gitignore').touch()


print("n--- 使用 iterdir() 遍历一级子项 ---")
# 1. iterdir()：遍历目录下的所有文件和子目录 ( 非递归)
# 返回的是 Path 对象的迭代器，可以直接操作
for item in test_root.iterdir():
    print(f"{item.name} {'( 目录)'if item.is_dir() else'( 文件)'}")

print("n--- 使用 glob() 匹配文件 (非递归) ---")
# 2. glob()：在当前目录查找匹配指定模式的文件 ( 非递归)
# 模式支持通配符：* (任意字符), ? (单个字符), [] ( 字符集)
print("所有 .py 文件:")
for py_file in test_root.glob('*.py'): # 没找到，因为 .py 文件在 src 目录下
    print(f"{py_file}")
print("所有 .md 或 .txt 文件:")
for doc_file in test_root.glob('docs/*.md'):
    print(f"{doc_file}")
for doc_file in test_root.glob('docs/*.txt'):
    print(f"{doc_file}")

print("n--- 使用 rglob() 递归匹配文件 ---")
# 3. rglob()：递归查找匹配指定模式的文件 ( 深度遍历)
print("所有 .py 文件 ( 递归查找):")
for py_file in test_root.rglob('*.py'):
    print(f"{py_file}")

print("所有 .csv 和 .json 文件 ( 递归查找):")
for data_file in test_root.rglob('*.csv'):
    print(f"{data_file}")
for data_file in test_root.rglob('*.json'):
    print(f"{data_file}")

# 小提醒：我刚开始用 glob/rglob 时，总以为它能像 `ls -R` 那样把所有文件都列出来，# 结果发现需要指定模式。掌握通配符后，它就成了文件查找的利器，比 `os.walk` 结合手动过滤方便多了。# 比如 `rglob('**/*.py')` 可以找到所有子目录下的 Python 文件。# 清理测试目录
shutil.rmtree(test_root)
print(f"n 测试目录'{test_root}'已清理。")

经验总结： pathlib 提供的文件和目录操作方法，让日常的文件系统交互变得异常简洁。尤其是 read_text/write_text 省去了 open() 上下文管理器，glob/rglob 则让文件查找和过滤更加高效。

在项目开发中，灵活地在相对路径和绝对路径之间切换是十分重要的，它关系到代码的可移植性和健壮性。

实操第七步：路径转换

from pathlib import Path
import os

# 定义一个基准路径
current_working_directory = Path.cwd() # 获取当前工作目录
print(f"当前工作目录: {current_working_directory}")

# 假设有一个相对于当前工作目录的路径
relative_path_to_file = Path('data/processed/report.csv')
print(f"相对路径: {relative_path_to_file}")

# 1. 转换为绝对路径 (resolve() 会解析所有符号链接和 '..' 等 )
# absolute() 也会返回绝对路径，但不一定会解析符号链接
absolute_path = (current_working_directory / relative_path_to_file).resolve()
print(f"解析后的绝对路径: {absolute_path}")

# 2. 从绝对路径获取相对于某个基准路径的相对路径
# 场景：你有一个文件的绝对路径，想知道它相对于你的项目根目录的路径
project_root = current_working_directory.parent # 假设上一级是项目根目录
try:
    relative_to_project_root = absolute_path.relative_to(project_root)
    print(f"文件相对于项目根目录的路径: {relative_to_project_root}")
except ValueError as e:
    print(f"无法获取相对路径，因为 {absolute_path} 不是 {project_root} 的子路径。错误: {e}")

# 小提醒：用 `relative_to()` 时，如果路径不是相对关系（即一个不是另一个的子路径），# 会报错 `ValueError`。所以，在使用前最好确保它们确实存在父子关系。

经验总结： resolve() 和 relative_to() 是 pathlib 中处理路径转换的两个关键方法。前者确保你获得的是一个清晰、无歧义的绝对路径；后者则帮助你在复杂的文件结构中，保持路径的相对性，从而提高脚本的可移植性。

即使 pathlib 已经大大简化了路径操作，但初学者还是容易踩到一些“坑”：

误区一：混淆 Path 对象和字符串
- 现象： 认为 Path 对象就是字符串，直接传给一些只接受字符串路径的旧 API (比如 subprocess 模块的一些函数，或者某些第三方库 )。
- 正解： Path 对象在大多数情况下可以无缝转换为字符串 (当需要字符串时，Python 会自动调用 Path.__str__ 方法 )。但如果遇到明确需要字符串的场景，显式地使用 str(path_obj) 是最稳妥的做法。
- 我的经验： 刚开始用 pathlib 时，有次写 os.system(f'ls {my_path_obj}') 竟然报错，调试半天才发现 ls 命令期望的是字符串，老老实实加 str() 就行了。
误区二：忘记处理文件 / 目录不存在的情况
- 现象： 直接调用 read_text()、unlink()、rmdir() 等方法，而没有检查文件或目录是否存在，导致 FileNotFoundError 或 OSError。
- 正解： 在进行文件操作前，先用 path.exists()、path.is_file()、path.is_dir() 进行检查，或者使用 try...except FileNotFoundError 等方式捕获异常。mkdir(exist_ok=True) 和 touch() 都是很好的防守策略。
- 我的经验： 自动化脚本中，文件路径往往是动态生成的，之前有几次因为文件不存在就直接读取，导致脚本中断。现在我的习惯是，凡是涉及文件读写操作，必加 if path.exists(): 或者 try...except 块。
误区三：过度依赖绝对路径，忽略可移植性
- 现象： 在代码中硬编码大量绝对路径，或者不加思索地将所有路径都 resolve() 成绝对路径。
- 正解： 优先使用相对路径。只有在需要确保路径的唯一性和稳定性，或者与外部系统交互时，才将相对路径转换为绝对路径。利用 Path.cwd()、Path(__file__).parent (当前文件所在目录) 等获取基准路径，再拼接相对路径，能让你的代码在不同环境、不同机器上都能正常运行。
- 我的经验： 刚毕业那会儿，我写了个脚本，把数据文件路径直接写死了 /home/myuser/data/input.csv，结果部署到服务器上根本跑不起来，因为服务器没有 /home/myuser 这个目录。后来学会了用 Path(__file__).parent 定位脚本自身位置，再相对地找数据文件，脚本一下就变得超级好用，再也不用担心部署问题。