个人博客自建指南3代码托管——Git 入门与码云实战写这个系列的前两篇时我把博客从零搭到了能本地跑通的阶段框架、主题、第一篇内容都已经就位。但很多跟着做的人会卡在同一个地方代码全在本地改个样式、写篇新文章心里总是没底——万一电脑坏了怎么办改出一堆问题怎么回滚换台电脑想接着写怎么办这篇就专门解决这个问题。我选了两个工具版本控制软件 Git以及国内的代码托管平台码云Gitee。前者是管理代码版本的事实标准后者是目前国内最顺手、速度也最稳的托管平台。文章会从 Git 的核心概念讲起一直讲到码云上建仓库、本地推送、日常更新再到各种报错的排查思路。适合刚接触 Git 的博客搭建新手也适合那些用过但一直没把原理搞明白的朋友。1. 整体思路为什么博客要上 Git 和码云1.1 版本控制解决的不只是“备份”问题很多人觉得博客就是一堆静态文件传到服务器或者托管平台上就行没必要搞版本控制。但真的做过几个月的博客就会明白写作和改版是个持续迭代的过程——今天觉得这个配色好明天又想换回之前的这篇文章写了一半想推翻重来某个插件配置改坏了却忘了原来是什么样。Git 解决的就是这类“后悔药”问题。它会把每次修改都记录成一个提交commit每个提交有完整的时间线、作者信息和修改内容。这意味着你可以随时回到任何一个历史版本对比任意两次修改的差异甚至把某次改动单独找出来。这些能力不是一个压缩包备份能做得到的。另一个容易被忽略的点是Git 是目前几乎所有开发协作场景的基础设施。博客虽然是个人项目但学一遍 Git 的常用操作后面无论参与开源项目还是团队协作都能直接上手。你在自己的博客项目上练习 Git试错成本为零这是最理想的入门场景。我见过不少朋友第一反应是“我用网盘备份不就行了”实测下来远远不够。网盘只能解决“文件丢了”的问题解决不了“文件改坏了想回滚”“想对比两个版本差异”“每次更新内容完整记录”这些问题。用 Git本质上是把“备份”升级成了“版本管理”这两件事的差距非常大。1.2 代码托管平台怎么选为什么是码云有了 Git 之后代码还是在本地的 Git 仓库里它和普通文件的区别在于有了版本历史。但如果始终留在本地就只解决了回滚和对比的问题没解决多端同步和异地备份的问题。托管平台的作用就是给 Git 仓库提供一个远程存放地。常见的选项有 GitHub、GitLab、Bitbucket还有国内的码云Gitee。从我的实际体验来说个人博客项目选择码云有几点很现实的好处。首先是访问速度。码云的服务器在国内clone、push、pull 的速度体感上是几十毫秒级别基本是瞬时完成。而 GitHub 在国内的访问速度本身就不稳定push 大一点的仓库时经常卡住这对于每次更新博客来说是非常影响体验的。其次是私有仓库免费。博客在发布前可能需要放草稿、放未完成的内容有些私人项目也不想公开。GitHub 的私有仓库虽然也免费了但个人使用起来码云的策略更宽松数量上没有心理负担。第三是社区环境更贴近国内用户。码云上的中文资料、开源项目、Gitee Pages 静态托管服务对于写中文博客的人来说生态配套更完整。后面如果需要做博客的自动部署码云也提供对应的 WebHooks 等功能衔接起来没有障碍。当然这不是说你不能多平台同步。一个本地仓库推送到多个远程平台是完全支持的你完全可以同时用码云做主力、GitHub 做国际备份。这个后面我会在推流配置里提一下但主线会以码云为准。2. Git 安装与环境配置一步都不能少2.1 不同系统下的 Git 安装方式在开始操作前先确认你的电脑里有没有 Git。Windows 用户可以在开始菜单里输入git看是否能找到 Git BashmacOS 和 Linux 用户可以在终端里输入git --version试试。如果没安装分系统处理Windows 用户直接去 Git 官网下载安装包。下载的时候注意选择对应系统架构64 位还是 32 位安装过程一路默认即可但有一个地方建议改一下在选择默认编辑器那一步如果你会用 Vim保留默认如果对 Vim 不熟建议选成 Notepad 或者 VS Code否则后面写提交信息时会卡在 Vim 界面里进退两难。macOS 用户建议先装 Homebrew然后用一条命令安装brew install git。这样装的是当前最新版本后续升级也方便。如果不方便装 Homebrew去官网下 pkg 安装包也行只是升级要自己处理。Linux 用户用系统自带的包管理器即可Ubuntu/Debian 是sudo apt install gitCentOS/RHEL 是sudo yum install git。装完记得验证一下git --version能看到版本号就说明装好了。安装完成后Windows 用户建议在开始菜单里打开 Git Bash这是一个模拟 Linux 环境的终端操作体验比 CMD 舒服得多。后面文章里所有的命令示例都是基于 Git Bash 的。2.2 全局配置用户名、邮箱和换行符Git 装好后有两项配置是必须做的因为每次提交都会记录作者信息没有它 Git 会拒绝提交。在终端里依次执行git config --global user.name 你的名字 git config --global user.email 你的邮箱注意这里的邮箱不一定要真实存在但建议用一个你常用的邮箱因为很多平台会根据提交邮箱关联账号。比如你将来在码云上开源项目别人看到的提交记录里显示的就是这个邮箱。还有一个很多人踩坑的地方是换行符。Windows 用 CRLF回车加换行Linux/macOS 用 LF仅换行。如果设置不对你可能会在 diff 里看到一整片文件都被标记为修改很恼人。推荐设置git config --global core.autocrlf true # Windows 用户 git config --global core.autocrlf input # macOS/Linux 用户core.autocrlf true的意思是提交时把 CRLF 转成 LF 存进仓库检出时自动转回 CRLF。这样在 Windows 上编辑正常仓库里保存的是标准 LF跨平台协作不会出问题。2.3 SSH 密钥让推送不再输密码每次 push 都输密码虽然也能用但输多了真的很烦。更麻烦的是很多平台的密码验证已经在逐步收紧推荐的方式是 SSH 密钥认证。配置一次之后就不用再管密码了。生成密钥的命令ssh-keygen -t rsa -b 4096 -C 你的邮箱执行后会有几个询问直接按回车用默认路径就行密码建议直接留空即直接按回车。如果设置了密码每次使用密钥还要再输一遍就没有“免密”的意义了。生成完成后默认会得到两个文件私钥id_rsa和公钥id_rsa.pub。私钥留在本地绝对不能发给任何人公钥是要添加到码云账号上的。查看公钥内容cat ~/.ssh/id_rsa.pub把输出的内容整段复制下来下一步在码云里配置。3. 码云实战从建仓到日常发布的完整流程3.1 在码云创建远程仓库码云的网址是 gitee.com注册并登录账号后点击右上角的“”号选择“新建仓库”。创建仓库时有几个选项需要注意。仓库名称建议和你本地的博客目录名保持一致方便对应。比如我的博客目录叫my-blog仓库名也写my-blog。这纯粹是管理上的便利没有强制要求。路径Path会自动根据名称生成这个是仓库的访问路径如果名称有中文建议手动改成英文。开源还是私有取决于你的博客内容。如果博客文章公开后不想让人直接看到源码里的草稿选私有仓库如果希望别人能 fork 你的博客模板、或者用 Gitee Pages 部署公开站点选开源。这里提醒一下码云对开源仓库的数量没有限制私有仓库对个人用户也是免费的所以这个选择比较自由后续也可以随时改。初始化仓库那个选项建议勾选“使用 Readme 文件初始化这个仓库”。这样远程仓库会有一个初始的 README 文件后面如果本地仓库和远程仓库的历史记录没有关联点首次推送时处理起来会容易一些。创建完成后仓库页面会显示一个远程地址形如https://gitee.com/你的用户名/my-blog.git或gitgitee.com:你的用户名/my-blog.git。这里有两种协议HTTPS 和 SSH。用了 SSH 密钥后建议统一用 SSH 地址因为免密、速度也更快。3.2 配置 SSH 公钥打通本地与码云进入码云官网后登录账号点击右上角头像进入“设置”——“安全设置”——“SSH 公钥”。把刚才复制好的id_rsa.pub内容粘贴到“公钥”输入框标题随便填一个方便识别的名称比如“我的工作电脑”点击确定。验证是否配置成功在本地终端执行ssh -T gitgitee.com如果看到Hi xxx! Youve successfully authenticated, but GITEE.COM does not provide shell access.这样的提示说明 SSH 已经通了。第一次执行时可能会提示是否信任该主机输入yes回车即可。这一步是整个流程里最容易出问题的地方。常见的情况是公钥没复制完整或者复制时多了空格和换行导致认证失败。建议用cat命令输出后手动选中整行确认以ssh-rsa开头。3.3 本地初始化仓库并完成首次推送现在进入博客项目目录执行cd ~/my-blog # 换成你自己的目录 git init这会在目录下创建一个隐藏的.git文件夹它就是你的本地仓库。但要注意这个目录下现在可能有很多文件有些是不需要纳入版本管理的比如系统的临时文件、编辑器的配置缓存、日志文件等。这时候就需要一个.gitignore文件来声明哪些文件要忽略。比如.DS_Store Thumbs.db *.log node_modules/具体忽略什么取决于你的博客框架。如果是 Hexo通常要忽略node_modules和public目录因为这两个目录可以由源码重新生成。如果是 Hugo要忽略public目录。如果你不确定可以先把所有文件加入版本管理后面发现有不需要的文件再用git rm --cached 文件名把它从版本控制里移除。然后添加所有文件并提交git add . git commit -m first commit: 初始化博客仓库这里解释一下这两条命令。git add .是把当前目录下的所有变更加入暂存区git commit是把暂存区的内容正式提交到本地仓库-m后面是提交说明。提交说明建议写清楚这次改了什么不要写“111”“aaa”这种没有意义的文字。接下来关联远程仓库并推送git remote add origin gitgitee.com:你的用户名/my-blog.git git branch -M main git push -u origin maingit remote add origin是把远程仓库地址取名为origin这是 Git 社区约定俗成的名字。git branch -M main是把本地分支名改成main因为码云默认分支名是main旧版本可能是master保持一致能省掉很多分支名带来的小麻烦。git push -u origin main是第一次推送时的标准写法-u的意思是把本地 main 分支和远程 main 分支关联起来以后只需要执行git push就行。如果仓库里没勾选初始化 README推送一般能一次成功。如果勾选了本地和远程都有了各自的首次提交Git 会拒绝推送必须先git pull origin main --allow-unrelated-histories把两边合并后再推送。这也是常见报错之一后面我会在问题部分重点说。3.4 日常更新博客三条命令搞定博客进入正常更新节奏后每天的操作基本只有三步。写完一篇新文章或者在站点配置里改了内容在项目根目录执行git add . git commit -m 新增文章xxx git push第一步是把所有变更加入暂存区。这里用了.表示“所有变更”包括新增、修改、删除。如果你只想提交某些文件可以指定文件名git add 文件路径。第二步是提交。在这里我想强调一下提交信息的习惯。好的提交信息应该能让人不看代码内容就大致知道每次改了什么。比如新增文章使用 Git 管理博客修改主题颜色并优化导航栏修复文章页面的列表样式错位这样的信息在后续回滚时会非常有用。你翻历史记录一目了然。第三步是推送。因为没有配置其他复杂流程推送成功后远程仓库就同步了你的最新变更。另外很多人会问“写了一半的文章要不要提交”。我的建议是提交。即使在草稿状态也建议提交一次提交信息里注明“草稿”。因为本地文件一旦出错、误删至少有一个可恢复的版本。但要注意如果你用的是私有仓库这个问题不大如果仓库是公开的草稿内容也会被公开那就谨慎点或者干脆用私有仓库放草稿。3.5 不想记命令用小乌龟TortoiseGit图形化操作命令行的方式其实已经很简洁了但还是有不少朋友对终端有心理门槛。这种情况下可以装一个 TortoiseGit俗称“小乌龟”的图形化客户端。TortoiseGit 是 Windows 下的 Git 图形化工具装完后资源管理器里的文件夹上鼠标右键会多出“Git Commit”“Git Push”“Git Pull”等菜单操作逻辑非常直观。比如改完文件后右键选择“Git Commit”会弹窗列出所有变更文件勾选要提交的填写提交信息点确定就行。需要注意的一点是TortoiseGit 依赖 Git for Windows装 TortoiseGit 之前必须先把 Git 装好。安装时选择不勾选“集成 SSH”如果你已经生成过 SSH 密钥勾选它反而会启用它自带的 PuTTY 密钥格式和你的现有密钥对不上。macOS 用户没有 TortoiseGit更常见的选择是 SourceTree 或 GitKraken。不过在个人博客这种简单场景下我还是推荐先学会命令行。原因是命令行在任何系统、任何服务器上都通用不会出现“离开了这个软件就不会用”的情况。图形化工具作为辅助是极好的但前期不建议过度依赖。4. 常见问题与排查技巧实录4.1 高频报错速查表实际操作中几乎每个人都会遇到几个报错。我把高频问题整理成了表每一条都是我实测过的排查思路报错信息原因分析解决思路fatal: not a git repository (or any of the parent directories): .git当前目录不是 Git 仓库或者.git目录丢失检查是否执行过git init是否在错误的目录层级下执行命令fatal: refusing to merge unrelated histories本地仓库和远程仓库的首次提交相互独立没有共同的历史点执行git pull origin main --allow-unrelated-histories后再推送Permission denied (publickey)SSH 公钥未配置或本地没有对应私钥重新检查ssh -T gitgitee.com确认为你本人后检查公钥是否完整remote: error: GE907: The repository is empty推送的分支名和远程默认分支名不一致执行git branch -M main后重新推送fatal: remote origin already exists.已经配置过远程仓库地址执行git remote set-url origin 新地址或git remote remove origin后重新添加error: failed to push some refs to ...远程有本地没有的提交通常是远程有人推了新代码或初始化了 README先git pull origin main合并再git pushlogin failed. check api token or gitlab version. log in via git if the ...通常出现在 IDE 连接 GitLab/Gitee 时API Token 过期或版本兼容问题在 IDE 设置里更新账号密码或 Token或改成本地命令行方式操作这种表格形式适合快速定位问题。实际排查时我的经验是先确认终端能正常操作命令行验证通过再排查 IDE 等其他工具的配置因为大部分“账户验证失败”类的问题根源都在凭据配置上。4.2 提交信息写错了怎么办git commit --amend很多人第一次提交时容易手滑提交信息写错或者忘了包含某个文件。这时候不需要新建一个提交去“补救”用git commit --amend就可以修改上一次提交。# 修改上一个提交的提交信息 git commit --amend -m 新的提交信息 # 或者忘了加某个文件先 add 再 amend git add 你忘了的文件 git commit --amend注意amend修改的是最近一次提交。如果你已经把这个提交推送到远程了那么amend之后提交历史就变了此时必须强制推送git push -f origin main才能同步。但这会覆盖远程的历史如果这个仓库有别人在用请跟其他人确认后再操作。个人博客项目只有自己一个作者问题不大但养成习惯很重要——公共分支尽量不用强制推送。4.3 安全意识.git目录暴露与码云账号安全这是我想单独拿出来说的一点因为很多人不太在意。如果你的仓库是公开的一旦本地的.git目录被不小心拷贝到网站的发布目录里别人就能通过特定路径把整个版本历史下载下来。Git 目录里保存的不仅是代码变更记录还有你曾经提交过的所有内容——包括你后来删除过的敏感信息。所以使用静态博客时务必确认发布目录里不能包含.git文件夹。比如 Hexo 生成的public目录它本身不是 Git 仓库但如果你把整个博客项目目录直接拷贝到服务器上就要确保.git不在 web 根目录的访问路径里。至于码云账号被封的问题也值得提醒一句。码云作为国内平台对仓库内容有严格的管理要求。如果仓库里出现违规内容、盗版资源、赌博相关代码等账号会被封禁仓库会被清空这是申诉流程很麻烦的事。个人博客项目一般不会涉及这个问题但如果你有收集整理一些边界内容到仓库里的习惯建议提前清理尽量避免这种风险。另外码云对 SSH 公钥的数量也有限制。如果你换了很多台电脑旧公钥又没删可能会提示公钥数量超限。遇到这种情况登录设置页面删掉不用的公钥即可。4.4 提升效率的几个实用功能除了日常的 add、commit、push还有几个功能是我在博客项目上经常用的提一下供参考。查看历史记录git log --oneline这会把提交历史压缩成一行行显示很简洁。如果信息很乱也可以用git log --graph看分支图谱。临时切换版本git stash git stash pop如果你正在改一个样式突然想先看看另一个分支或者旧版本的效果又不想把现在改到一半的内容提交git stash会把这些改动暂时收起来等你看完再git stash pop恢复回来。并行工作git worktree add ../blog-dev maingit worktree允许你在同一个仓库下同时检出多个分支到不同目录。比如我常用一个目录放正式发布的分支另一个目录放开发分支两个目录互不干扰。对于个人博客来说这可能有点过度设计但如果你同时维护两三个主题这个功能会很有用。4.5 远程仓库有多份的需求一台电脑管多个平台前面提到过一个本地仓库可以推送多个远程。这是一个很多人不知道但很实用的功能。比如你想同时用码云和 GitHub 做备份git remote add gitee gitgitee.com:你的用户名/my-blog.git git remote add github gitgithub.com:你的用户名/my-blog.git # 推送时指定平台 git push gitee main git push github main或者设置默认推送时同时推两个git remote add all gitgitee.com:你的用户名/my-blog.git git remote set-url --add --push all gitgithub.com:你的用户名/my-blog.git这样一来git push all main就能同时推送到码云和 GitHub。当然使用 GitHub 需要你能正常访问它这里只做配置思路的参考。平时主力还是码云备份的事情你不用操心。5. 我踩过的一些坑和心得体会写了这么多最后说点大实话。网上关于 Git 的教程非常多但大部分要么讲得太浅只教几个命令要么讲得太深长篇大论内部原理让人越看越晕。我给自己的定位是“够用就行、遇错能修”这篇的内容就是以这个为标准写的。实际写完博客一年以上你会发现高频操作确实也就这几条命令add、commit、push、pull、log、stash。把这些练熟日常开发已经能覆盖九成以上场景。但也别把“够用”理解成“不学原理”。Git 的机制其实很优雅理解了暂存区、提交、分支这三个概念后面遇到任何诡异问题你至少能判断问题出在哪个环节不会像无头苍蝇一样乱试命令。有一个细节我是在实际写博客后深有体会的提交消息就是你的“项目日记”。半年后你回看博客的提交记录看到“新增文章从零搭建个人博客”和“修改样式优化移动端适配”比看到“update”“fix”要有温度得多而且能快速定位当时的思路。写清楚提交信息这件事花不了三十秒但收益是非常长期的。另外把博客源码托管到码云后后续可以做的事情也很多。比如配合 CI/CD 自动部署每次 push 后自动构建并发布到服务器或者用 Gitee Pages 直接对外提供服务甚至可以在博客里加一个“历史版本”页面用 GitHub API 之类的能力展示文章修改过程。这些都在我后面的系列计划里。如果你在操作过程中遇到文章里没提到的问题先别慌把完整报错信息复制下来搜一下关键词通常都比盲试命令有效。版本控制是个熟能生巧的事第一次可能会折腾半小时但操作一次、两次之后它就会变成你写博客时最无感但也最可靠的一部分。