GitLab Runner（Windows10）执行Python Setuptools构建失败：找不到kernel32.lib

在Windows10系统上恢复GitLab Runner流水线运行时，执行基于setuptools的Python项目构建命令，调用Visual Studio的link.exe时出现以下错误：

LINK : fatal error LNK1104: cannot open file 'kernel32.lib'

构建流程会生成部分文件，但在调用link.exe时立即失败。

已尝试的无效方案 #

• 将kernel32.lib路径传入setuptools的include_dirs（此前该方法解决过io.h找不到的问题）
• 在Visual Studio安装器中切换/仅保留单一版本Windows SDK
• 重新安装Visual Studio安装器，并在gitlab-runner的config.toml中配置相关路径
• 修改相关文件夹权限

异常现象 #

手动在PowerShell中执行GitLab Runner的shell命令（gitlab-runner shell: powershell）时构建完全正常，但通过GitLab流水线运行时必然失败；对比两者日志发现，流水线中link.exe的参数缺少kernel32.lib的路径。无论GitLab Runner以服务、管理员身份或普通PowerShell/CMD运行，结果一致。

解决方案建议 #

1. 显式加载Visual Studio环境变量 #

GitLab Runner的shell环境默认不会自动加载Visual Studio的环境变量，而手动执行PowerShell时可能已通过启动器或配置文件加载。在构建脚本开头添加以下命令，确保加载对应架构的VS环境：

针对Visual Studio 2022（Community版），执行：

& "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd.bat" -arch=x64

若使用其他版本或版本类型（如Professional），请调整路径中的版本和版本文字。

2. 配置setuptools的library_dirs参数 #

仅配置include_dirs不足以让setuptools找到链接库，需同时设置library_dirs指向kernel32.lib所在的Windows SDK目录：

from setuptools import setup

setup(
    # 其他项目配置
    include_dirs=["C:/Program Files (x86)/Windows Kits/10/Include/<你的SDK版本>/um"],
    library_dirs=["C:/Program Files (x86)/Windows Kits/10/Lib/<你的SDK版本>/um/x64"]
)

替换<你的SDK版本>为实际安装的版本号（如10.0.22621.0）。

3. 检查GitLab Runner服务的运行用户权限 #

若GitLab Runner以Windows服务运行，确保服务运行用户拥有访问Windows SDK目录（通常为C:\Program Files (x86)\Windows Kits\10\Lib\<SDK版本>\um\<架构>）的权限，且该用户的环境变量包含VS和Windows SDK的路径。

4. 在config.toml中配置全局环境变量 #

在gitlab-runner的config.toml文件中，为Runner添加包含VS和Windows SDK路径的环境变量：

[[runners]]
  name = "Windows Runner"
  url = "你的GitLab实例地址"
  token = "你的Runner令牌"
  executor = "shell"
  shell = "powershell"
  environment = [
    "INCLUDE=C:/Program Files (x86)/Windows Kits/10/Include/<你的SDK版本>/um;C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/<你的MSVC版本>/include",
    "LIB=C:/Program Files (x86)/Windows Kits/10/Lib/<你的SDK版本>/um/x64;C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/<你的MSVC版本>/lib/x64"
  ]

替换路径中的版本号为实际安装的对应版本。

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