Windows 10 GitLab CI Shell执行Docker命令提示未找到问题排查

核心问题 #

你的Pipeline实际使用了docker+machine类型的Runner（而非你配置的shell executor Runner），同时即使切换到正确的shell Runner，也需要确保Docker CLI能在Runner的执行环境中被找到。

解决步骤 #

1. 确认Runner配置与生效状态 #

• 检查本地Runner配置文件：打开C:\ProgramData\GitLabRunner\config.toml，确保目标Runner的配置块符合要求：

  [[runners]]
    name = "Windows Shell Runner"
    url = "https://gitlab.com/"
    token = "你的Runner令牌"
    executor = "shell"
    shell = "pwsh"
    # 确保没有其他覆盖executor的配置项
  

• 重启GitLab Runner服务：在PowerShell中执行命令使配置生效：

  Restart-Service gitlab-runner
  

• 验证项目关联的Runner：进入GitLab项目的Settings → CI/CD → Runners页面，确认你配置的shell executor Runner处于启用状态，且没有被其他共享Runner抢占（如果项目启用了共享Runner，可能会优先使用）。

2. 强制Pipeline使用指定的Shell Runner #

在.gitlab-ci.yml中为job添加tags，绑定到你配置的Runner（需提前给Runner设置标签，比如windows-shell）：

stages:
  - deploy

deploy-api:
  stage: deploy
  tags:
    - windows-shell  # 与你的shell Runner标签一致
  script:
    - docker compose up --build -d

如果未设置标签，可将该Runner设为项目的专属Runner（在GitLab Runner设置中勾选"Run untagged jobs"），同时禁用项目的共享Runner，避免误选。

3. 解决Docker命令找不到的问题 #

• 本地验证Docker CLI可用性：在本地PowerShell中执行docker --version和docker compose --version，确认命令可正常运行。
• 确保Runner环境包含Docker路径：GitLab Runner默认使用系统账户运行，需确保系统账户的PATH环境变量包含Docker CLI的路径（默认是C:\Program Files\Docker\Docker\resources\bin）。可在.gitlab-ci.yml的before_script中手动添加路径：

  before_script:
    - $env:PATH += ";C:\Program Files\Docker\Docker\resources\bin"
  

• 确认Docker Desktop运行状态：确保Docker Desktop处于启动状态，且已启用"Use the WSL 2 based engine"（若使用WSL2）。

4. 排查执行环境 #

添加测试job验证Runner环境：

test-runner-env:
  tags:
    - windows-shell
  script:
    - echo "当前Runner Executor: $env:RUNNER_EXECUTOR"
    - echo "系统PATH: $env:PATH"
    - docker --version

运行该job后，查看日志确认RUNNER_EXECUTOR为shell，且PATH包含Docker路径。

内容的提问来源于stack exchange，提问作者Orange Lux