Python读取Excel报错FileNotFoundError怎么检查文件路径

一、报错本质：相对路径究竟相对于谁？

初学者在编写数据处理脚本时，最常遇到的困惑是：“我的 Python 代码和 Excel 文件明明在同一个文件夹里，为什么运行 pd.read_excel('sales.xlsx') 还是报错提示找不到文件？”

这个疑问背后隐藏着 Python 解释器的一个核心机制：相对路径永远是相对于“当前工作目录”（os.getcwd()），而不是相对于“代码文件所在目录”（__file__）。

import pandas as pd

# 代码看似正常，但在不同目录下执行会直接崩溃
df = pd.read_excel('sales.xlsx')
# FileNotFoundError: [Errno 2] No such file or directory: 'sales.xlsx'

举例来说，如果你的项目结构是：脚本存放在 /project/src/read.py，Excel 文件存放在 /project/src/sales.xlsx。如果你打开终端时停留在 /project 目录，并执行 python src/read.py，此时 Python 的当前工作目录就是 /project。当代码尝试读取 sales.xlsx 时，Python 实际上会在 /project/sales.xlsx 查找，自然无法找到位于 src/ 子目录下的文件。

二、四步排查法：精准定位真实文件路径

当出现 FileNotFoundError 报错时，不要反复去手动重命名文件或拖拽文件，按照以下四个标准步骤，可以在 1 分钟内查明症结：

第 1 步：打印并确认当前工作目录（os.getcwd）

在报错代码的前一行，加入当前工作目录的打印语句。这是最基础、最直接的诊断动作：

import os

# 打印 Python 程序此刻所处的工作目录
print("当前工作目录 (CWD):", os.getcwd())

查看输出的路径。判断此路径是否恰好是 Excel 文件所在的那个文件夹。如果不是，就说明程序启动位置与文件实际存放位置脱节。

第 2 步：查看拼接后的绝对路径并检验存在性

相对路径在操作系统底层最终都会被转换为绝对路径。直接使用 os.path.abspath() 输出 Python 实际去寻找的绝对路径，并用 os.path.exists() 验证系统反馈：

import os

target_file = "sales.xlsx"
abs_path = os.path.abspath(target_file)

print("Python 实际寻找的物理路径:", abs_path)
print("该物理路径是否存在:", os.path.exists(abs_path))

如果 os.path.exists() 返回 False，请直接复制打印出来的 abs_path 路径字符串，粘贴到操作系统的文件管理器（Windows 资源管理器或 macOS 访达）地址栏中进行跳转。系统通常会提示“找不到路径”，这便直接证实了路径推导的错误。

第 3 步：列出目录下的所有真实文件名

如果工作目录确认无误，但 exists() 依然是 False，很可能是文件名中包含了空格、大小写差异或不可见的后缀名。可以通过代码将该目录下的所有文件列出：

import os

# 查看当前工作目录下所有包含 'sales' 的文件
matched_files = [f for f in os.listdir(".") if "sales" in f.lower()]
print("找到的相关文件:", matched_files)

很多情况下，打印出来的结果会出人意料地显示为 ['sales.xlsx.xlsx'] 或 ['sales .xlsx']（带有意外的空格），真相瞬间大白。

第 4 步：检查字符串反斜杠转义

如果你在代码中写的是 Windows 绝对路径，例如 "C: ew_data est.xlsx"，必须警惕 Python 字符串中的反斜杠转义。 会被解释为换行， 会被解释为制表符。在路径前加 r 声明为原始字符串，或统一使用正斜杠 /。

三、三大高频“隐形陷阱”及排查技巧

在日常开发与数据分析中，有三个特别容易让人忽视的系统与环境陷阱：

1. Windows 系统的隐藏文件扩展名

Windows 资源管理器默认勾选了“隐藏已知文件类型的扩展名”。如果新建一个名为 data.xlsx 的工作簿，系统可能会在背后自动追加 .xlsx，其实际物理全名变成了 data.xlsx.xlsx。在资源管理器中视觉上只显示为 data.xlsx，但 Python 代码按 data.xlsx 去读取就会报 FileNotFoundError。

排查与修复：在 Windows 资源管理器顶部点击“查看”菜单，勾选“文件扩展名”复选框，核对文件是否变成了双后缀。如果是，直接重命名去掉多余的后缀。

2. Windows 路径反斜杠 \ 的字符转义灾难

在 Windows 系统中直接从资源管理器地址栏复制路径时，通常带有反斜杠：

# 错误示范：	 和 
 触发了 ASCII 转义
path = "C:	est
ew_project\sales.xlsx"
# 实际被 Python 解析为: C:[Tab]est[换行]ew_project\sales.xlsx

排查与修复：强烈建议采用以下两种安全写法之一：

# 方案 A：使用 raw string 原始字符串（在引号前加 r）
path = r"C:	est
ew_project\sales.xlsx"

# 方案 B：在 Python 中统一将反斜杠替换为正斜杠（全平台通用且无歧义）
path = "C:/test/new_project/sales.xlsx"

3. IDE（VS Code / PyCharm）工作区与启动目录不一致

在使用 VS Code 时，很多开发者通过“打开文件夹”加载了最外层的整个项目仓库。此时，VS Code 内置终端的默认工作目录是项目根目录。如果你的数据分析脚本保存在 analysis/chapter1/demo.py，直接点击右上角运行按钮时，执行上下文基于根目录，写相对路径 demo_data.xlsx 便会报错。

排查与修复：在 VS Code 设置中搜索 Execute In File Dir 并勾选（“When running a file in terminal, whether to use the file's directory instead of the currently open folder”），或直接使用下文介绍的动态绝对路径技术。

四、根治方案：基于 pathlib 的现代化健壮读取规范

为了一劳永逸地解决路径问题，既不应该使用脆弱的裸相对路径，也不应该使用写死盘符的硬编码绝对路径（因为换一台电脑或部署到 Linux 服务器就会立刻失效）。

现代 Python（Python 3.6+）推荐使用内置的标准库 pathlib.Path，通过 __file__ 动态锚定“当前脚本所在文件夹”，从而构建绝对可靠、自包含且跨平台的路径。

工业级 Excel 安全加载模板

在实际生产或数据分析项目中，推荐统一使用如下防御性代码模板：

from pathlib import Path
import pandas as pd

def load_excel_safely(filename: str):
    # 1. 动态获取当前脚本所在目录的绝对路径，不受终端运行位置影响
    base_dir = Path(__file__).resolve().parent
    
    # 2. 使用 / 操作符无缝拼接文件路径（自动适配 Win 的 \ 与 Linux/Mac 的 /）
    target_path = base_dir / filename
    
    # 3. 前置物理校验：提供明确的中文错误信息与排查路径
    if not target_path.is_file():
        raise FileNotFoundError(
            f"未找到目标 Excel 文件！
"
            f"期望路径: {target_path}
"
            f"当前工作目录: {Path.cwd()}
"
            f"同级目录现有文件: {[p.name for p in base_dir.iterdir()]}"
        )
    
    # 4. 正常读取数据
    return pd.read_excel(target_path)

# 调用示例
if __name__ == "__main__":
    df = load_excel_safely("sales.xlsx")
    print(f"成功加载 Excel 数据，共 {len(df)} 行")

五、排查自检速查清单

遇到报错时，对照下表进行 30 秒快速自检：

只要严格按照“打印 CWD → 校验绝对路径 → 检查真实文件全名 → 转换为 Pathlib 动态基准”这一链路执行，Python 读取 Excel 的路径报错问题便能彻底解决并在未来的代码中有效预防。