在子目录中运行 GitHub Actions 的三种方式

1. 简介

GitHub Actions 默认会在仓库的根目录下执行。但在实际项目中，我们经常会遇到需要操作子目录中的文件或资源的场景。为了更高效地处理这些嵌套目录中的操作，我们可以对工作流进行配置或编写脚本。

本文将介绍三种在子目录中运行 GitHub Actions 的方法，帮助你在复杂项目结构中更灵活地控制工作流的执行路径。

2. 使用文件或目录的完整路径

最简单直接的方式就是在执行命令时，直接指定目标文件或目录的路径。比如，我们可以在工作流中这样写：

name: 路径演示
on:
  push:
    branches:
      - main
jobs:
  demo:
    name: 演示任务
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cat directory_1/file_1
      - run: cat directory_2/file_2

执行结果如下图所示，两个命令分别成功读取了对应路径下的文件内容：

使用路径在 GitHub Actions 中执行命令

✅ 优点：适用于简单、单一文件的操作
❌ 缺点：当需要操作多个文件时会显得重复且不够高效
⚠️ 注意：建议使用绝对路径以避免相对路径带来的不确定性

3. 使用 `cd` 命令切换目录

我们也可以通过 cd 命令来切换当前执行路径，这样就可以在某个目录下执行多个命令，避免重复写路径。示例如下：

name: cd 命令演示
on:
  push:
    branches:
      - main
jobs:
  demo:
    name: 演示任务
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          cd directory_1
          cat file_1
      - run: |
          cd directory_2
          cat file_2

运行结果如下图所示，每个步骤都成功进入了指定目录并执行了命令：

使用 cd 命令切换 GitHub Actions 的执行目录

✅ 优点：适合在一个目录中执行多个命令
❌ 缺点：只能在 run 步骤中使用，不能在 job 层级使用 cd 切换目录
⚠️ 小贴士：多个命令可以合并到一个 run 块中执行，提升可读性

4. 使用 `working-directory` 关键字

GitHub Actions 提供了官方支持的 working-directory 配置项，可以更清晰地指定执行路径。这个关键字可以在 workflow、job 和 step 三个层级中使用。

4.1 在 Step 级别设置工作目录

name: working-directory 演示
on:
  push:
    branches:
      - main
jobs:
  demo:
    name: 演示任务
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cat file_1
        working-directory: directory_1
      - run: cat file_2
        working-directory: directory_2

效果如下图所示，每个命令都在指定的目录中执行：

在 GitHub Actions 的步骤中设置工作目录

✅ 优点：语法清晰，可读性强
⚠️ 注意：每个步骤都要单独配置，略显重复

4.2 在 Job 级别设置默认工作目录

如果一个 Job 中的所有步骤都在同一个目录下执行，我们可以在 Job 层级统一配置：

name: working-directory 演示
on:
  push:
    branches:
      - main
jobs:
  demo:
    name: 演示任务
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: directory_3
    steps:
      - uses: actions/checkout@v4
      - run: cat file_3
      - run: cat file_4

运行结果如下：

在 GitHub Actions 的任务中设置默认工作目录

✅ 优点：适用于整个 Job 内统一目录，减少重复配置
⚠️ 注意：仍需在每个 Job 中单独设置

4.3 在 Workflow 级别设置全局工作目录

如果整个工作流中的大部分 Job 都需要在同一个目录下执行，可以在 Workflow 层级统一设置：

name: working-directory 演示
on:
  push:
    branches:
      - main
defaults:
  run:
    working-directory: directory_3

jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cat file_1
  job2:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cat file_2
  job3:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cat file_3
  job4:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cat file_4

✅ 优点：适用于整个工作流统一目录，减少重复配置
⚠️ 注意：如果部分 Job 需要不同目录，需单独覆盖配置

5. 总结

本文介绍了三种在 GitHub Actions 中操作子目录的方法：

方法	适用场景	优点	缺点
使用完整路径	单个文件操作	简单直接	多文件时重复繁琐
`cd` 命令	同一目录下多个命令	可批量操作	仅限 `run` 步骤使用
`working-directory`	多层级目录控制	配置清晰，支持全局	需理解层级作用域

✅ **推荐使用 working-directory**，这是 GitHub 官方推荐方式，语法清晰，支持多层级配置，适合复杂项目结构。
⚠️ 踩坑提醒：cd 命令不能跨步骤保留路径状态，每个 run 块都是独立的 shell 会话。

Persistence

REST

Security