先交代个背景在 Windows 上做版本管理很多人第一次接触版本库就是装个小乌龟 TortoiseSVN然后在某个目录右键 Create repository here再把项目文件提交进去觉得自己已经会用 SVN 了。这个动作确实能生成一个版本库但它离“一个真正可以给团队用的代码仓库”还差得很远——同事怎么连进来谁能读谁能写代码要不要分主干和分支本地改坏了怎么回滚这些没有一个按钮是右键菜单能解决的。这篇我以“创建版本库”为主线从最基础的svnadmin create开始把 Windows 本地搭建、仓库目录规划、权限分配、客户端接入和常见报错排查完整串一遍。适合刚接手 SVN 维护、或者想在局域网里搭一个代码托管环境的朋友看完能直接照着操作并且知道每一步为什么这么做。1. 创建版本库之前先把访问方式想清楚很多人以为创建版本库就是一条命令的事实际上“怎么访问这个库”才是影响所有后续配置的关键。SVN 版本库本身没有“协议”的概念它只是一堆数据文件放在磁盘上但你用什么方式让别人读到它决定了你要不要启动额外进程、要不要开防火墙端口、能不能做权限控制。1.1 file://、svn://、http(s):// 三者的实际差别访问版本库有三种最常见的 URL 形式file:///、svn://、http(s)://。我见过不少新手初期一直用file:///D:/svn-repos/xxx访问自己一个人玩没问题等同事要拉代码时才发现人家根本连不上——因为file://本质是读你本地磁盘文件跨机器只能靠网上邻居之类的文件共享权限和稳定性都很糟糕。访问方式依赖的服务进程适用场景主要代价file:///无直接读本地磁盘单机自用、临时测试无法用于真正的团队协作svn://svnserve 进程局域网小团队需要注册服务、开防火墙 3690 端口http(s)://Apache / VisualSVN Server跨网络、企业级安装配置较重但集成域认证更方便我的建议很明确如果你们是几个人在同一个局域网里共用就用svn://配合 svnserve如果团队人数多、要跨办公网点或者公司已经有活动目录账号体系直接上 VisualSVN Server 走 HTTPS 反而省心。版本库本身用svnadmin create创建时并没有区别区别只在于你之后用哪个服务进程去“暴露”它。这一点是新手最大的认知盲区一定要先想清楚再动手。1.2 仓库目录放哪、建在哪个盘版本库存放的位置有三个硬性要求路径不要带中文和空格、不要放在系统盘、所在磁盘要有足够空间。原因不复杂——SVN 仓库里每个文件的历史版本都会保存随着提交次数增长db目录会越来越肥。系统盘通常有权限保护重装系统时也容易一锅端中文路径则会在某些命令行工具、IDE 插件和 TortoiseSVN 的老版本里触发编码问题没必要给自己挖坑。我自己的习惯是在 D 盘建立一个专门的根目录比如D:\svn-repos然后在下面按项目建仓库。这种“一个根目录管多个仓库”的做法配合 svnserve 的-r参数会非常舒服URL 可以直接写成svn://服务器IP/项目名。如果只建一个库并把所有项目都塞进去后边做权限隔离会越来越痛苦因为 authz 文件里要写非常多路径规则。1.3 顺带聊几句 Git 和 SVN 的选型差异搜索记录里很多人会对比 Git 和 SVN其实两者不是同一个时代的产物Git 是分布式的每一个工作副本都是完整仓库SVN 是集中式的所有历史都只在服务端。对小型团队、Windows 环境、成员普遍不熟悉命令行的人来说SVN 的优势很实在——概念少、权限模型简单、TortoiseSVN 图形化之后基本没有学习门槛。日常提交、更新、打分支用鼠标就能完成。如果团队已经习惯 Git 分支流程那就没必要为了统一工具迁回 SVN但如果只是想在公司内部快速搭一套“能管理代码版本、能控制谁改哪块”的环境SVN 是最省事的选择。后面我讲的内容都是围绕集中式仓库展开的。2. 用 svnadmin 和 TortoiseSVN 创建版本库实操选型确定之后创建动作本身其实很简单。前提条件是你已经装好 TortoiseSVN安装时记得勾选命令行客户端组件这样C:\Program Files\TortoiseSVN\bin目录下才会有svnadmin.exe、svnserve.exe、svnlook.exe这些工具。如果没找到单独装一个 SlikSVN 或者 VisualSVN Server 也能拿到这些命令行程序。2.1 命令行创建svnadmin create 与生成目录结构打开一个管理员身份的 CMD 或 PowerShell执行svnadmin create D:\svn-repos\myproject --fs-type fsfs这里--fs-type fsfs其实不写也行因为 Subversion 新版本默认就是 FSFS 存储格式我显式写出来只是为了让命令更直观。FSFS 的特点是每个版本对应磁盘上的一组文件备份容易、损坏概率低早期还有一个 BDB 格式依赖数据库环境官方早已边缘化能不用就不用。执行完之后D:\svn-repos\myproject目录下会生成这样几项内容conf配置目录权限相关的三个文件都在这里后面第 4 节重点讲。db真正的仓库数据区所有历史版本存在这里。hooks钩子脚本目录放的是模板文件改成可执行文件名后可以在提交前、提交后触发自定义操作。locks目录锁相关一般不用管。format/README.txt版本格式说明文件。创建出来的是一个 revision 0 的空库没有任何目录、没有任何代码相当于刚装修完的空房间。很多新手在这个阶段就开始把文件往仓库目录里复制这是不对的——版本库目录不是你放代码的工作区它只能被 svnserve 访问任何直接往db里塞文件的行为都可能弄坏仓库。2.2 图形化创建TortoiseSVN 的 Create repository here如果你不想碰命令行TortoiseSVN 也提供了图形化入口先建一个空目录D:\svn-repos\myproject然后右键这个目录选择 TortoiseSVN - Create repository here弹窗里选 FSFS点确定版本库结构就生成了。注意这里的细节这个操作会把“当前这个目录”直接变成版本库根目录也就是说目录本身已经变成仓库了不会再有一层嵌套。所以你在做图形化创建时应该先想清楚最终 URL 要长什么样。如果你用svnserve -r D:\svn-repos暴露根目录那D:\svn-repos\myproject对应的 URL 就是svn://服务器IP/myproject这个对应关系很直观。图形化方式适合一次性建库命令行方式适合批量建库。比如你要一次性给十几个项目建仓库写一个 for 循环脚本调用svnadmin create明显比一个个右键点更快。2.3 把 svnserve 注册成 Windows 服务并在防火墙放行 3690仓库建好后还缺一个“对外服务”的进程。最简单的方式是在命令行跑svnserve -d -r D:\svn-repos-d表示后台守护-r指定根目录。但这种方式有个问题手一抖关了那个命令行窗口服务就断了电脑重启后它也不会自动拉起。所以正式环境一定要把 svnserve 注册成 Windows 服务。以管理员身份打开 CMD执行sc create svnserve binPath \C:\Program Files\TortoiseSVN\bin\svnserve.exe\ --service --root D:\svn-repos start auto sc start svnservesc create后面的binPath参数比较刁钻如果路径里有空格引号需要写成\\这种转义形式很多人第一次注册失败都是卡在这里。注册好之后打开服务管理器能看到一个名为 svnserve 的服务把它设为自动启动就完成了。还要提醒一下Windows 防火墙默认会拦截外部机器访问 3690 端口。添加一条入站规则的方法有很多种我习惯用命令netsh advfirewall firewall add rule nameSVN Service dirin actionallow protocolTCP localport3690补充一个很容易踩的坑-r这个参数的值是“所有仓库的父目录”不是某一个具体仓库。如果你写成--root D:\svn-repos\myproject那访问 URL 就会变成svn://服务器IP/URL 里反而没有仓库名了。父目录作为根子目录名才作为仓库路径这个映射关系千万别搞反。2.4 第一次访问验证服务起来之后别急着通知同事。先自己在服务器本机验证一遍打开 CMD 执行svn list svn://localhost/myproject如果命令没有任何输出也没有报错说明连接正常如果提示无法连接到主机先检查服务是否真的在跑再用telnet localhost 3690看端口通不通。局域网内其他机器要把localhost换成服务器 IP比如svn list svn://192.168.1.10/myproject。telnet 不通的时候优先排查防火墙规则其次是确认 svnserve 运行账户对仓库目录有读写权限。3. 空库到手先做目录初始化trunk/branches/tags 与首次导入仓库建好只是第一步真正决定后面代码管理是否顺畅的是往空库里放什么目录结构。我没有见过哪个正规团队把代码直接稀里哗啦全堆在仓库根目录下的那样做一两次还行等你要给一个版本打标签、要派两个人同时开发两个不同版本功能时就完全失控了。3.1 为什么标准布局是 trunk、branches、tags创建一个空库后第一件事就是在仓库根下建三个子目录trunk、branches、tags。这是 Subversion 社区最常见的标准布局几乎可以被当成默认约定来理解trunk主干随时处于可发布状态的代码主线。大部分常规提交都发生在这里。branches分支从主干复制出来做并行开发的实验线。比如大版本重构、临时回滚修复都可以开一条分支互不干扰。tags标签某个时间点的快照。发布 1.0、2.0 版本时把对应代码复制到 tags 下存档之后随时能找回当时的样子。用生活化的话说trunk 是流水线主作业台branches 是旁边的实验台tags 是拍好照片放在相册里的作品集。这个结构的好处是约定统一——不管谁 checkout 你的仓库第一眼就能明白哪条是主线、哪个是历史快照。3.2 两条导入路径svn import 和 checkout 后 commit把现有的代码项目放进仓库传统做法是右键本地项目根目录选 TortoiseSVN - Import然后在导入对话框里填上 URLsvn://服务器IP/myproject/trunk确认即可。这里有一个几乎所有新手都会误解的细节Import只负责把本地文件夹内容“上传”到仓库它不会在你本地产生.svn元数据目录。也就是说导入完之后你本地的项目目录依然是一个普通文件夹它跟仓库没有任何连接。要继续在这个目录里开发、提交必须把它删掉然后在空白目录重新svn checkout svn://服务器IP/myproject/trunk把代码从服务器拉回来再继续工作。还有一种方式是先 checkout trunk 出空目录再把本地代码文件拷进去执行 TortoiseSVN - Add然后右键 Commit。这种方式适合那些希望本地目录从一开始就纳入版本管理的场景但操作步骤更繁琐。我个人的习惯是第一天图省事用 import导入完马上删本地目录重新 checkout 一遍让后续操作都建立在正常的工作副本上。3.3 版本号与首次提交的常见失误空库的版本号是 revision 0第一次提交后版本号变成 1。注意 SVN 的版本号是仓库全局递增的不是按项目或者按目录独立计数的。建多个仓库时每个仓库自己有独立的版本号序列这个不受影响。很多人在 Trunk 上工作了一段时间想打个 1.0 标签就直接右键 trunk 目录复制了一份改名成 tags这没问题但要注意 tags 目录下的任何文件都不应该再被修改。如果发现 tag 有 bug正确做法是开一个 bugfix 分支去修修完再合回主干重新打一个新 tag。直接在 tag 里提交会让“快照”失去意义也会让其他人对目录用途产生混乱。3.4 忽略规则和首批代码的常见失误首批导入代码时最容易犯的错误是把编译产物体、IDE 配置、依赖包全部提交上去。比如 Java 的target、classesC# 的bin、objVSCode 的.vscodeIDEA 的.idea前端项目的node_modulesPython 的__pycache__日志文件.log。这些东西体积大、变化频繁、而且每个开发者的本地环境不同提交它们只会让仓库快速膨胀造成大量无意义的冲突。在 TortoiseSVN 里打开 Settings - Subversion - Global ignore pattern把这些通配符样式填进去。我建议至少在全局忽略里加上这样一行bin obj node_modules .idea .vscode target dist .class .log除了全局忽略也可以在仓库根目录设置svn:ignore属性后者随仓库走团队所有人 checkout 下来设置都会生效。两者配合使用能挡掉绝大部分误提交。4. 权限文件三件套svnserve.conf、passwd、authz 从零配置SVN 集中式最大的优点之一就是权限控制非常直观。仓库目录下的conf里三个文件——svnserve.conf、passwd、authz——共同完成了“谁能访问、能不能读写、能读写哪些路径”的控制。这一节我会把三个文件拆开讲清楚因为这是团队协作能不能顺利运转的分水岭也是网上搜索量极大的一个话题。4.1 三个配置文件的分工先给一个总览表文件职责关键内容svnserve.confSVN 协议服务主配置匿名访问策略、认证文件路径、授权文件路径passwd用户与密码清单用户名明文密码authz路径访问规则用户/组对仓库下路径的读写权限svnserve.conf的默认内容基本全是注释需要自己解开对应配置项。一个最常用的配置是这样的[general] anon-access none auth-access write password-db passwd authz-db authz realm myproject repository解释一下几个关键项anon-access none禁止匿名访问。设为read的话任何人都能拉代码设为write的话匿名用户都能提交这基本等于裸奔千万不要。auth-access write登录用户默认可写。如果团队里有成员只该读代码靠 authz 单独限制。password-db passwd告诉服务进程用户名密码存在哪个文件。authz-db authz开启路径级授权。注意一旦启用 authz权限判断就完全按照 authz 文件来没写到的路径任何人都没有权限。passwd文件里格式如下[users] zhangsan 123456 lisi abc123 wangwu 654321这里有一个很现实的问题svn://协议是明文传输的密码在网络里等于裸奔。局域网自己人用一用问题不大如果有人力保密的诉求请切换到 HTTPS 方案那会让复杂度上一个台阶。4.2 authz 路径权限细节与“上级目录无权限”的真实根因authz文件是权限控制的核心。常见写法如下[groups] dev zhangsan, lisi pm wangwu [myproject:/] * dev rw pm rw [myproject:/branches/feature-001] dev rw这里的段名是[仓库名:/路径]第一段[myproject:/]表示 myproject 仓库的根路径。规则从上到下按“最具体路径优先”匹配也就是说/branches/feature-001下的规则会覆盖根路径下对同一个用户/组的设置。然后我重点说一个搜索记录里高频出现的问题拉取代码没问题但提交代码时提示某一层上级目录没权限。很多人的第一反应是“我只提交子目录文件跟上级目录有什么关系”。事实上 SVN 在提交时的权限校验不是只看目标文件所在目录而是要从仓库根开始把目标路径上的每一级节点都校验一遍。路径上任一级缺少读权限整次提交都会被拒绝。举例你在[myproject:/branches/feature-001]下面给 dev 组开了rw但[myproject:/]里没有给 dev 组任何读权限那么 dev 组成员 checkout 时根目录都读不到提交时更是会直接报 Permission denied。解决办法是在根路径给读权限让具体写权限落在需要的目录[myproject:/] dev r [myproject:/trunk] dev rw [myproject:/branches/feature-001] dev rw这样 dev 组能读取整个仓库结构、在 trunk 和 feature 分支下正常开发但又不会莫名其妙获得整个仓库的写权限。如果你真的希望某些组只能接触某个子目录小心不要让根路径的写权限开得太宽否则目录隔离就形同虚设了。还有一个容易被忽略的点同一个用户如果同时属于多个组权限取各组合并之后的“宽松”结果。比如 dev 组只有读权限、admin 组有写权限那么该用户最终是写权限。配置时注意不要因为组叠加而意外放开范围。4.3 修改配置后为什么不用重启服务端svnserve 在每次客户端发起请求时都会重新读取 conf 里的配置文件所以你改完passwd或authz保存即可不需要重启服务。这一点对运维很友好——半夜改一个用户密码保存完立刻生效。不过客户端这边有一个缓存坑TortoiseSVN 会在本机缓存认证信息你改完服务器端密码客户端如果还带着旧密码尝试连接会报认证失败或者弹不出新的登录框。这时到 TortoiseSVN 的 Settings - Saved Data把认证数据清一下再访问仓库就会重新弹窗让你输账号密码。IDEA 里也有类似的密码缓存在 Subversion 设置里清除即可。4.4 用 pre-commit 钩子挡住空提交信息在hooks目录下默认有一堆.tmpl结尾的模板文件。把它们复制一份并去掉.tmpl后缀就能成为可执行的钩子脚本。比如pre-commit.tmpl改成pre-commit.bat每次提交前系统会自动执行脚本如果脚本返回非零值提交就会被拦截。Windows 下示例脚本如下echo off set SVNLOOKC:\Program Files\TortoiseSVN\bin\svnlook.exe %SVNLOOK% log -t %2 %1 | findstr . nul if errorlevel 1 ( echo 提交信息不能为空 2 exit 1 ) exit 0这个脚本做的事是检查提交事务的日志信息里面有没有非空字符如果没有就以非零退出拒绝这次提交。很多团队不强制写提交信息但一旦协作人数超过三个人没有提交信息的日志会变成灾难。这是我比较推荐的第一个钩子脚本因为成本几乎为零但收益立竿见影。5. 客户端接入、Checkout 与提交权限报错排查实录版本库建好、目录结构搭好、权限文件配好接下来就是要让团队成员能够稳定地使用它。这一节我挑几个搜索记录里特别密集的场景按真实踩坑顺序来写基本都是可以直接照用的排查思路。5.1 TortoiseSVN、IDEA、VSCode 三种客户端的接入要点TortoiseSVN 的使用方式很简单随便找个空白目录右键选择 SVN Checkout填写仓库 URL 如svn://192.168.1.10/myproject/trunk指定检出位置确认即可。检出完成后文件夹图标上会多出绿色打勾状态表示这是一份干净的工作副本。IDEA 接入 SVN 时最容易出问题的点是命令行客户端路径。打开 Settings - Version Control - Subversion路径一栏要指向svn.exe的真实位置而不是只靠 IDEA 内置。如果路径没配好版本控制面板会显示不出文件状态提交时也会各种抽风。配好之后从主菜单选择 VCS - Checkout from Version Control - Subversion输入 URL 就能把项目拉下来作为 IDEA 工程打开。VSCode 则要装对应扩展装完在设置里搜svn.executable把svn.exe完整路径填进去。装好后左侧资源管理器里的文件会用颜色标出新增、修改、冲突等状态这就是搜索词里“vscode使用svn标记文件”的来源。注意 VSCode 的 SVN 扩展对中文路径和特殊字符支持比较一般建议工作副本路径里别带中文。5.2 误 update 后如何找回本地修改“TortoiseSVN 不小心 svn update 了怎么办”这个问题在搜索里出现次数不少但大多数人其实没搞清 update 和覆盖的区别。svn update不会无脑覆盖你已经修改的文件如果服务器版本和本地修改冲突了TortoiseSVN 会弹出一个冲突合并窗口并把冲突文件旁边生成三个临时文件文件.mine你自己的版本、文件.r旧版本号你更新前的基础版本、文件.r新版本号服务器最新版本。这三个文件可以手工保留也可以用 TortoiseSVN - Edit Conflicts 打开对应窗口逐个选择保留谁的内容。如果 update 之后你想反悔可以直接右键冲突目录选择 TortoiseSVN - Revert把未提交的本地修改全部还原。但注意 Revert 只清空本地未提交的改动不会改变已经提交到服务器的内容。如果真正担心的是“我改的东西被 update 更新没了”先别急用 TortoiseSVN 的 Show Log 查看这个文件的历史在追求自己修改过的那个版本处双击查看内容通常都能找回来再按 5.3 的操作恢复即可。5.3 回滚到指定日期/版本的正确姿势回滚是 SVN 使用中的高频需求也是一个非常容易搞混的点。搜索词里有“svn 回滚到指定日期版本操作”这里我给出准确的操作路径。首先要分清两种诉求我只是想“看看”某个文件在旧版本长什么样用 Show Log选中对应版本双击或右键 Show 查看内容。我希望能让服务器上的最新版本也恢复到某个历史状态必须先让工作副本变成一个“旧版本的新修改”然后提交。大部分教程推荐的反向合并命令是svn merge -r HEAD:123 .意思是把当前工作副本从 HEAD 版本的状态反向合并到 123 版本的状态。执行后本地文件会变成旧版内容但注意它并没有真正提交到服务器这只是一个“新的未提交修改”。你再执行svn commit -m rollback to r123服务器上才会真正多出一个新版本其他同事svn update之后就会拉到你回滚的结果。TortoiseSVN 图形化操作方法是右键工作副本 - Show Log选中要回退到的版本然后右键选择Revert changes from this revision或Revert to this revision。两者的差别在于前者是撤销该次提交的改动后者直接把整个工作副本的所有后续改动全部丢弃、回到那个版本的样子。选完之后它会生成一次本地修改同样需要再 commit 才能同步到服务器。我特别提醒一句SVN 的日志保存在服务器仓库里客户端离线状态下是查不了历史日志的。本地wc.db里只有当前工作副本状态跟提交历史是两回事。“svn log 离线”这个问题在搜索里意味着大家还在期待类似 Git 的本地历史但这在集中式模型里不存在快速认清这一点能避免很多无谓折腾。5.4 “svn report request on failed” 这类网络层错误的排查链搜索热词里有“svn report request on failed”这通常是 check/update/commit 时报的一类网络层错误出现原因五花八门。我整理一条排查链路按顺序走下来基本能定位。第一步确认 svnserve 服务活着。在服务器上打开服务管理器看 svnserve 状态或执行sc query svnserve如果服务没启动就先启动。第二步确认端口通。在客户端机器执行telnet 服务器IP 3690如果连不上重点查 Windows 防火墙是否放行了 3690 TCP 入站规则。第三步验证仓库完整性。在服务器上执行svnadmin verify D:\svn-repos\myproject如果输出一堆错误说明仓库数据区已经有文件损坏。FSFS 格式通常比较皮实但如果仓库所在磁盘满了、或者计算机非正常断电仍然可能出现问题。此时只能从备份恢复这也是为什么最后我要专门强调备份。第四步检查 NTFS 权限。svnserve 运行账户必须对仓库目录有读写权限特别是db目录。Windows 下很多诡异报错其实是共享目录或 NTFS ACL 权限挡住写操作导致的。第五步清客户端缓存。TortoiseSVN 的 Saved Data 里清除认证和临时数据然后重新 checkout。偶尔是客户端本地存放的信息和服务端不一致清掉就恢复。这条链路我实际排查过太多次每一条都可能单独触发。不要一上来就怀疑仓库损坏先从服务、端口、防火墙这些最廉价的检查点开始。至于另一个热词“svn 更新代码前注意事项”其实要点就是三条先看清本地有没有未提交的修改提交或者暂存好再 updateupdate 之前尽量保证本地工作副本是干净的遇到需要合并的文件不要慌用 TortoiseSVN 的冲突编辑工具不要手动乱删。养成这个习惯能在绝大多数情况下避开“update 后本地修改被搞乱”的麻烦。最后再分享一个我自己维护 SVN 仓库多年的习惯创建版本库很容易维护版本库才是功夫。我每周末会固定做一次完整性快照先执行svnadmin verify检查仓库数据然后用svnadmin hotcopy把整个仓库目录热拷贝到备份盘。热拷贝不用停服务操作也很简单svnadmin hotcopy D:\svn-repos\myproject E:\backup\svn\myproject备份这事看着不起眼真到了磁盘故障或误删仓库的时候就知道这一条命令值多少钱了。版本库是团队代码资产的总闸门宁可永远用不上备份也不能在需要的时候没有备份。
