如何在CircleCI构建脚本中正确使用外部shell脚本？

云上老周

2026-5-12

在CircleCI Orb中引入外部Shell脚本的最佳实践？

我正在尝试把CircleCI配置里的一些重复步骤封装成Orb复用，但遇到个棘手的问题——我的foo.sh脚本没法直接打包进Orb里，想找个“正确”的方式把这类外部脚本纳入构建流程。先给大家看看我的基础配置：

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/ruby:2.5.3-node-browsers
    steps:
      - checkout
      - run:
          name: Compute some value
          command: |
            SOME_VALUE=$(foo.sh)
      - run:
          name: Reuse some value
          command: |
            echo "Hello" > /a/path/${SOME_VALUE}.txt

我已经琢磨过几个办法，但都不太满意：

翻了CircleCI的官方文档，确实没法把foo.sh这类脚本直接作为Orb的一部分打包进去。
基于官方镜像重新构建一个包含脚本的Docker镜像——但脚本和镜像本身完全无关，感觉是硬把Docker当文件传输工具用，有点别扭。
从公共URL用wget下载脚本临时执行——这种方式风险太高了，要是URL输错或者被恶意篡改，执行未知脚本简直是埋雷。
把存脚本的Git仓库克隆到构建容器里——比下载的方式靠谱点，但总觉得不是最优雅的解法。

有没有我没想到的思路或者行业最佳实践？

推荐的几种靠谱方案

1. 直接把脚本内容内嵌到Orb的Command里

如果你的foo.sh代码不长，最省心的办法就是直接把脚本内容写到Orb的command定义里，用HEREDOC的方式注入进去。这样脚本就和Orb绑定在一起，完全不需要外部依赖。比如Orb里可以这么写：

commands:
  compute-some-value:
    parameters:
      param1:
        type: string
        default: "default-value"
    steps:
      - run:
          name: Compute some value
          command: |
            # 这里直接复制foo.sh的全部内容
            #!/bin/bash
            echo "<< parameters.param1 >>-calculated-value"

调用Orb的时候，直接执行这个command就行，相当于把脚本内容直接放到构建步骤里，完美解决Orb不能打包文件的问题。

2. 用CircleCI Workspace传递脚本（多Job场景适用）

如果脚本必须是独立文件，而且你的构建流程有多个Job，可以在初始化Job里把脚本拉取到容器，然后保存到CircleCI的Workspace中，后续Job直接从Workspace读取使用。比如：

jobs:
  setup-scripts:
    docker:
      - image: circleci/ruby:2.5.3-node-browsers
    steps:
      - checkout # 如果脚本在当前代码仓库里
      - persist_to_workspace:
          root: .
          paths:
            - foo.sh
  build:
    docker:
      - image: circleci/ruby:2.5.3-node-browsers
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Compute some value
          command: |
            SOME_VALUE=$(./foo.sh)

这种方式如果脚本在你的私有代码仓库里，安全性有保障，而且Workspace是CircleCI内部的存储机制，不会有公共下载的风险。

3. 从私有Git仓库拉取单个脚本（带SSH认证）

如果脚本在私有Git仓库里维护，不想克隆整个仓库，可以用git archive配合SSH只拉取需要的脚本文件：

git archive --remote=git@your-private-repo.com:scripts/repo.git HEAD foo.sh | tar -x

这种方式只拉取单个文件，效率更高，而且用SSH认证，只有你的构建容器能访问私有仓库，安全性拉满。记得把SSH密钥存在CircleCI的环境变量里，构建的时候自动加载就行。

4. 用CircleCI Cache缓存脚本（适合不常更新的脚本）

如果你的脚本不经常变动，可以第一次拉取后缓存起来，后续构建直接用缓存，减少重复操作：

- restore_cache:
    keys:
      - scripts-v1-{{ checksum "foo.sh" }}
- run:
    name: Fetch scripts if not cached
    command: |
      if [ ! -f foo.sh ]; then
        git clone git@your-private-repo.com:scripts/repo.git && cp repo/foo.sh .
      fi
- save_cache:
    key: scripts-v1-{{ checksum "foo.sh" }}
    paths:
      - foo.sh

这样既保证了脚本的安全性，又能提升构建速度，一举两得。

其实没有绝对的“最佳”方案，要看你的具体场景：

如果脚本代码短，优先选内嵌到Orb的方式，最省心也最直接。
如果脚本需要独立维护或者代码较长，私有仓库拉取+SSH认证是安全性和灵活性兼顾的选择。
多Job共享脚本的话，Workspace是最适合的方案。

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