Jenkins多阶段流水线捕获制品时出错，请求技术协助

Hey there! 刚接触Jenkins流水线确实容易踩坑，尤其是制品捕获这块——多阶段架构下阶段间的上下文、权限、路径配置稍不注意就会出问题。我整理了多阶段流水线中捕获制品时最常遇到的几类问题及对应的解决办法，你可以对照排查：

1. 阶段间工件无法传递 #

• 问题原因：多阶段流水线默认每个阶段在独立的执行环境（比如不同容器或节点）中运行，前一阶段生成的文件不会自动带到后续阶段。
• 修复方法：使用stash和unstash步骤在阶段间共享文件，或者配置统一的agent让所有阶段在同一个节点/容器运行。示例代码：

  stage('Build') {
    agent any
    steps {
      sh 'npm run build'
      // 暂存构建产物
      stash includes: 'dist/**/*', name: 'build-artifacts'
    }
  }
  stage('Capture Artifact') {
    agent any
    steps {
      // 取出暂存的产物
      unstash 'build-artifacts'
      // 归档制品
      archiveArtifacts artifacts: 'dist/**/*', fingerprint: true
    }
  }
  

2. 制品路径配置错误 #

• 问题原因：指定的制品路径不存在、相对路径基准错误（比如阶段的工作目录不同），或者使用了绝对路径导致跨节点无法访问。
• 修复方法：
  • 优先使用相对路径，确保路径相对于当前阶段的工作空间；
  • 在阶段中添加sh 'pwd'和sh 'ls -la'命令，确认当前目录下的文件结构；
  • 如果是容器环境，检查容器内的工作目录配置是否和预期一致。

3. 权限不足无法读取/归档制品 #

• 问题原因：Jenkins执行用户对生成的制品文件没有读取权限，或者归档目录没有写入权限。
• 修复方法：
  • 在生成制品后添加权限修改步骤，比如sh 'chmod -R 755 dist/'；
  • 检查Jenkins agent的运行用户权限，确保其能访问目标文件和归档目录。

4. archiveArtifacts参数使用错误 #

• 问题原因：通配符使用不当、fingerprint配置冲突，或者遗漏了必要参数（比如onlyIfSuccessful）。
• 修复方法：
  • 通配符要匹配实际文件结构，比如用**/*.jar匹配所有子目录下的jar包；
  • 避免使用绝对路径，保持参数简洁，示例：

    archiveArtifacts artifacts: '**/*.war', fingerprint: true, onlyIfSuccessful: true
    

5. 多代理环境下的制品丢失 #

• 问题原因：如果阶段使用了不同的agent（比如一个用Docker，一个用本地节点），stash/unstash可能因为环境差异导致文件丢失。
• 修复方法：
  • 尽量让涉及制品处理的阶段使用同一个agent；
  • 如果必须跨agent，确保stash的文件不包含系统特定的文件权限或符号链接，避免解压失败。

如果这些方案没覆盖到你的问题，麻烦提供你的流水线代码片段（尤其是捕获制品的阶段和之前的构建阶段）以及具体的错误日志，这样我能更精准地帮你定位问题~

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