Bitbucket CI写入Commit SHA至文件后推送失败及静态资源版本化问询

一、Git推送权限错误的解决 #

你遇到的Permission denied和pre-receive hook declined问题，核心原因有两个：

• CI默认凭据权限不足：多数CI平台的内置令牌只有仓库只读权限，无法直接推送到受保护的主分支。解决办法是换成个人访问令牌（PAT），给令牌开启仓库读写权限，再在CI变量中配置该令牌作为推送凭据。
• 分支保护规则拦截：如果master分支设置了保护（比如要求必须通过合并请求提交），直接推送会被仓库钩子拦截。这种情况要么临时调整分支保护规则（不推荐生产环境使用），要么干脆放弃往主分支提交version.txt——实际上完全没必要把这个文件提交回仓库，后面的优化方案会说明原因。

二、更高效的静态资源版本化方案 #

你当前生成version.txt再提交的思路，不仅有权限问题，还会增加仓库提交记录的冗余。推荐几种更高效的实现方式，不用修改仓库也无需每次请求计算哈希：

1. 构建时给静态文件加哈希后缀（最推荐） #

直接把Git Commit Hash嵌入到静态文件名中，比如将style.css改成style.abc12345.css。浏览器会把不同文件名的资源视为全新文件缓存，彻底不需要?v=参数。
示例CI构建阶段的shell脚本：

# 给dist目录下的CSS/JS文件添加短哈希后缀（取SHA前8位）
for file in dist/*.css dist/*.js; do
  if [ -f "$file" ]; then
    short_sha=${CI_COMMIT_SHA:0:8}
    new_file="${file%.*}.${short_sha}.${file##*.}"
    mv "$file" "$new_file"
    # 同步替换HTML里的资源引用路径
    sed -i "s/$(basename "$file")/$(basename "$new_file")/" dist/index.html
  fi
done

如果用Webpack、Vite这类专业构建工具，它们自带文件名哈希功能，只需在配置中开启即可自动生成带哈希的文件名并替换引用，比如Vite的build.rollupOptions.output.assetFileNames配置项。

2. 直接在构建时注入版本变量 #

不用生成version.txt，直接将CI_COMMIT_SHA注入到代码或HTML模板里：

• 用模板引擎的话，在HTML模板中写：<link rel="stylesheet" href="/style.css?v={{ commit_sha }}">，构建时把{{ commit_sha }}替换为CI_COMMIT_SHA的值。
• 用前端构建工具的话，比如Webpack可以通过DefinePlugin把版本号注入成全局变量：

const webpack = require('webpack');
module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'VERSION': JSON.stringify(process.env.CI_COMMIT_SHA)
    })
  ]
};

之后在JS中直接用VERSION变量拼接资源URL：const cssUrl = /style.css?v=${VERSION};

3. 用Git标签作为版本号 #

如果不需要每次提交都更新版本，用Git标签（比如v1.2.3）作为版本后缀，比随机字符串更有意义，也方便问题追溯。CI里可以通过CI_COMMIT_TAG变量获取当前标签，用它替换版本号即可。

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