GitLab CI流水线中sphinx-build命令找不到（Python3 Alpine镜像）

这个问题确实和你使用的Alpine Linux镜像有关，核心原因是Alpine的Python环境中，pip安装的可执行文件路径可能不在默认的PATH环境变量里，或者pip的安装行为和常规Linux发行版（比如Ubuntu）有差异。下面给你几个可行的解决方案：

方案1：用Python模块方式调用Sphinx（最可靠） #

不需要依赖sphinx-build脚本的PATH配置，直接通过Python模块运行Sphinx，这是跨环境最稳定的方式：

pages:
  stage: build
  tags:
    - buildtag
  script:
    - pip install -U sphinx
    - python -m sphinx -b html docs/ public/
  only:
    - master

python -m sphinx会直接调用Sphinx的核心模块，绕开了脚本路径的问题，几乎在所有Python环境下都能正常工作。

方案2：显式指定sphinx-build的路径 #

在Alpine镜像中，pip全局安装的sphinx-build通常位于/usr/local/bin目录，你可以直接用绝对路径调用它：

script:
  - pip install -U sphinx
  - /usr/local/bin/sphinx-build -b html docs/ public/

方案3：将pip安装目录加入PATH #

如果想继续用sphinx-build命令，可以先把pip的安装目录添加到环境变量PATH中：

script:
  - export PATH="$PATH:/usr/local/bin"
  - pip install -U sphinx
  - sphinx-build -b html docs/ public/

方案4：用Alpine的包管理器安装Sphinx（推荐用于Alpine环境） #

Alpine自带的包管理器apk有预编译的Sphinx包，用它安装比pip更符合Alpine的生态，也能避免路径问题：

script:
  - apk add --no-cache py3-sphinx
  - sphinx-build -b html docs/ public/

--no-cache参数是为了减少镜像体积，符合Alpine精简的特点。

为什么Alpine会出现这个问题？ #

Alpine Linux为了极致精简，默认的PATH配置可能没有包含pip全局安装可执行文件的/usr/local/bin（虽然大部分情况下是包含的，但GitLab CI的环境可能有特殊配置）；另外，Alpine的Python是基于musl libc构建的，和常规glibc发行版的pip行为略有差异，导致脚本路径可能没有被正确识别。

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