GitHub Actions无法上传node_modules/.bin目录至工件的问题

我使用GitHub Workflow安装依赖并构建Next.js应用，但上传工件后发现node_modules下的.bin目录缺失。在自托管运行器上安装依赖后，.bin目录确实存在，日志也能查到该目录，但下载工件压缩包后找不到它；单独上传node_modules/.bin时，还会提示路径不存在。后来发现.bin目录里全是指向实际二进制文件的软链接，这是不是导致无法上传的原因？

我的工作流文件 #

name: build-application

on:
  push:
    branches:
      - '*'
  pull_request:
    branches:
      - '*'

jobs:
  build:
    runs-on: self-hosted
    strategy:
      matrix:
        node-version: [22.x]
    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - name: 📥 Install dependecies; 🏗️ Build code
      run: |
        npm ci
        npm run build --if-present
        #npm test
        echo "🎉  The build was successfully completed!"
    - name: List node_modules contents
      run: | 
        ls -al node_modules | grep .bin
        pwd
    - name: Upload Build Artifacts
      uses: actions/upload-artifact@v4
      with:
        name: nextjs-build
        path: |
          .next
          public
          package.json
          next.config.js
          node_modules

日志显示.bin目录存在 #

Run ls -al node_modules | grep .bin
drwxr-xr-x   2 ubuntu ubuntu   4096 Jan 24 20:18 .bin
drwxr-xr-x   2 ubuntu ubuntu   4096 Jan 24 20:17 binary-extensions
drwxr-xr-x   4 ubuntu ubuntu   4096 Jan 24 20:17 call-bind
drwxr-xr-x   3 ubuntu ubuntu   4096 Jan 24 20:17 combined-stream
drwxr-xr-x   4 ubuntu ubuntu   4096 Jan 24 20:17 function-bind
drwxr-xr-x   2 ubuntu ubuntu   4096 Jan 24 20:17 is-binary-path

单独上传.bin的错误提示 #

Warning: No files were found with the provided path:
node_modules/.bin. No artifacts will be uploaded.

.bin目录内的软链接详情 #

ls -al node_modules/.bin/
total 16
drwxr-xr-x   2 ubuntu ubuntu  4096 Jan 24 20:30 .
drwxr-xr-x 338 ubuntu ubuntu 12288 Jan 24 20:30 ..
lrwxrwxrwx   1 ubuntu ubuntu    18 Jan 24 20:30 acorn -> ../acorn/bin/acorn
lrwxrwxrwx   1 ubuntu ubuntu    32 Jan 24 20:30 autoprefixer -> ../autoprefixer/bin/autoprefixer
lrwxrwxrwx   1 ubuntu ubuntu    22 Jan 24 20:30 browserslist -> ../browserslist/cli.js
lrwxrwxrwx   1 ubuntu ubuntu    20 Jan 24 20:30 cssesc -> ../cssesc/bin/cssesc
lrwxrwxrwx   1 ubuntu ubuntu    23 Jan 24 20:30 eslint -> ../eslint/bin/eslint.js
lrwxrwxrwx   1 ubuntu ubuntu    19 Jan 24 20:30 jiti -> ../jiti/bin/jiti.js
lrwxrwxrwx   1 ubuntu ubuntu    19 Jan 24 20:30 json5 -> ../json5/lib/cli.js
lrwxrwxrwx   1 ubuntu ubuntu    25 Jan 24 20:30 js-yaml -> ../js-yaml/bin/js-yaml.js
lrwxrwxrwx   1 ubuntu ubuntu    22 Jan 24 20:30 loose-envify -> ../loose-envify/cli.js
lrwxrwxrwx   1 ubuntu ubuntu    24 Jan 24 20:30 nanoid -> ../nanoid/bin/nanoid.cjs
lrwxrwxrwx   1 ubuntu ubuntu    21 Jan 24 20:30 next -> ../next/dist/bin/next
lrwxrwxrwx   1 ubuntu ubuntu    23 Jan 24 20:30 node-which -> ../which/bin/node-which
lrwxrwxrwx   1 ubuntu ubuntu    28 Jan 24 20:30 prettier -> ../prettier/bin/prettier.cjs
lrwxrwxrwx   1 ubuntu ubuntu    22 Jan 24 20:30 resolve -> ../resolve/bin/resolve
lrwxrwxrwx   1 ubuntu ubuntu    16 Jan 24 20:30 rimraf -> ../rimraf/bin.js
lrwxrwxrwx   1 ubuntu ubuntu    23 Jan 24 20:30 semver -> ../semver/bin/semver.js
lrwxrwxrwx   1 ubuntu ubuntu    22 Jan 24 20:30 sucrase -> ../sucrase/bin/sucrase
lrwxrwxrwx   1 ubuntu ubuntu    27 Jan 24 20:30 sucrase-node -> ../sucrase/bin/sucrase-node
lrwxrwxrwx   1 ubuntu ubuntu    25 Jan 24 20:30 tailwind -> ../tailwindcss/lib/cli.js
lrwxrwxrwx   1 ubuntu ubuntu    25 Jan 24 20:30 tailwindcss -> ../tailwindcss/lib/cli.js
lrwxrwxrwx   1 ubuntu ubuntu    21 Jan 24 20:30 tsc -> ../typescript/bin/tsc
lrwxrwxrwx   1 ubuntu ubuntu    26 Jan 24 20:30 tsserver -> ../typescript/bin/tsserver
lrwxrwxrwx   1 ubuntu ubuntu    32 Jan 24 20:30 update-browserslist-db -> ../update-browserslist-db/cli.js

原因确认 #

没错，问题根源就是软链接。actions/upload-artifact@v4默认不处理符号链接：它既不会跟随软链接指向的实际文件，也不会把软链接本身作为文件上传。由于.bin目录里全是软链接、没有实际文件内容，工具会判定该目录为空，因此不会将其包含在工件中；单独指定上传该目录时，就会提示路径不存在。

方案1：推荐 - 在CD阶段重新安装依赖 #

这是更合理的实践，原因有两点：

1. 上传整个node_modules体积庞大，会大幅拖慢工件上传/下载速度；
2. 自托管运行器的环境和部署服务器的环境可能存在差异（比如系统架构、Node.js版本细节），直接复用构建阶段的node_modules可能引发兼容性问题。

修改CD流程，在部署服务器上执行：

npm ci --only=production

这会重新生成适配部署环境的node_modules及对应的.bin目录，完全规避软链接问题。

方案2：强制打包软链接（仅当必须复用构建产物时） #

如果一定要在构建阶段打包包含.bin的node_modules，可以用tar命令打包时跟随软链接，将软链接转换成实际文件后再上传压缩包：

修改工作流中的上传步骤：

- name: 打包node_modules（解析软链接）
  run: tar -chzf node_modules.tgz node_modules
- name: Upload Build Artifacts
  uses: actions/upload-artifact@v4
  with:
    name: nextjs-build
    path: |
      .next
      public
      package.json
      next.config.js
      node_modules.tgz

然后在部署阶段解压：

tar -xzf node_modules.tgz

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