开源项目中如何阻止package.json版本未升级时合并到master分支

方案1：使用GitHub Actions（仓库级约束，推荐） #

这是最可靠的方式，运行在GitHub服务器端，所有PR合并都会触发检查，不受协作者本地环境影响，能彻底拦截不符合要求的合并。

1. 在仓库根目录创建.github/workflows/check-version.yml文件，内容如下：

name: Check Package Version
on:
  pull_request:
    branches: [ master ]

jobs:
  check-version:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 拉取完整历史，确保能对比master分支

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install version comparison tool
        run: npm install semver --global

      - name: Compare package.json versions
        run: |
          # 获取master分支的package.json版本
          BASE_VERSION=$(git show origin/master:package.json | jq -r '.version')
          # 获取当前PR分支的package.json版本
          HEAD_VERSION=$(jq -r '.version' package.json)
          
          # 检查PR分支版本是否高于master，否则报错终止流程
          semver -r ">$BASE_VERSION" "$HEAD_VERSION" || {
            echo "错误：package.json版本($HEAD_VERSION)必须高于master分支版本($BASE_VERSION)"
            exit 1
          }

2. 仓库设置：在GitHub仓库的「Settings」→「Branches」里，给master分支开启「Require status checks to pass before merging」，并把上面创建的Check Package Version工作流添加进去。这样所有未升级版本的PR都会被拦截。

方案2：共享客户端钩子（本地辅助约束） #

客户端钩子能在本地合并/提交时提前检查，但需要协作者手动安装，可作为GitHub Actions的补充。

1. 在仓库根目录创建hooks/pre-merge-commit脚本：

#!/bin/bash

# 仅在合并到master分支时触发检查
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$CURRENT_BRANCH" != "master" ]; then
  exit 0
fi

# 获取待合并分支和master的版本号
MERGE_BRANCH=$(git rev-parse --abbrev-ref MERGE_HEAD)
HEAD_VERSION=$(git show "$MERGE_BRANCH":package.json | jq -r '.version')
BASE_VERSION=$(git show master:package.json | jq -r '.version')

# 自动安装semver（如果未安装）
if ! command -v semver &> /dev/null; then
  echo "正在安装semver版本对比工具..."
  npm install semver --global
fi

# 对比版本，不满足则阻止合并
semver -r ">$BASE_VERSION" "$HEAD_VERSION" || {
  echo "ERROR：待合并分支的package.json版本($HEAD_VERSION)必须高于master版本($BASE_VERSION)"
  exit 1
}

2. 创建setup-hooks.sh安装脚本：

#!/bin/bash

# 复制钩子到git钩子目录
cp hooks/pre-merge-commit .git/hooks/
# 添加执行权限
chmod +x .git/hooks/pre-merge-commit

echo "客户端合并钩子已安装完成"

3. 将hooks/目录和setup-hooks.sh提交到仓库，通知协作者克隆仓库后运行./setup-hooks.sh完成钩子安装。

关于钩子类型的说明 #

• pre-merge-commit是客户端钩子，仅在本地执行git merge时触发，能拦截本地合并到master的操作，但无法约束GitHub上的PR合并，因此必须配合GitHub Actions使用。
• GitHub不支持自定义服务端钩子，官方推荐用GitHub Actions实现仓库级别的合并拦截逻辑。

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