企业官网建设流程全解析

公司里一半人用Git用得上瘾，运维那边却咬死不放SVN——这种场景很多人都不陌生。最近我帮一个朋友做“Git仓库迁移至SVN仓库，并保留提交记录”的活儿，折腾了整整两天，中间还踩出了“迁移提交log失败”的幺蛾子。这篇笔记我把能复现的完整步骤、命令行、报错现象和排查思路全部摊开讲，尤其把“为什么log没保住”这件事翻个底朝天。不管你是负责代码合规迁移的运维，还是被逼着换版本管理工具的开发，这里面的坑你八成也会碰到。

1. 项目背景与需求拆解

1.1 为什么有人要从Git往SVN回迁

先别急着吐槽“都什么年代了还往SVN迁”。实际工作里，Git往SVN回迁的需求比想象中多。最常见的是企业内部统一代码库规范，某些传统部门要求所有项目统一进SVN，权限模型由管理员集中管控，开发人员只能拉取和提交；其次是客户或外包项目明确指定交付物必须走SVN，否则审计不过关；再一种情况是团队里除了研发还有测试、文档、美术，大家用非技术视角看版本管理，集中式SVN的checkout/update逻辑反而比Git的分支概念更容易普及。

Git完全分布式的特性在大型团队里当然好用，但在“强管控、弱技术背景、需要精确到目录授权”的场景下，SVN确实有它的历史惯性。回迁不是技术倒退，而是组织流程适应的结果。所以这个需求的核心不是“谁更好”，而是“如何让Git仓库里的历史资产完整地落到SVN服务器上，且能被追溯”。

1.2 “保留提交记录”的真实含义

迁移Git到SVN时，很多人以为“保留提交记录”就是把log里的提交说明复制过去，其实不是。SVN的提交历史是由一个个revision组成的，每个revision对应一次commit操作，包含提交人、提交时间、变更内容、日志说明。所谓保留提交记录，就是让原来Git的每次提交在SVN服务器上也变成一条提交记录，而不是整个仓库只导成一个快照。

要做到这点，核心工具不是svn import，而是Git自带的git svn。它的逻辑是：在本地维护一个和SVN仓库对应的Git分支（通常是refs/remotes/svn/trunk），然后通过git svn dcommit把本地提交推送到SVN，每推一条就生成一个SVN revision。反过来，SVN上的新提交也可以通过git svn rebase拉回来。这个机制是双向的，但坑也集中在方向上：Git历史可以任意非线性合并，SVN却严格要求线性递增，这一条就够迁移过程喝一壶的。

1.3 三条迁移路线怎么选

实际操作中，Git迁SVN有三条常见路线，我用一张表把差异讲清楚：

我的建议很直接：能走git svn就走git svn，虽然它有很多限制，但至少能把commit message和提交顺序保下来。我这次失败的恰恰是这个过程，下面会详细说。

2. SVN服务器侧的准备与建仓

2.1 建库与目录规划

迁移前先把SVN服务器准备好，我用的是Windows环境下的VisualSVN Server，社区版免费，三分钟能建好一个库。打开VisualSVN Server Manager，右键Repositories，选Create New Repository，输入仓库名比如legacy-project，注意勾选“Create standard structure (trunk/branches/tags)”。这个看似不起眼的勾选决定了后续git svn能不能用-s参数自动识别标准目录，强烈建议勾上。

如果你们用的是纯开源方案svnserve，建库命令是：

svnadmin create /data/svn/repos/legacy-project

然后在仓库根目录下手工创建目录结构：

cd /data/svn/repos/legacy-project mkdir -p trunk tags branches svn import /data/svn/repos/legacy-project file:///data/svn/repos/legacy-project -m "init structure"

svn import这一步会把空目录结构作为第一个revision提交掉，后面迁移时这个初始提交会成为Git与SVN的共同祖先锚点，非常重要。很多人在这一步偷懒，后面dcommit时就会遇到“祖先不是SVN的trunk”之类的报错。

2.2 用户与权限配置

建好库之后，配置用户权限。VisualSVN Server默认支持Windows账户，也可以创建SVN专用用户。我建议为迁移单独建一个迁移账号，比如svn_migrator，并给它仓库的读写下限（普通开发只读、迁移账号可写），这样发生误操作时能被权限兜住。

权限模型上，VisualSVN操作路径是：右键仓库 -> Properties -> Security，添加用户并设置Read/Write权限。如果后续推送时报“提示仓库不存在”，九成是权限问题——URL路径根本没权限访问，SVN给出来的提示十分误导人，它会说“Repository not found”，实际可能是认证失败，要先排查授权。

用svnserve的话，权限集中在conf/authz和conf/passwd两个文件里。authz至少要保证迁移账号对仓库根目录有读写权限，格式类似：

