说实话我当年第一次用 FTP 往博客服务器传文件时干过一件蠢事改主题配置之前忘了备份手一抖把原来的文件覆盖了刷新网页直接变成白屏。更气人的是本地也只剩那份改坏的版本想回退都无从下手。后来老老实实把博客源码纳入了 Git 管理这种惨剧再也没发生过。这篇博客自建指南的第三篇专门讲代码托管这环——Git 入门和码云实战。文章会从 Windows 下的 Git 安装讲起一直讲到你本地的博客源码真正推送到码云仓库最后顺手把新手时期最容易踩的坑一起排掉。适合给那些刚把静态博客生成器跑起来、但对版本管理还一知半解的朋友。1. 为什么博客写得好好的非要把代码交给 Git 管1.1 博客一旦进了 Git等于有了后悔药写博客这种事改稿子、换主题、调样式是家常便饭。今天觉得这个布局好看过两天又嫌它啰嗦想改回第一版的样子。这时候没有版本管理的博客就只能靠手动备份——把整个文件夹复制一份改个名加个日期戳当缓存。问题在于人是有惰性的备份这件事很容易被跳过等你真正需要回退的时候才发现上一版早就被覆盖了。Git 解决的就是这个痛点。它会在你每次提交时给整个项目拍一张快照记录当时的文件内容并配上说明文字。想找哪个时间点的版本都能翻出来想对比两个版本之间的差异也可以。尤其静态博客这种项目主题配置、文章源文件、部署脚本每天都在变没有版本历史打底很多改动都是拆东墙补西墙。把博客源码交给 Git 之后所有操作都变成可追溯的等于花钱买了一份后悔药而且这份药还是免费的。1.2 本地存一份云端存一份代码丢不了版本管理的另一个被忽视的价值是异地备份。硬盘损坏、电脑丢失、误删文件夹这些事在别人身上听到总觉得遥远真落到自己头上才明白什么叫欲哭无泪。代码托管平台的存在让本地之外永远多一个远端副本。改完代码本地提交一次再推送到码云即使本地整个目录被格式化重新 clone 一份下来就满血复活。多设备写作也是个刚需。白天在公司台式机上写了一半的文章回家想在笔记本上继续没有远端仓库就只能在两个设备之间用 U 盘来回拷拷贝的过程中还容易弄混到底哪份是最新的。有了 Git 托管换设备只需要 clone 或 pull手头写到哪了无缝接续这个体验一旦用上就回不去了。1.3 这篇的适用范围与前置条件这篇指南面向的是从零开始接触 Git 的新手默认你对版本管理没有任何概念。如果你已经会基本的 add、commit、push可以直接跳过第 2、3 节重点看第 4 节的码云配置和第 6 节的报错排查。前置条件只有两个一台 Windows 电脑和一个能正常访问网页的浏览器。浏览器用来注册码云账号和下载 Git 安装包具体跑博客的生成工具本篇不展开那是这一系列里其他章节要讲的内容这篇只负责把代码托管这条链路彻底打通。2. Windows 上装 Git 的完整流程与基础配置2.1 下载安装包时的版本选择细节先说下载渠道直接去 Git 官网 git-scm.com 的 Downloads 页面下载不要在第三方下载站找。第三方站点经常打包旧版本还可能顺手推荐一堆推广软件下载完还要跟捆绑安装的杂七杂八的东西斗智斗勇纯属给自己找麻烦。进入官网后会看到 Windows、macOS 和 Linux 等平台的选项。Windows 下一般选 64-bit 版本就行现在绝大多数电脑都是 64 位系统。怎么看系统位数右键“此电脑”选“属性”在弹出的窗口里能看到“系统类型”写着“64 位操作系统”就可以放心选 64-bit 安装包。下载完成后得到一个 .exe 文件双击运行。安装界面是全英文的新手最容易在这里被劝退但其实绝大部分步骤保持默认即可真正需要留神的只有几个关键页面下面逐个说明。2.2 安装向导里的关键勾选项安装向导的前几步都可以一路 Next但有三处建议停下来看两眼。第一处是 Select Components选择组件默认勾选的基础组件已经够用了但建议额外确认“Git Bash Here”和“Git GUI Here”这两项被勾上。勾选之后鼠标右键菜单里会多出“Git Bash Here”的入口后面几乎所有 Git 操作都要从这个入口打开终端这一个小设置能省很多事。第二处是 Choosing the default editor默认编辑器。Git 默认选 Vim如果你过去没碰过 Vim强烈建议换成 VS Code 或 Notepad。原因是以后执行 git commit 时如果忘记加 -m 参数Git 会弹出编辑器让你补写提交说明Vim 的交互逻辑对新手非常不友好很多人第一次被卡在里面不知道怎么退出。换成熟悉的编辑器这个坑就直接绕过去了。第三处是 Adjusting your PATH environment调整 PATH 环境变量务必选择中间那项“Git from the command line and also from 3rd-party software”。选了它Windows 自带的 CMD 和 PowerShell 里也能直接敲 git 命令不用后期再手动配置环境变量。还有一处关于行尾换行的选项英文叫 Line Ending Conversions选默认的“Checkout Windows-style, commit Unix-style line endings”就行。这个选项处理的是 Windows 的 CRLF 和 Linux 的 LF 两种换行符之间的转换博客项目以后大概率要部署到 Linux 服务器上默认值已经把这个坑填平了不要动它。2.3 装完必做的三项基础配置安装完成后在任意文件夹里右键选择“Git Bash Here”会弹出一个黑色终端窗口看起来像 Linux 的 shell。我建议后续所有 git 命令都在这个环境里执行它支持自动补全和更友好的粘贴行为比 CMD 舒服得多。第一项必做配置是告诉 Git 你的身份。不配置也能运行命令但提交记录里会没有作者信息代码托管平台也没法把提交关联到你的账号。执行git config --global user.name 你的名字 git config --global user.email 你的邮箱邮箱务必填注册码云时用的那个这样提交记录能直接关联到码云账号。user.name 填昵称或真名都行它显示在提交历史上。第二项是确认安装成功执行git --version能输出类似 git version 2.xx.x 的版本号说明 Git 装好了。第三项配置解决中文显示问题。博客文章涉及大量中文文件名Windows 下 Git 默认会对中文路径做转义处理导致 git status 里看到一堆形如“\345\210\206...”的八进制乱码。执行git config --global core.quotepath false这样中文文件名就能正常显示了否则每次看改动列表都跟看天书一样。顺带提一句 Git 小乌龟也就是 TortoiseGit。它是 Windows 下的图形化 Git 客户端装好后在文件夹右键就能看到“Git 提交”“Git 拉取”等菜单对不想碰命令行的人很友好。但我还是建议第一遍学习时老老实实用命令行过一遍把 add、commit、push 三个动作分别干了什么搞清楚之后再上图形界面会轻松得多。小乌龟更适合作为日常更新时的快捷键不适合作为入门的替代品。3. 从零到一Git 本地仓库的核心命令链3.1 工作区、暂存区、版本库的比喻这三个概念是 Git 入门时最容易懵的地方。我用一个改稿子的场景来类比工作区就是你的书桌上面摊着正在写的稿子想改哪页就改哪页暂存区相当于书桌上的一个待办盒你从书桌上挑出几页准备正式提交的稿子放进盒子还没准备好的继续留在书桌上版本库则是一个带锁的档案柜每隔一段时间你把待办盒里的稿子整理成一本档案锁进柜子里并贴上标签说明这本档案记录了什么。对应到命令上git add 是把文件放进暂存区git commit 是把暂存区里的内容正式归档成一条提交记录。新手总想不通 add 和 commit 为什么要分两步这个设计其实很灵活——你可以一次改十个文件但只提交其中两个另外八个还在草稿状态不会被误收入本次快照。等以后文章越写越多你会越来越感激这层缓冲。3.2 建仓、提交、查看历史的完整流程在博客源码所在的目录打开 Git Bash执行git init这个命令会在当前目录下生成一个隐藏的 .git 文件夹仓库的完整历史都记录在里面。注意这个命令只需要执行一次之后无论怎么改文件都不用重新 init。执行完 git init仓库还是一个空壳里面没有任何文件被跟踪。接着建议新建一个说明文件 README.md内容随便写点博客简介。建好之后执行git status终端会显示当前仓库的状态里面能看到未跟踪文件的列表也就是 Git 还没管理的文件。下一步把它纳入管理git add README.md git commit -m 初始化仓库commit 后面的 -m 参数是提交说明一定要写得像人话。比如“新增文章Git 入门实践”“修复导航栏在移动端不显示的问题”都比干巴巴的“update”强得多。三个月后翻提交记录看到“update”只会一脸茫然完全想不起来当时改了什么。之后进入常规节奏就很简单了改文件、git add、git commit循环往复。想看历史用git log输出信息比较长习惯之后可以加参数精简git log --oneline每条记录会显示一个提交编号、作者、日期和提交说明。提交编号是一串哈希值相当于提交记录的唯一身份证。3.3 写错了怎么办commit --amend 与回滚思路提交说明写错字或者刚提交就发现漏了一个文件这时 git commit --amend 是最顺手的工具。amend 的意思是修补上一次提交git commit --amend -m 正确的提交说明执行后上一条提交记录的说明被替换成新内容而且不会新增一条记录历史看起来就像从开始就写对了一样。需要提醒的是amend 只能改最近一次提交。想改更早的历史不是不行但对新手来说复杂度会陡增建议等对 Git 的理解到位了再碰。另一种常见情况是文件提交错了想撤销。Git 的撤销机制分层很多最容易理解的场景是文件已经 git add 进了暂存区但还没 commit。想把它从暂存区退出来执行git reset HEAD 文件名如果已经 commit 但还没推送远程可以用git reset --soft HEAD~1--soft 表示保留文件改动只撤销提交记录。这在想拆分一次提交或重写提交说明时很实用。注意这段话里说的都是本地操作。一旦提交已经推送到远程仓库就不要再轻易用 reset 了后续会引出更复杂的同步问题第 6 节会细讲。4. 码云实战注册、建仓、SSH 密钥与第一次推送4.1 为什么选码云而不是别的托管平台对个人博客项目来说选码云Gitee有个非常现实的原因访问速度。它在国内部署的节点多clone 和 push 的时候不会出现国外平台那种时快时慢的卡顿感。界面全中文对第一次接触代码托管的新手非常友好每个按钮是什么功能一目了然。而且免费用户就能创建私有仓库博客源码不想公开时藏在私有仓库里正合适。另一个关键原因是后续的博客部署。静态博客最终生成一堆 HTML、CSS、JS 文件需要一个能公网访问的地方把它们托管起来码云自带的 Pages 服务就能把仓库里的静态文件直接发布成网站。虽然现在还用不到但选平台时提前把这个因素考虑进去后面联动会是顺手的事。4.2 创建远程仓库时的参数选择注册码云账号的过程不赘述登录后点击右上角的“”号选择“新建仓库”。创建页面里几个关键字段要注意。仓库名称给英文小写比如 my-blog-source 或 myblog以后 clone 时要靠它定位别用空格和中文免得后面命令行操作时出麻烦。仓库路径会自动根据名称生成不用改。开源许可证这一项直接选“不使用”个人博客源码没有必要给自己套一长串法律文本。重点说一下初始化仓库的选项。如果你是按第 3 节在本地已经建好仓库了这里不要勾选“使用 Readme 文件初始化这个仓库”。因为平台一旦生成了初始提交本地和远程各有一条互不相干的历史第一次推送时会被拒。反过来如果你是第一次创建仓库、本地还没来得及建仓那就可以勾选初始化选项之后直接 clone 下来用省得手动建仓。仓库类型上博客源码建议选私有因为里面可能包含主题配置文件、未发布草稿等不想被人随意看到的内容。以后要公开的是构建后生成的静态站点仓库而不是源码仓库。4.3 SSH 密钥配置免密登录的关键一步在码云上做代码托管最推荐走 SSH 协议而不是 HTTPS。HTTPS 每次 push 都要输用户名密码即使系统能帮你记住一段时间换一台设备又得重新验证。SSH 配好之后至少这台电脑上推送、拉取全程不需要再输入账号密码。第一步在本地生成密钥对。打开 Git Bash执行ssh-keygen -t rsa -b 4096 -C 你注册码云的邮箱-t rsa 指定密钥类型为 RSA-b 4096 表示密钥长度 4096 位-C 是备注信息。执行后终端会提示保存路径直接回车用默认的 ~/.ssh/id_rsa 即可。接着会问 passphrase如果设置每次使用私钥都要输入一次类似给私钥再加一道锁。个人电脑上为了日常便利直接回车留空就行。生成完成后查看公钥内容cat ~/.ssh/id_rsa.pub终端会输出一大段以 ssh-rsa 开头的内容这就是公钥。把整段内容复制下来包含最后的邮箱备注。第二步登录码云后台进入“设置”-“安全设置”-“SSH 公钥”页面把复制的内容粘贴进去标题写个“我的 Windows 电脑”之类方便识别的名字保存。之后验证连通性ssh -T gitgitee.com首次连接会询问是否信任该主机输入 yes 回车。如果看到欢迎语并带出你的码云用户名说明 SSH 链路已经通了。至此你这台电脑和码云之间建立了免密连接。4.4 本地关联远程仓库并完成首次推送这里分两种情况。情况一本地还没有仓库直接从码云克隆。在仓库首页点击“克隆/下载”选择 SSH 地址复制下来。回到 Git Bash 执行git clone gitgitee.com:你的用户名/仓库名.git执行后当前目录下会出现一个与仓库同名的文件夹里面已经包含 README 和完整的 Git 配置直接在这个目录里开始写博客即可。情况二本地已经按第 3 节建好了仓库需要手动关联远程地址git remote add origin gitgitee.com:你的用户名/仓库名.gitorigin 是远程仓库的默认别名之后 push 和 pull 直接用这个别名指代那一长串地址。关联完成后把本地内容推送到远程git push -u origin main分支名要留意新建的 Gitee 仓库默认分支可能是 main也可能是 master取决于创建仓库时的默认设置。拿不准就先看仓库首页的分支标签或者执行 git branch 看本地分支名保持一致就行。第一次推送到空仓库会非常顺畅。如果之前不小心勾了初始化选项导致推送被拒先执行git pull origin main --allow-unrelated-histories这个参数允许两条没有共同父节点的提交历史合并属于“本地初始化过 远程也初始化过”场景的标准解法。合并完若有冲突解决冲突后再 push。5. 博客日常更新的标准工作流与免密优化5.1 一天一篇的更新节奏怎么安排很多自建博客的人热情在前两周烧完之后断更。原因往往不是没内容写而是操作流程太碎每次写文章前还得回忆一遍命令积累了几次之后就懒得打开了。给自己定一个固定模板能明显降低启动成本。我自己写一篇博客文章的流程是这样的在源码目录下新建一个 posts/日期-标题.md 文件正文写完后打开 Git Bash 执行三连git add . git commit -m 新增文章标题 git push origin maingit add 后面跟英文句点表示把当前目录下所有改动一次性加入暂存区。这个命令会把删除操作也记录下来所以临时文件或垃圾文件先清理干净再执行或者先看一眼 git status 确认要提交的内容有没有夹带私货。习惯之后每天花在版本管理上的时间不超过三十秒这个成本低到不会形成心理负担。5.2 免密推送的日常体验优化SSH 密钥配好后push 和 pull 已经不需要输任何密码这是我最推荐的方案第 4 节的配置一步到位。但如果你因为某些原因用的是 HTTPS 地址比如 clone 时手滑复制了 HTTPS 链接Windows 下也可以通过凭据管理器把密码保存下来方法是执行git config --global credential.helper manager第一次输入密码后会写入 Windows 凭据库之后也不用重复输入。需要理解的是SSH 免密和 HTTPS 凭据存储是两套机制SSH 靠密钥对做机器级别认证HTTPS 靠系统保存密码。个人体验上 SSH 更干净毕竟密钥一旦生成就和这台机绑定了而凭据偶尔会失效换个 Windows 账户或密码过期又得重新验证一次。能走 SSH 就走 SSH。5.3 多用分支少踩坑博客源码与静态文件分开管个人博客建议维护两个仓库一个存博客源码包括文章、主题、配置文件一个存生成后的静态文件也就是构建工具吐出来的 HTML、CSS、JS。两个混在一起的话每次构建都会产生几十上百个文件变动提交历史很快被覆盖真正想看文章修改记录时反而找不到重点。分支策略上单人维护博客保持一条主分支就足够不需要为了用 Git 而强行搞 Git Flow 那套复杂模型。但有一个命令值得了解git worktree。它允许你同时在不同的目录下检出同一个仓库的不同分支适合那种“新分支写着长文旧分支突然来了个紧急修复”的场景。基本用法git worktree add ../blog-fix fix-branch这个功能在博客这种低频更新项目里使用率不高但知道有这回事遇到多分支并行时就省得来回切换目录。如果你用 VS Code 或 JetBrains 系 IDE左侧的源代码管理面板其实已经封装了 add、commit、push能看到每个文件的改动详情填完提交说明点一下对勾就完成提交。适合不喜欢进终端的人但前提是已经理解了底层的命令逻辑不然出了问题根本不知道怎么排查。6. 高频报错的排查链路与应急修复6.1 fatal: not a git repository 的根因与处理这条报错基本每个新手都会撞到一次完整信息是fatal: not a git repository (or any of the parent directories): .git意思很直白当前目录不是 Git 仓库向上查找父目录也没找到 .git 文件夹。常见原因有三个。一是你还没在这目录里执行过 git init二是 Git Bash 打开后当前路径跑到了其他位置比如落在了用户主目录三是克隆下来的仓库文件夹内部结构被改动弄丢了 .git 目录。排查链路很固定先执行 pwd 确认当前路径是不是博客源码目录不是就 cd 过去是但还是报错就执行 ls -a 看看有没有 .git 文件或文件夹。注意 ls -a 必须加 -a 参数.git 是隐藏项不加才看到。如果确实没有 .git那就重新 git init 一次从头来。6.2 push 被拒远程已有文件的冲突push 时遇到! [rejected] main - main (fetch first)说明远程仓库里有本地不存在的提交或文件。常见原因就是之前创建仓库时勾了初始化选项或者后来在网页上直接编辑过仓库文件。处理办法是先把远端内容拉下来git pull origin main如果两条历史互不相干报错会提示需要 --allow-unrelated-histories加上即可。合并后解决冲突重新 push。如果确认远程仓库刚创建、里面没有任何有价值内容也可以用强制推送git push -f origin main但 -f 会直接覆盖远程历史强推前务必想清楚。我的原则是远程有不想丢的提交时永远别强推远程只是空壳时才考虑强推。6.3 commit --amend 的典型适用场景与一个隐藏坑第 3 节提过 amend 的改法这里补充一个最容易踩的坑如果这次提交已经 push 到远程仓库再执行 amend 会怎么样答案是本地提交编号变了远程还留着旧编号下次 push 会被拒绝。这时候要么强推要么先把远端旧提交拉回来再手动调整。个人博客单机环境下强推问题不大但如果你已经用多台电脑同步博客强推可能会让另一台设备上的记录变乱。所以我给自己定的规矩是commit 推送到远程之前先认真检查说明文字一旦推送了就不再用 amend 去改它宁可下次再补一个 commit。补传漏掉文件时amend 配合 --no-edit 很好用git add 漏掉的文件 git commit --amend --no-edit--no-edit 表示沿用原来的提交说明不弹出编辑器。执行后上一次提交的内容就把漏掉的文件包含进去了历史里完全看不出曾经遗漏过。6.4 几个容易被忽略的规范与安全问题最后说几句做代码托管时容易漏掉的细节。第一件.git 目录千万不要暴露到公网。博客部署时如果直接把整个目录同步到服务器其中包含的 .git 文件夹就等于把全部历史提交交了出去包括你可能写错后又删掉的草稿和隐藏配置。部署前要确认发布工具默认忽略了 .git或者干脆手动删掉再发布。第二件仓库里不要提交敏感信息。数据库密码、云服务密钥这类内容一旦进入 Git 历史即使后面删掉仍然残留在历史提交里几乎不可能彻底清除。个人博客常见的坑是站点部署配置里写了服务器密码这类文件要提前用 .gitignore 排除而不是指望自己下次“记得不提交”。第三件账号如果出现异常状态先别慌去注册邮箱找平台通知按邮件说明提交反馈或申诉。正常情况下普通用户正常提交代码、使用 Pages 服务不会遇到问题守住底线就没什么可担心的。6.5 给系列下一篇留个钩子代码托管这关过了博客的地基就算打完了。到这里你已经能把文章写成 markdown 文件用 Git 管好每次修改再通过码云把内容同步到云端。下一篇我准备写博客生成与 Pages 发布的正题讲清楚构建命令、发布目录和码云 Pages 的绑定流程。到时会发现这一篇里推上去的仓库正好是下一步部署的原料。我自己当初从 FTP 裸奔切换到 Git 工作流之后最大的感受不是功能多酷炫而是心里踏实了。改坏能回滚换电脑不用拷 U 盘有时断更几周捡起来翻一眼提交记录就马上知道自己写到哪一步。这种踏实感比单纯掌握了几条命令重要得多也值得你在自建博客的早期就认真打好底子。