含斜杠的分支名导致Jenkins多分支Pipeline构建失败

问题背景 #

使用Git Plugin的Jenkins多分支Pipeline时，分支名如feature/PROJECT-123-add-feature-x会被Jenkins将/替换为%2F生成工作区路径，例如F:\j\workspace\project\reponame\feature%2FPROJECT-123-add-feature-x。执行nuget pack时，NuGet会将%2F解码为反斜杠\，导致路径解析错误，出现类似以下报错：

CSC : error CS0006: Metadata file 'F:\j\workspace\project\reponame\feature\project-123-add-feature-x\packages\Lib.1.1.0\lib\net45\Lib.dll' could not be found [F:\j\workspace\project\reponame\feature%2FFSLTDK-123-add-feature-x\project_name.csproj]

问题解答 #

1. 能否配置Git插件将分支名的/转换为%2F以外的字符（如-）？ #

可以，有两种可行方式：

• Multibranch Pipeline配置层面：在Jenkins的Multibranch Pipeline项目配置中，找到「Branch Sources」下的Git源，点击「Advanced」展开高级设置，在「Name mapping」中使用正则表达式替换。例如输入正则匹配式(.*)/(.*)，替换为$1-$2，即可将分支名中的斜杠替换为横杠，工作区文件夹名会变成feature-PROJECT-123-add-feature-x。
• Pipeline脚本层面：在Jenkinsfile中手动指定自定义工作区路径，通过字符串替换将分支名里的/替换为-，示例代码如下：

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                ws("${JENKINS_HOME}/workspace/${JOB_NAME}/${BRANCH_NAME.replace('/', '-')}") {
                    // 执行拉取代码、nuget pack等操作
                    sh 'git pull'
                    sh 'nuget pack project_name.csproj'
                }
            }
        }
    }
}

2. 能否阻止用户创建含/的分支名？Jira默认生成bugfix/xyz这类分支名。 #

可以通过Git服务器钩子阻止，但需要考虑与Jira的兼容性：

• Git服务器端钩子：在Git服务器的仓库中添加pre-receive钩子脚本，检查推送的分支名，若包含/则拒绝推送。脚本示例（bash）：

#!/bin/bash
while read oldrev newrev refname; do
    branch=$(git rev-parse --symbolic --abbrev-ref $refname)
    if [[ "$branch" == *"/"* ]]; then
        echo "Error: Branch names cannot contain slashes."
        exit 1
    fi
done
exit 0

但这种方式会和Jira默认的分支命名模板冲突，更合理的做法是修改Jira的分支生成规则：在Jira项目的「Settings」→「Branching models」中，调整分支命名模板，将bugfix/${issue.key}改为bugfix-${issue.key}，让Jira生成不带斜杠的分支名。

3. 还有其他可行的解决办法吗？ #

除上述方案外，还有以下几种思路：

• 切换Jenkins工作区到Linux系统：Linux系统允许路径中包含/，Jenkins不会将其编码为%2F，从根源避免NuGet解码错误的问题。
• 使用Docker容器构建：在Pipeline中使用Docker代理，构建过程在容器内部进行，容器内的路径为Linux风格，不会出现Windows路径的编码问题，且可以隔离不同分支的构建环境。
• 修改NuGet配置或构建脚本：在执行nuget pack前，通过脚本临时修改csproj文件中的引用路径，将可能被错误解码的路径替换为实际工作区路径，但这种方式维护成本较高，不如前两种方案可靠。

内容的提问来源于stack exchange，提问作者J. Moutray