[legacy-project:/] svn_migrator = rw

2.3 服务器的常见故障

我迁移过程中顺手排查了几个高频问题，这里先列出来：

一是svn is not a working copy。这个报错多数是因为工作副本的.svn目录损坏，或者目录被其他工具重命名过。处理办法很简单：先svn cleanup，不行就重新svn checkout，不要试图手动修元数据。

二是VisualSVN Server许可证过期。社区版本身免费，但如果之前装的是试用版，到期后管理器会拒绝新建仓库。解决方案不是找破解，直接把试用版卸载干净，换装社区版原版，仓库数据在磁盘上不会丢。

三是克隆或提交时连接不上本机地址。常见原因包括端口被占用、防火墙拦截、软件缓存了旧的仓库地址。先把SVN客户端里的仓库URL重新确认一遍，再检查监听端口是否正常，不要一上来就怀疑网络带宽。

3. Git侧迁移实操：git svn 完整流程

3.1 准备好工具链

迁移用的工具是Git自带的git svn，它依赖Perl，Windows用户在安装Git时只要勾选了“Git for Windows”，通常已经包含该组件。可以在Git Bash里验证：

git svn --version

如果提示找不到命令，用管理员权限重装Git并勾选“Include submodules and git svn related tools”。Linux环境则执行：

sudo apt install git git-svn subversion

我这里还额外准备了一个原Git仓库的裸克隆，作为历史的源。裸克隆的好处是能完整保留所有引用，不会因为本地分支状态脏掉而漏提交：

git clone --mirror /original/project.git project-mirror.git

3.2 初始化Git与SVN关联并嫁接历史

核心操作分四步。第一步，在本地新建一个工作目录，把SVN仓库拉成Git可识别的远程引用：

mkdir git2svn-work cd git2svn-work git svn init --trunk=trunk --branches=branches --tags=tags --prefix=svn/ https://svn.example.com/svn/legacy-project

第二步，抓取SVN上的现有提交。因为SVN仓库刚建，只有那个初始化的结构提交：

git svn fetch

抓取完成后，git branch -a会看到类似remotes/svn/trunk的分支。第三步，把原Git仓库作为另一个remote加进来，并抓取全部历史：

git remote add original /path/to/project-mirror.git git fetch original

第四步是关键，要把原Git所有提交“嫁接”到SVN这个基础上。我采用rebase --onto把原master重放到remotes/svn/trunk上：

git checkout -b migration remotes/svn/trunk git rebase --onto migration svn/trunk original/master

这里注意，svn/trunk与original/master之间没有共同祖先，所以不能用普通git merge。用rebase --onto可以直接把一串提交应用到另一个commit之上，而忽略祖先关系。如果原仓库历史里有较多merge commit，建议先做线性化处理：

git rebase -i --root --rebase-merges

3.3 发布：dcommit把提交推上SVN

嫁接完成后，确认migration分支的提交数量与原仓库一致：

git log --oneline | wc -l

然后执行发布：

git svn dcommit

这个命令会自动把migration分支上比remotes/svn/trunk多出的每个commit逐个提交为SVN的revision。执行过程中控制台会依次打印类似：

Committing to https://svn.example.com/svn/legacy-project ... Commit r2 ... trunk Commit r3 ... trunk

SVN端的历史就变成：

svn log https://svn.example.com/svn/legacy-project

可以看到原Git提交说明、时间顺序都保留下来，唯一遗憾是每条记录的提交人都会变成执行dcommit的SVN账号，原始Git作者信息会被追加在说明末尾的Author:字段里。如果要让SVN端author也变成原Git作者，就得为每位原作者建独立SVN账号，再用对应账号分别执行dcommit，工程量大且不现实。

分支和标签的处理逻辑同理，SVN标准布局里branches和tags目录存在，Git里的分支在dcommit前要先被适配到对应的SVN分支路径，或者干脆只迁主干，分支历史在Git仓库里继续留档。多数迁移场景下，主干才是最终交付物。

4. 提交log保留失败的排查实战

4.1 我实际遇到的失败现场

这次迁移没一次跑通。执行git svn dcommit到第三四个commit时直接报错中断，控制台提示说有一个merge commit不能被线性提交，还出现过几次“File already exists”的树冲突。更要命的是，我第一次没做足准备，直接用svn import把整个Git目录导入SVN，结果服务器上只有孤零零一条revision，Git log里的每一条提交说明全部消失——这就是典型的“迁移提交log失败”。

回顾整个过程，我总结出五个高频原因，基本覆盖了Git迁SVN的大部分翻车点。

4.2 高频原因逐个拆

