Jupyter Notebook在GitHub Actions中访问data目录触发FileNotFoundError

本地运行使用pdfplumber提取PDF数据的Jupyter Notebook完全正常，但在GitHub Actions中执行时触发错误：FileNotFoundError: [WinError 3] The system cannot find the path specified: 'data'。

项目结构 #

pdf_data_extract/
├── data/
│   └── part_number_chart.pdf
├── notebook/
│   └── pdf_extract.ipynb
├── .github/
│   └── workflows/
│       └── test.yml
├── requirements.txt
└── .gitignore

Notebook核心代码 #

import os

dir = 'data'
for filename in os.listdir(dir):
    if filename.endswith('.pdf'):
        pdf_file_fullpath = os.path.join(dir, filename)
        print(pdf_file_fullpath)

GitHub Actions运行步骤 #

- name: Run notebook
  run: jupyter nbconvert --to notebook --execute notebook/pdf_extract.ipynb --output notebook/pdf_extract.ipynb

已确认远程仓库存在data目录及PDF文件，添加打印当前工作目录和文件列表的步骤后，显示data目录确实存在，但仍触发相同错误。

原因分析 #

问题核心是Notebook执行时的工作目录不一致：

• 本地运行时，你的工作目录是项目根目录pdf_data_extract/，所以'data'相对路径能直接定位到根目录下的data文件夹。
• GitHub Actions中执行jupyter nbconvert时，Notebook的默认工作目录是它自身所在的notebook/文件夹，此时'data'会被解析为notebook/data/——这个路径不存在，因此报错。

解决方案 #

1. 动态获取项目根路径（跨环境通用，推荐） #

修改Notebook代码，通过动态计算定位项目根目录，确保本地和CI环境都能正确找到data文件夹：

import os

# 兼容脚本和Jupyter Notebook的路径获取逻辑
try:
    # 脚本模式下，获取当前文件的上级目录（即项目根）
    notebook_path = os.path.abspath(__file__)
    project_root = os.path.dirname(os.path.dirname(notebook_path))
except NameError:
    # Jupyter模式下，判断当前工作目录，自动定位根目录
    current_dir = os.getcwd()
    if os.path.basename(current_dir) == 'notebook':
        project_root = os.path.dirname(current_dir)
    else:
        project_root = current_dir

# 拼接data目录的绝对路径
data_dir = os.path.join(project_root, 'data')

for filename in os.listdir(data_dir):
    if filename.endswith('.pdf'):
        pdf_file_fullpath = os.path.join(data_dir, filename)
        print(pdf_file_fullpath)

2. 在GitHub Actions中指定Notebook的工作目录 #

修改workflow步骤，通过--ExecutePreprocessor.cwd参数强制Notebook在项目根目录执行：

- name: Run notebook
  run: |
    jupyter nbconvert --to notebook --execute notebook/pdf_extract.ipynb \
    --output notebook/pdf_extract.ipynb \
    --ExecutePreprocessor.cwd="./"

这个方法配置简单，但依赖CI环境的设置，通用性不如动态路径方案。

3. 调试路径的验证步骤 #

在Notebook开头添加以下代码，输出路径信息，快速定位问题：

import os
print("当前工作目录:", os.getcwd())
print("解析的data路径:", os.path.abspath('data'))
print("路径是否存在:", os.path.exists(os.path.abspath('data')))

在GitHub Actions的日志中查看这些输出，就能明确路径解析的偏差所在。

内容的提问来源于stack exchange，提问作者Weverson Barbieri