企业官网建设流程全解析

三条命令跑通本地 .gitlab-ci.yml：gitlab-ci-local 实战教程

【免费下载链接】gitlab-ci-localTired of pushing to test your .gitlab-ci.yml?项目地址: https://gitcode.com/GitHub_Trending/gi/gitlab-ci-local

改一行.gitlab-ci.yml，commit、push、等 GitLab 排队拉镜像，结果发现只是变量名写错——这种循环你可以不再走。gitlab-ci-local 是一个用 TypeScript 编写的 CLI 工具，把 GitLab CI 流水线完整拉到本地执行：shell 执行器或 Docker 执行器，按 stages 和 needs 依次跑完所有 job，全程不需要推送代码。下面从安装讲起，再拆解几个真正省时间的用法。

📦 装好并跑通第一条本地流水线

装好工具只需要一条命令，npm、Bun、Homebrew、Debian 源都可以，任选其一：

npm install -g gitlab-ci-local

装完之后，进入任意一个根目录带有.gitlab-ci.yml的 Git 仓库，直接裸跑：

gitlab-ci-local

预期效果：工具解析配置文件，按阶段依赖把 job 逐个跑起来，Docker job 会拉取image指定的镜像并挂载源码，每个 job 结束后打印PASS、WARN或FAIL，最后一行汇总pipeline finished的总耗时。跑通了，后面所有配置改动都可以原地验证。顺手加个别名，后面敲起来舒服很多：

echo "alias gcl='gitlab-ci-local'" >> ~/.bashrc

🔍 五个值得先知道的功能点

用--list先看清楚流水线会执行什么

gitlab-ci-local --list不执行任何 job，只输出一张表格：job 名、stage、when、allow_failure、needs 依赖一目了然，when: never的 job 会被过滤掉。改完配置先扫一眼这张表，比 push 之后看 GitLab 页面快得多；加--list-all能看到被隐藏的 never job，--list-csv则输出可直接处理的结构化格式。

指定 job 名，只跑其中一步

调试时不必每次跑完整条流水线。gitlab-ci-local docker-compose-down这样直接把 job 名跟在后面，就只执行这一个 job——它特别适合验证某个部署脚本或手动触发的任务，不用陪跑前面所有依赖。

三级变量文件，敏感信息不进仓库

变量按作用域分层存放：项目根目录的.gitlab-ci-local-variables.yml是默认位置（支持 YAML 和.env两种格式），$HOME/.gitlab-ci-local/variables.yml可以按项目或组匹配 remote 地址注入变量，--remote-variables还能从别的 Git 仓库拉取变量文件。项目级的写法很简单：

--- AUTHORIZATION_PASSWORD: djwqiod910321 KNOWN_HOSTS: '~/.ssh/known_hosts' # 值是文件路径时自动成为 File 类型变量

记得把这个文件写进.gitignore，它和 GitLab 控制台的变量功能语义一致，只是换到了本地。

只在本地跑的 job，和@Interactive调试器

本地执行时GITLAB_CI恒为false，靠它就能写"只在本机存在"的 job，比如开一个交互式 shell 进容器排查问题：

# @Interactive debug-container: rules: - { if: $GITLAB_CI == 'false' } when: manual script: - docker run -it debian bash

@Interactive装饰器会让这个手动 job 在你的终端里前台交互执行；类似的# @Description注释行会出现在--list的描述列里，@NoArtifactsToSource可以阻止某个 job 的 artifacts 拷回源码目录。

shell 与 Docker 双执行器，artifacts 照常传递

没有声明image的 job 走 shell 执行器，声明了的走 Docker 执行器，两者混用没问题。artifacts 的传递和 GitLab 行为对齐：Docker 执行器之间经由.gitlab-ci-local/artifacts目录交接，shell 执行器则直接拷回主机工作目录，所以像npm install产出的node_modules能被下游 job 正常消费。

🎯 什么时候用它最划算

复杂多阶段流水线的本地联调。仓库自带的 examples/docker-compose-nodejs 是典型场景：npm-install装依赖并产出 artifacts，npm-audit查安全漏洞，npm-outdated查过期依赖，最后docker-compose-up用 compose 起 webserver，四步之间靠 artifacts 和 needs 串起来。

gitlab-ci-local --cwd examples/docker-compose-nodejs/

跑起来的效果和 GitLab 上看到的日志几乎一致，四个 job 依次输出后给出汇总：

改动 rules、include、matrix 之后验证。这类改动最容易影响"哪些 job 会被创建"，本地--list加--list-all一眼就能对比改动前后的 job 清单。注意外部 include（project/remote）默认只拉取一次并缓存，怀疑版本过旧时加--fetch-includes强制刷新。

CI/CD 组件（components）模板开发。工具的输入校验是内置的：inputs 的 type、options、正则默认都会验证，遇到旧组件声明的类型和默认值对不上时，可用--skip-input-validation跳过类型检查继续渲染流水线，required 输入仍会校验。

⚙️ 环境变量、配置项与常见坑

常用开关都能用GCL_前缀的环境变量固化，不必每次敲参数：

另外三件容易踩的事：只有 git 已跟踪（tracked）的文件会同步进隔离 job，新文件记得git add；自托管 GitLab 如果用了非标端口，需要在变量文件里手动补CI_SERVER_PORT；Docker 相关的测试行为可以参考 tests/test-cases/ 下 150 多个集成用例，配置解析与执行流程的实现分别在 src/parser.ts 和 src/executor.ts。

✅ 开始之前的几条建议

1. 第一句就养成习惯：改完配置先gitlab-ci-local --list，确认 job 清单再全量跑。
2. 把.gitlab-ci-local-variables.yml加入.gitignore，敏感变量永远不进版本库。
3. 调试单个 job 时直接用 job 名做参数，别整条流水线陪跑。
4. 用@Description给关键 job 写一句话说明，--list的输出会立刻可读很多。
5. 工具更新比较频繁，隔一段时间执行一次npm update -g gitlab-ci-local，新版本的 GitLab 特性支持基本都靠它跟进。

想深入了解解析和执行的内部机制，src/ 目录下每个模块都有对应职责，配合 README 的 Quirks 一节，足够你把它用得顺手。

【免费下载链接】gitlab-ci-localTired of pushing to test your .gitlab-ci.yml?项目地址: https://gitcode.com/GitHub_Trending/gi/gitlab-ci-local