Git跨服务器部署分支报错：无法切换远程work-tree路径

哦，这个坑我之前也踩过！Git的--work-tree参数只能识别本地文件系统路径，它没办法直接处理ssh-user@my-domain.com:/xxx这种远程SSH路径——毕竟Git本身是个本地工具，没法直接挂载远程文件系统来执行文件操作，这就是你报错的根源。

下面给你几个实用的解决方案，按推荐程度排序：

方案1：通过SSH在远程服务器上执行Git命令（最推荐） #

核心思路是把整个checkout操作放到远程服务器本地执行，本地只负责通过SSH触发这个命令。这样Git处理的都是远程服务器上的本地路径，自然就没问题了。

假设远程服务器上已经有你的Git裸仓库（就是你写的/user-root-dir/my-repository/my-repository.git），而且你要部署到远程的/user-root-dir/my-repository/target目录，那可以直接跑这条命令：

ssh ssh-user@my-domain.com "cd /user-root-dir/my-repository && git --work-tree=./target --git-dir=./my-repository.git checkout -f ."

• 注意：这里的--work-tree路径是远程服务器上的本地路径，不是SSH格式的！
• 如果远程还没有裸仓库，你可以先从本地推过去：git push ssh-user@my-domain.com:/user-root-dir/my-repository/my-repository.git main（替换成你的分支名）

方案2：用git archive打包后远程解压（适合轻量部署） #

如果不想在远程服务器上保留Git仓库，只是想把当前分支的文件部署过去，可以用git archive把代码打包，然后通过管道直接传到远程服务器解压。

命令如下：

git --git-dir=$GIT_DIR archive HEAD | ssh ssh-user@my-domain.com "cd /user-root-dir/my-repository && tar -x"

• 这个方法不需要远程安装Git（只要有tar就行），适合静态页面、纯文件的部署场景。
• HEAD可以替换成你要部署的分支名，比如main。

方案3：本地临时checkout后用rsync同步（适合需要预处理的场景） #

如果部署前需要在本地做一些文件修改、编译之类的预处理，可以先在本地临时目录checkout出代码，再用rsync同步到远程：

1. 本地临时checkout代码：

mkdir -p /tmp/git-deploy-temp
git --work-tree=/tmp/git-deploy-temp --git-dir=$GIT_DIR checkout -f .

2. 同步到远程服务器：

rsync -avz /tmp/git-deploy-temp/ ssh-user@my-domain.com:/user-root-dir/my-repository/

• -avz参数是保持文件权限、递归同步、压缩传输，适合大部分场景。

3. 清理本地临时目录：

rm -rf /tmp/git-deploy-temp

额外注意事项 #

• 确保ssh-user对远程的目标路径有读写权限，否则会报权限错误。
• 如果远程目标目录已有文件，checkout -f会强制覆盖，如果你需要保留某些文件，可以提前备份或者用git checkout的其他参数避免覆盖。

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