写博客这件事越写到后面越会发现真正卡住你的不是文笔而是文件管理。我见过太多人写了半年博客文章散落在三个电脑、两个U盘和一个被覆盖的文件夹里哪天硬盘一挂几年的产出直接清零。这一篇我们来解决这个问题也是整个自建博客系列里我认为最值得反复看的一篇代码托管。这里说的代码托管准确讲是用 Git 做版本管理再把仓库推到码云Gitee上做云端备份和后续的自动化部署。适合正在自建博客、但还没搞明白 Git 怎么用、推送老失败、或者听说过 SSH 免密但一直没配成功的朋友。我会从 Git 是什么、为什么博客需要它讲起然后完整走一遍 Windows 环境下的安装、配置、SSH 密钥生成再到码云建仓库、本地初始化、首次推送最后会把博客日常更新的标准流程和高频报错一起梳理出来。整个系列走到这一步你的博客基本就具备了“换电脑也能三分钟恢复写作”的能力。1. 写博客的人为什么绕不开 Git 和码云1.1 博客文件管理的尴尬现状不知道你有没有经历过这样的场景文章写了一半想在另一台电脑上继续结果只能靠 U 盘拷、网盘传、邮件发附件改了一版又一版文件名从博客正文变成博客正文最终版再变成博客正文最终版2-打死不改突然有一天发现某篇文章被自己改坏了想回到三天前那个能用的版本却发现早被覆盖了。这种混乱在写博客初期还能忍一旦文章数量上了五六十篇配图、代码片段、自定义样式文件混在一起整个博客目录就成了一个你不敢乱动、又不知道哪些能删的黑洞。这其实就是典型的“没有版本管理”的副作用。1.2 代码托管到底解决了什么问题Git 是一个非常朴素的工具它的全部核心就两件事记录快照和分叉合并。所谓记录快照就是你在每个关键节点打一个标记Git 把这个时刻所有文件的状态完整保存下来。你不需要自己起文件名不担心覆盖随时可以回到任意一个历史节点。分叉合并则是方便多人协作或者多设备同步——你在办公室改了一版回家又改了一版Git 可以帮你把两条线合并起来遇到冲突时给出提示而不是静默覆盖。而码云这类代码托管平台做的就是两件事一是帮你把 Git 仓库放到云端作为异地备份硬盘坏了也不怕二是提供一个 Web 界面让你能在线查看文件、查看提交记录、给文章打标签甚至后续接上自动部署服务实现“本地 push线上自动更新博客”。1.3 在自建博客这条线上Git 和码云的分工结合这个系列前两篇的内容现在你的博客大概已经是这样的状态本地有一堆静态文件可能是 Hexo 的 source 目录、Hugo 的 content 目录或者直接用 Next.js 构建出的静态站点需要通过某种方式发布到服务器。在没有代码托管之前典型操作是本地改完文件用 FTP 工具整站上传或者手动复制到服务器目录。这种方式有两个明显问题增量更新很难每次全量传既慢又容易漏文件回滚很麻烦传错了就把服务器上的备份覆盖了想还原只能靠你在本地留了个备份。引入 Git 和码云之后整个流程会变成本地修改、commit 提交、push 推送到码云然后通过各种手段手动拉取或自动部署把最新代码同步到服务器。每一次操作都有日志出了任何问题都可以回滚到任意历史版本。这也是业界目前最主流的静态博客发布流程可以说是绕不开的标准答案。2. Git 安装Windows 环境下的完整配置2.1 下载 Git 并完成基础安装国内用户安装 Git最省心的方式是直接访问 Git 官网下载对应系统版本。如果你的网络访问官网比较慢也可以用国内的一些开源镜像站下载速度会快很多原理都一样安装包本身并没有差别。以 Windows 为例下载得到的通常是.exe安装文件双击运行一路 Next 就行。这里提醒一下不要为了方便直接全部默认安装有几个选项值得看一下再点关系到你后面用起来的顺手程度。安装过程中会问几个比较关键的选项我的建议是这样选Select Components页面勾选 “Git Bash Here” 和 “Git GUI Here”这会在鼠标右键菜单里加入入口非常方便。Default editor页面如果你不熟悉 Vim务必把默认编辑器改成 Notepad 或 VS Code否则后面 commit 时让你写注释你会被 Vim 卡到怀疑人生。Adjusting your PATH environment页面选择Git from the command line and also from 3rd-party software这样 Git 命令会在 CMD 和 PowerShell 里都能直接使用。Line ending conversions页面选默认的 “Checkout Windows-style, commit Unix-style line endings” 就好这能避免后面在不同系统之间切换时出现换行符相关的诡异问题。2.2 安装完成后的验证与两种使用入口安装完成后在桌面空白处点鼠标右键你应该能看到Git Bash Here的选项。点开它输入git --version如果输出类似git version 2.40.0.windows.1就说明安装成功。这里顺便解释一下 Git Bash 和其他几种使用方式的关系。Git 在 Windows 下有三种入口最常用的是Git Bash它模拟了一个类 Linux 的终端环境命令习惯和服务器端一致这个系列后面所有操作都建议在 Git Bash 里进行Git CMD是 Windows 命令提示符风格的入口日常用不太到还有一些图形化工具比如“小乌龟”TortoiseGit它是把 Git 操作集成到右键菜单里的图形界面对不熟悉命令行的朋友比较友好但我个人建议学博客部署还是把命令行基础操作掌握好因为后续和服务器、自动化脚本打交道时命令行填坑效率远高于图形工具。2.3 关于环境变量配置的补充说明有些朋友安装完 Git 后在 cmd 里输入git会提示“不是内部或外部命令”这大概率是安装时把 PATH 环境变量那个选项选错了或者 Git 安装路径没有自动加入系统 PATH。解决办法是右键“此电脑” - “属性” - “高级系统设置” - “环境变量”在系统变量的Path中添加 Git 的安装目录下的cmd文件夹路径默认一般是C:\Program Files\Git\cmd。修改完环境变量后记得重新打开终端再验证。注意环境变量修改后不会自动生效需要关闭并重新打开终端窗口。如果你的电脑装了新终端环境比如 Windows Terminal也要完全重启这个程序才能加载新的 PATH。3. 首次配置与 SSH 免密这一步做完推送不再烦3.1 设置你的身份标识Git 装好后第一件事不是学命令而是先告诉 Git 你是谁。这个身份会写进每一次的提交记录里后续别人或者未来的你看提交历史时能知道哪次提交是谁做的。在 Git Bash 里执行git config --global user.name 你的名字 git config --global user.email 你的邮箱这两个配置是全局的作用于这台电脑上的所有 Git 仓库。建议直接用真实常用的昵称和邮箱因为之后这些信息会出现在码云仓库的提交记录里如果乱填以后再改历史记录里的作者信息虽然可以修改但很麻烦。想要确认配置已经生效可以执行git config --global --list这是一个查看全部全局配置的命令你会看到类似这样的输出user.name你的名字 user.email你的邮箱3.2 为什么要用 SSH 而不是 HTTPS和码云连接的方式主要有两种HTTPS 和 SSH。HTTPS 方式下每次 push 和 pull 都需要输入码云的账号密码。有些人觉得这没什么输入就输吧。但实操下来频繁输入密码真的会打断写作节奏而且有些 IDE 或自动化脚本在非交互环境下根本没法输入密码会直接卡死。虽然 Windows 系统有凭据管理器可以帮你记住 HTTPS 的密码但偶尔还是会遇到凭据失效需要重新输入的麻烦。SSH 方式则是用一对密钥来认证本地生成一个私钥和一个公钥公钥放到码云后台私钥留在本地。推送时 Git 会使用私钥进行签名码云用公钥验证身份整个过程不需要输入任何密码。这就是大家常说的SSH 免密。我实际用下来的感受是SSH 配置一次之后所有仓库、所有项目都永久免密非常值得花十分钟搞明白。3.3 生成 SSH 密钥并配置到码云在 Git Bash 中输入ssh-keygen -t rsa -b 4096 -C 你的邮箱执行后终端会问你要把密钥文件保存到哪里直接按回车使用默认路径~/.ssh/id_rsa即可。接着会让你输入一个 passphrase密钥口令这里可以直接留空按回车表示不设置额外口令。如果设了口令虽然安全性更高但每次连接时还得输入口令就失去“免密”的意义了。生成成功后执行cat ~/.ssh/id_rsa.pub把输出的内容复制下来这是一整行以ssh-rsa开头、以你的邮箱结尾的字符串。然后登录码云进入设置-SSH 公钥标题随意填比如“我的主力笔记本”公钥粘贴进去保存。3.4 验证 SSH 连接是否正常配置完成后在 Git Bash 里执行ssh -T gitgitee.com第一次执行会提示确认主机指纹输入yes回车即可。如果配置成功你会看到类似Hi XXX! Youve successfully authenticated, but GITEE.COM does not provide shell access.的输出。这就是再标准不过的成功信号。看到这个提示说明 SSH 免密已经打通。如果你在配置过程中遇到Permission denied (publickey)的报错大多数情况是公钥粘贴时多了空格或换行或者你用的是 32 位版本的 ssh-keygen。可以将这个问题记下来到后面的常见问题部分对号入座排查。提示SSH 的公钥和私钥就好比一把锁和一把钥匙。公钥是锁可以放心给别人私钥是钥匙绝对不能泄露不要把它上传到任何公共仓库或在线笔记里。4. 码云实战从创建仓库到首次推送4.1 注册码云账号与创建远程仓库码云Gitee是目前国内访问速度最稳定的代码托管平台之一。去官网注册一个账号流程很简单注意用户名一旦确定会在你的仓库 URL 中出现建议直接用和博客品牌一致的英文名不要用手机号或乱打的 ID。注册时如果有邀请码选项没有就跳过。登录后右上角“”号 - “新建仓库”进入仓库创建页面。这里有三个关键选项仓库名称一般和博客项目名保持一致比如my-blog、hexo-blog。这个小写字母和连字符的组合会在之后的仓库地址中直接体现。是否私有如果博客仓库里放的是源码和配置不含敏感信息公开也行方便分享如果不想让别人看到稿子、草稿或一些隐私配置文件选私有码云私有仓库也是免费的。初始化仓库如果你在本地已经有博客文件建议这里全部不要勾选不要自动生成 README、.gitignore 和许可证保持一个完全空的远程仓库这样本地首次推送不容易产生冲突。4.2 本地仓库初始化与 .gitignore 配置创建好远程空仓库后先不要急着在码云页面操作。回到你的博客根目录在 Git Bash 中执行git init这个命令会在当前目录创建一个隐藏的.git文件夹这就是 Git 用来保存版本信息的地方。目录里如果没有.gitignore文件建议先手动创建一个再开始首次提交。.gitignore的作用是告诉 Git 哪些文件不需要被纳入版本管理。对于博客项目通常需要忽略这些内容依赖包目录如 Node.js 项目的node_modules构建产物如 Hexo 生成的public/目录、Hugo 的public/系统的临时文件和 IDE 配置文件如.DS_Store、.vscode/本地环境变量文件如.env等我见过不少新手直接把整个博客目录一股脑推上去结果几千个小文件全部进仓库不仅推送慢后续每次改动都容易把无关的依赖文件也提交进去仓库体积迅速膨胀。.gitignore这件事值得一开始就做好。我的博客.gitignore大致长这样不同框架会有差异这里是通用思路node_modules/ public/ .DS_Store *.log .env注意不同博客框架对静态文件的生成方式不同如果你用的是 Hexo 且确实想把生成的静态文件也托管到码云比如为了配合静态 Pages 服务那就不要忽略public/。这个取舍取决于你的部署方案本系列后面讲自动化部署时会单独展开。4.3 完成第一次 commit 与 push本地初始化完成后执行以下三条命令这就是 Git 使用频率最高的“提交三步曲”git add . git commit -m first commit第一条命令git add .是把当前目录下所有未被忽略的文件加入暂存区。这里的点表示当前目录。第二条命令是提交-m后面跟的是本次提交的说明文字。第一次提交的说明一般就叫“first commit”就行。提交完成后还要把本地仓库和远程仓库关联起来。需要回到码云的仓库页面复制仓库的 SSH 地址形如gitgitee.com:你的用户名/仓库名.git。然后在本地执行git remote add origin gitgitee.com:你的用户名/仓库名.git git push -u origin master这里解释一下这两行命令在做什么。git remote add origin是把远程仓库的地址绑定到本地仓库origin是远程仓库的默认别名后面推送时就用这个名字代替一长串地址。git push -u origin master是把本地的 master 分支推送到远程-u参数会在推送的同时把本地分支和远程分支关联起来之后在本地执行git push或git pull时就不需要再指定分支了。如果你的默认分支名是main而不是master把第一条里的master换成main即可。具体是哪个本地执行git branch看一下输出就能确认。4.4 三种远程仓库地址方式的选型码云仓库页一般会提供三种地址HTTPS、SSH 和 SVN。最推荐的方式是使用 SSH 地址这也是前面花时间配置密钥的原因。HTTPS 地址可以作为备用万一某个网络环境对 SSH 端口不友好可以临时切换。SVN 方式对熟悉 SVN 的用户比较友好但对新项目建议直接拥抱 Git不要用 SVN 语义去理解 Git 的分支和提交。仓库创建后在码云页面你会看到仓库的文件列表和初始化的提交记录。到这一步“代码托管”的第一环就完成了——本地文件有了版本记录远程有了备份。接下来要解决的是日常写博客时怎么高效地用 Git 完成更新。5. 博客日常维护的 Git 工作流高频操作与进阶技巧5.1 一次完整的博客更新流程当你的博客已经成功绑定 Git 和码云之后平时写新文章或者改样式基本就是一套固定的流程。我自己的习惯是写文章或改代码先预览和检查Hexo/Hugo 都需要本地预览确认样式正常执行git add .把所有改动加入暂存区执行git commit -m add post: 题目提交说明文字按本次改动的主题写清楚确认没问题后执行git push推送到码云这套流程看起来简单但有几个细节值得养成习惯。commit 的说明文字建议写清楚“做了什么”比如fix: 修复导航栏在移动端不显示的问题或者add: 新增文章《XXX》。一段时间之后回看提交历史你能快速明白当时的改动意图这对长期维护尤其重要。另外如果在一篇文章的撰写过程中你做了多次修改可以尽量把相关改动合并到一次 commit 里而不是每改一小段就提交一次。提交粒度太碎会让历史记录显得杂乱粒度太粗又不利于后期定位问题。我自己一般是一篇文章对应一个 commit一次样式调整对应一个 commit。5.2 用 git status 和 git log 掌握仓库状态两个命令建议常备git status这个命令用来查看当前工作区的状态比如哪些文件被修改了、哪些文件还没被跟踪。每次提交前跑一下能有效避免把不想提交的文件漏进去或者多提交。git log --oneline这是查看提交历史的浓缩模式每一行是一条记录包含提交 ID 和说明。想查看某次提交具体改了什么文件可以加上--stat参数或者直接用git show commit-id查看详情。实际维护博客时我经常用git diff查看尚未暂存的改动内容确认这次改动没有夹带一些意外内容。比如有时候在草稿里复制了一段测试代码提交前通过git diff会发现及时清理掉避免把草稿污染进正式文章。5.3 提交信息写错了怎么办git commit --amend写 commit 说明时手滑打错字是常有的事或者提交完发现漏掉了一个文件又或者想调整一下上次提交的信息。这时候不需要回滚重建提交Git 提供了git commit --amend命令。它的作用是把当前的暂存区内容与最近一次提交合并并允许重新编辑提交信息。用法是git commit --amend不带-m参数时会进入编辑器让你修改提交说明。如果想直接指定新的提交说明可以写成git commit --amend -m 修改后的提交说明如果漏掉了文件先git add那个文件再执行git commit --amend就能把这个文件补进上一次提交。注意--amend会改变提交的哈希值所以只适合修改“还没有推送”或者“你确定只有自己在用”的提交。如果你已经git push并且码场上只有这一条提交记录也还好如果已经推送且其他人或者你的另一台电脑也有拉取不要轻易 amend否则会导致历史不一致。5.4 多目录同步写作的 worktree 技巧这个技巧属于进阶内容我接触大部分博客作者后真正用得上的人不多但用起来是真的方便。场景是这样的你同时维护两篇文章一篇是长文一篇是短笔记每次切换还要保存当前工作区的状态或者用暂存区反复切换很费劲。git worktree可以让你在同一个仓库下创建多个工作目录每个工作目录可以独立切换分支、编辑和提交。常用命令如下git worktree add ../blog-draft draft这会在博客目录的同级创建一个新目录blog-draft并自动创建一个名为draft的分支。在这个新目录里你可以自由写文章、提交不会影响原本的仓库目录。两个目录的数据最终都会推送到同一个远程仓库。需要用完移除时执行git worktree remove ../blog-draft用这个功能的时候有一个注意点同一时间同一个分支不能同时在两个 worktree 中被检出这个是 Git 的保护机制避免两个目录对同一分支写入造成冲突。所以正确用法是每个 worktree 绑定独立分支最后再合并或推送。我个人的习惯是正常的文章更新都在主目录做只有临时想开一篇长草稿、但又不想污染当前工作分支时才用 worktree 开一个新分支去写。写完后合并回主分支清理 worktree整个过程很干净。6. 高频报错与实战避坑这些问题我全踩过6.1 fatal: not a git repository八成是你跑错了目录这个报错的完整形态是fatal: not a git repository (or any of the parent directories): .git热词榜上高频出现原因很简单你在一个还没有执行过git init的目录里执行了git status或者git log等 Git 命令。解决办法也很直接先确认当前路径是否在博客仓库目录内执行pwd查看当前路径或者进入仓库目录后再执行命令。另一种常见情况是你明明在仓库目录下却仍然报这个错那多半是.git文件夹被误删了或者磁盘文件系统不支持隐藏目录的正常读取。此时只能重新git init然后重新添加远程地址。6.2 login failed. check api token or gitlab version这是 IDE 在报错如果你用 IDEA、VS Code 这类 IDE 的 Git 插件提交代码时突然弹出login failed. check api token or gitlab version. log in via git if the version这样的错误这不是 Git 本身的问题而是 IDE 的 Git 插件常见于 GitLab 集成插件无法用 API token 连接你的代码托管平台。常见原因有三个一是你用的 IDE 版本较老插件使用的 API 版本和平台不兼容二是平台后台改过账号密码或 Token本地存的凭据过期了三是你连接的地址类型不对插件的 API 功能和 SSH 地址不兼容。解决办法我建议分三步走先检查 IDE 的 Git 远程地址是否用的是 HTTPS如果是可以改用 SSH 地址然后到 IDE 的凭据管理或插件设置里删除旧的 Token 后重新登录最后如果问题依旧直接关掉 IDE 自带的 Git 集成功能改用 Git Bash 操作这是最稳定的方案。实际上遇到这种和 IDE 绑定的问题我不太建议继续在 IDE 里折腾命令行永远是最可靠的兜底方案。6.3 推送被拒与中文路径显示乱码推送时经常见到的报错是! [rejected] master - master (fetch first) error: failed to push some refs to ...这个报错是因为远程仓库里有你本地不存在的提交记录最简单的解决方式有两种如果远程仓库是空的或者你来管理可以直接用git push origin master --force强制覆盖但要注意这会丢弃远程已有的提交。更规范的做法是执行git pull origin master --rebase拉取远程提交并变基到本地最新然后再推送。我在博客实际维护中很少遇到这种情况因为博客仓库只有我一人开发但如果你误操作在码云网页上改过文件或者点击过“初始化仓库”导致生成了一次自动提交就会触发。最稳妥的做法还是第 6.1 节提到的创建仓库时保持空白。另外一个常见的“看起来像报错其实不是”的问题是中文文件名或中文路径显示成转义字符。比如\344\270\255\346\226\207.txt这是 Git 的默认转义行为不是文件损坏。解决方式是在 Git Bash 中执行git config --global core.quotepath false之后中文就能正常显示了。这也就是为什么你会在很多 IDE 的提交日志里看到类似git -c core.quotepathfalse这样的参数——那是 IDE 在替你把这个选项临时打开。同理-c diff.mnemonicprefixfalse是为了关闭某些 IDE 在 diff 中对文件名前缀的缩写--no-optional-locks是为了避免提交过程中产生额外的锁文件。这些参数对普通用户来说不深究也没关系IDE 已经帮你处理好了。6.4 聊聊“码云账号被封”的几个常见原因热词里出现“码云账号被封”我猜很多朋友自己或者身边的人遇到过这里有必要说一下我观察到的规律。对于自建博客的用户来说账号被封通常和这几类操作有关仓库里存放了违规内容需要特别注意公开仓库的内容是任何人都能访问的不要把你的笔记、截图、密钥等隐私信息传到公开仓库也不要托管任何不当内容大量创建空仓库或者测试仓库被平台风控识别为恶意行为长期不活跃被系统判定为无效账号。另外如果你在注册时使用了不符合平台规则的信息也可能会被锁定。我个人踩过一次这样的坑早期为了测试自动化脚本一天之内创建了几十个空仓库结果第二天账号后台提示异常需要申诉才解锁。如果你规划尚不明确不要急着大量建仓库一个博客项目一个仓库就够等真正需要时再建。注意如果你确实遇到了账号异常正确的处理方式是走平台官方申诉通道提供注册信息和身份证明等待审核。不要在网络上轻信所谓“内部解封”的信息尤其不要提供任何密码或验证码给第三方。6.5 关于 git clone 和“目录泄露”的提醒热词里还有一个“git目录泄露如何下载”这其实是一个安全话题当网站部署时不小心把.git目录也传上了服务器任何人访问你的域名/.git/config就能看到仓库地址、分支信息甚至可能通过特定工具下载整个仓库源码。在自建博客的场景下这通常是因为部署时把整个项目目录包括.git直接同步到服务器导致的。这里明确提醒如果你用 FTP 或 rsync 部署博客一定要排除.git目录如果你用的是码云 Pages 或 CI/CD 自动构建部署一般不会出现这个问题因为构建产物里没有.git。另外这也解释了为什么你的博客源码即使托管在私有仓库也需要持续保持仓库本身的安全性——不要把服务器私钥、数据库密码等敏感信息以任何形式提交到仓库中即使仓库设为私有也要避免这类信息入库因为云端的仓库如果有任何意外暴露这些秘密就等于公开了。我见过不止一个人把.env文件推到码云然后发现服务器数据库密码泄露的事故。.gitignore一定要好好维护。回到部署本身如果你是本系列前两篇推荐的构建工具部署时用构建产物目录而不是用整个仓库目录这个问题就迎刃而解。6.6 我自己的日常避坑清单最后把这几年维护博客仓库的一些小经验整理成一个速查清单当作这篇实战内容的收尾推送到码云之前先在本地git status确认没有把密钥、日志、依赖包目录误加进去。至少保存一份完整的 SSH 私钥备份在安全位置换电脑时直接复制到新机器的~/.ssh/目录并设置权限即可不用重新生成再更新。如果换了新电脑或者在别人电脑上操作记得检查一下 Git 的全局用户名和邮箱避免用别人的身份提交了你的内容。定期清理.git目录里的对象数据库博客仓库如果提交次数很多可以用git gc这个命令压缩历史对象来瘦身。每次写完文章、推送完成之后建议在码云网页端瞄一眼仓库文件列表确认没有意外改动。Git 这东西初学时会觉得命令很多、概念抽象但它本质上就是一个“保存现场”的工具。你在本地写文章、改样式时觉得它烦等到某天误删了文件、或想把半年前写过的一段配图方案翻出来时你会感谢当初每一个写清楚了说明的 commit。码云在这个过程中扮演的角色就是那个“异地备份统一入口”让本地仓库和云端的同步成为习惯之后博客维护就可以彻底告别“文件拷贝来拷贝去”的原始时期了。下一篇我们会顺着已经推送到码云的代码聊如何让博客在服务器上实现自动化更新——也就是 push 之后服务器自己拉取、自己构建、自己生效省掉每次手动 SSH 上去执行的步骤。到时候你会发现前面配置这些底层的路径每一步都没白走。