BitBucket Pipeline安装本地TGZ包时完整性检查失败求助

问题配置 #

• 客户端项目位于client/目录，依赖同一仓库内的本地tgz包@company/my-library，包文件路径为local-packages/company-my-library-2.0.0.tgz
• package.json中依赖配置："@company/my-library": "file:../local-packages/company-my-library-2.0.0.tgz"

报错信息 #

npm warn tarball tarball data for @company/my-library@file:/opt/atlassian/pipelines/agent/build/local-packages/company-my-library-2.0.0.tgz (sha512-[Same-As-Package-Lock]) seems to be corrupted. Trying again.
npm warn tar TAR_BAD_ARCHIVE: Unrecognized archive format
npm error code EINTEGRITY
npm error sha512-[Same-As-Package-Lock] integrity checksum failed when using sha512: wanted sha512-[Same-As-Package-Lock] but got sha512-[Another-Checksum]. (131 bytes)

已排查操作 #

• 在Windows及WSL Ubuntu开发环境中卸载重装本地包，执行npm cache clean --force后，package-lock.json中的校验和始终一致
• 开发环境与Pipeline环境的Node.js、npm版本基本匹配：

原因分析 #

1. Git换行符转换破坏二进制文件：Windows环境下生成的tgz包，Git默认可能将其当作文本文件处理，自动转换换行符，导致包结构损坏，Pipeline拉取后无法识别为合法归档。
2. Git LFS未配置导致文件被替换为指针：若tgz包体积较大，未启用Git LFS的情况下，Git会将二进制文件替换为约131字节的文本指针，与报错中提到的文件大小吻合，npm读取指针文件自然无法解析。
3. Pipeline路径或权限异常：Pipeline执行环境中，相对路径解析错误，或者文件权限不足，导致npm读取的不是完整的tgz包文件。

解决方案 #

• 禁止Git转换tgz文件格式：在仓库根目录创建.gitattributes文件，添加规则：

  *.tgz binary
  

  提交该文件并推送仓库，强制Git将所有tgz文件视为二进制文件，避免格式转换。
• 启用Git LFS跟踪tgz文件：
  执行以下命令配置LFS：

  git lfs track "*.tgz"
  git add .gitattributes
  git add local-packages/company-my-library-2.0.0.tgz
  git commit -m "Track tgz packages with Git LFS"
  git push
  

  同时确保BitBucket仓库已在设置中启用LFS功能。
• 验证Pipeline中文件完整性：在Pipeline的npm install步骤前添加校验命令，确认文件是否完整：

  # 查看文件大小
  ls -lh ../local-packages/company-my-library-2.0.0.tgz
  # 计算校验和并与开发环境对比
  sha512sum ../local-packages/company-my-library-2.0.0.tgz
  

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