第一个原因是仓库结构没按标准布局走。SVN那边如果只有trunk/一个目录，没有branches和tags，git svn init -s就找不到标准结构，后续fetch下来的引用是空的，迁移自然抓不到历史锚点。

第二个原因是历史里有merge commit。SVN不承认一个revision有两个父提交，git svn dcommit遇到merge提交时的表现是“Cannot dcommit with a merge commit”或者莫名其妙的Perl报错。我那个仓库里恰好有两条分支合并记录，第一次执行就栽在这里。解决方法是先线性化，把merge打平：

git rebase -i --root

如果merge的语义在最终交付物里不重要，直接压成线性即可；如果非要保留分支合并点，只能分多次迁移到SVN的不同目录，无法原样映射。

第三个原因是账号与作者映射不全。git svn dcommit推送时，SVN服务器会校验当前认证用户的写权限。如果migration分支上某个commit的作者信息里有特殊字符或非英文姓名，控制台可能报错退出。Git的author信息与SVN账号完全不对应，虽然能通过Author:字段保留，但服务器端的权限模型只认SVN用户，这块必须提前准备好迁移账号。

第四个原因是空提交和空目录被跳过。Git允许空提交（比如只改commit message），但SVN不允许没有文件变化的提交，git svn dcommit会安静地跳过这些commit，导致SVN的revision数量和Git提交数对不上，log看起来就“少了一段”。

第五个原因是编码问题。仓库里如果有中文文件名或注释带特殊字符，且Git log的输出编码与SVN期望的UTF-8不一致，轻则乱码，重则提交直接中断。如果原仓库历史里有大量GBK编码的旧提交，建议先在Git侧做一次全量转码巡检，保证log能正常输出。

4.3 如何一步步定位问题

当log没有完整出现在SVN上时，不要瞎猜，按这个顺序排查。

第一，回看git svn dcommit的完整输出，找到第一个报错的那条提交hash。第二，在本地执行：

git fsck --full --no-reflogs

检查Git对象有没有损坏或丢失。只要原仓库的裸克隆还在，历史就不会真的丢，丢失的只是SVN端没有revision。第三，对照svn log和git log的数量与顺序，确认是“完全没有提交”还是“提交到一半中断”。第四，把migration分支重新建一份副本，用：

git rebase -i --root

把可疑的merge、空提交逐条压掉或改动message，再小步试推。我最后就是靠“先只推一条commit”的方式定位到元凶的——把migration分支rebase到只剩一条提交，dcommit成功后再把剩下的逐步追加。虽然过程繁琐，但绝对安全可控。

4.4 保底方案

如果折腾了几个小时仍没法原样保留每条log，这时候要接受“无法完美保log”的现实。我这次最终采取了混搭方案：SVN仓库只保留最终代码快照和一份完整的CHANGELOG.md，这份文件里逐条抄录了原Git log的每条提交说明和作者，保存为项目根目录下的文档；同时把原Git裸克隆打包归档，交给组长备份。这样一来，SVN作为对外交付的口径是干净的，详细追溯仍可在归档的Git仓库里完成。

用一句话概括我的观点：没有必要为了“让SVN服务器上每一条log和Git一模一样”这个执念耗费几天时间，重要的是资产不丢、逻辑可追。

5. 常见问题速查表与避坑清单

5.1 问题速查表

整理一下这次迁移中遇到过、以及身边同事常问的典型问题，可以直接对照处理：

5.2 迁移前必须确认的检查清单

分享迁移前务必检查的几个点，避免中途返工：

• 确认SVN仓库已创建标准目录结构，并且有一条初始提交作为锚点。
• 确认迁移账号有仓库根目录的写权限。
• 确认原Git仓库的裸克隆已备份，并且git fsck无错误。
• 确认历史中是否有merge、空提交，提前做线性化。
• 确认commit message中的编码与SVN服务端utf-8兼容。
• 确认SVN服务器时间和Git提交时间没有大面积倒挂，否则SVN revision顺序会乱。

这份清单每一条都是我这次踩出来的，尤其最后一条最阴——SVN要求revision时间线必须递增，如果历史里某条commit时间早于前一条，dcommit服务端照样收，但SVN日志里的排序会非常难看，后段提交顺序全乱，项目组看log时会完全摸不着头脑。

最后再分享一个小技巧：迁移完成后别急着删Git仓库，至少保留半年。SVN只是交付形态，Git仓库里的分支、tag、二进制历史、注释里的讨论记录，SVN都没法完全承载。我在这次迁移结束后，把裸克隆放到了内部归档区，后续任何一次需求回溯都从Git侧查，SVN侧只作为被审计和交付的“面子工程”。这样做虽然两边维护有点麻烦，但长期来看，不会因为格式转换丢掉任何有效信息。