Jenkins Pipeline中writeFile()无法序列化字符串路径的问题

核心原因分析 #

• Jenkins流水线序列化机制限制
  Jenkins流水线依赖Groovy CPS引擎实现断点续跑，会对流水线上下文的所有对象执行序列化。sun.nio.fs.UnixPath是Java NIO的路径对象，未实现Serializable接口，只要上下文存在该对象引用，就会触发序列化异常。

• 路径类型的隐式转换
  你确认传入的是字符串路径，但实际出现UnixPath，大概率是代码中存在隐式转换：比如用Paths.get()、new File(xxx).toPath()将字符串转为Path对象，且该Path对象被保留在流水线的全局变量或上下文里——即使你给writeFile传的是字符串，只要上下文有UnixPath引用，序列化时就会被扫描到报错。

• @NonCPS注解的误用
  添加@NonCPS后出现方法匹配错误，是因为@NonCPS方法禁止调用Jenkins内置的CPS方法（writeFile()属于CPS方法），强行调用会导致方法签名不兼容，自然无法执行。

• 主流水线代码报错的本质
  主流水线同样受CPS引擎管控，只要代码执行中生成了UnixPath对象并保存在变量中（哪怕后续没用到），序列化时都会触发异常，和是否提取为方法无关。

排查与修复提示 #

• 扫描所有路径相关代码，移除任何将字符串转为Path对象的操作，或在使用后立即丢弃Path对象引用，不要赋值给全局变量。
• 若必须使用Path对象，务必在传入writeFile前显式调用toString()转为字符串，比如：writeFile(file: pathObj.toString(), text: playbookContent)。
• 拆分@NonCPS方法逻辑：将纯Java/Groovy的非序列化操作（比如读取共享库文件内容）放在@NonCPS方法中，而调用writeFile()的CPS操作放在普通流水线代码块里，避免两者混合。
• 检查流水线变量，确保没有意外保留UnixPath或其他非序列化对象的引用。

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