升级GitHub Actions v4后部署Eleventy站点遇Artifact部署错误

问题分析 #

部署报错提示Artifact包含硬链接、软链接或总大小超10GB，结合配置和日志，核心排查方向集中在构建产物中的链接文件和产物大小——Eleventy默认构建不会生成超10GB的内容，优先排查链接问题。

排查与修复步骤 #

1. 检测构建产物中的软/硬链接 #

在build任务的run eleventy步骤后添加检查命令，确认是否存在违规链接：

- name: Check for symlinks/hard links in _site
  run: |
    echo "Checking for symlinks:"
    find ./_site -type l
    echo "Checking for hard links:"
    find ./_site -type f -links +1

运行后如果输出链接路径，说明构建产物中存在违规链接。

2. 定位链接来源并修复 #

• Eleventy配置问题：检查.eleventy.js，如果使用了copy插件或自定义复制逻辑，是否不小心复制了node_modules中的软链接（npm依赖常包含symlinks）。修改配置，排除依赖目录或确保复制实际文件而非链接。
• 自定义构建脚本问题：如果npm run build包含额外复制命令（如cp），检查是否使用了-l（硬链接）或-s（软链接）参数，替换为普通复制命令（如cp -r）。

3. 验证产物大小 #

添加命令确认_site目录总大小：

- name: Check _site directory size
  run: du -sh ./_site

如果大小接近或超过10GB，清理冗余文件（如未使用的静态资源、重复文件）。

4. 调整Artifact上传配置 #

显式添加参数确保文件被正确打包：

- name: upload static site content
  uses: actions/upload-artifact@v4
  with:
    path: ./_site
    name: github-pages
    if-no-files-found: error # 确保构建产物存在
    include-hidden-files: true # 包含隐藏文件（如.htaccess）

5. 确认部署权限与环境 #

你的配置中已正确设置permissions（pages: write和id-token: write），此步可跳过。

测试验证 #

修改Workflow后触发构建，观察是否仍报错。如果是链接问题，修复后部署即可成功。

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