企业官网建设流程全解析

“刚接触嵌入式Linux那会儿，我手里有五个名字里带final的工程目录，每个目录里都堆着改到一半的设备树和驱动。直到有一次想回退一个串口配置，发现压缩包备份里的代码跟当前代码差了十几个提交的改动，当场就承认：搞嵌入式，版本管理真的不能靠复制粘贴目录。”

如果你也遇到过类似情况，这篇内容应该能帮到你。它围绕一条主线展开：在Linux环境下用Git管理嵌入式工程，并把它同步到GitHub做远程备份和协作。内核源码、引导加载程序、设备树、板级配置、应用的交叉编译脚本，这些都属于容易被改坏、又需要频繁回退的内容，非常适合用Git来管。文章面向的是从压缩包/共享网盘迁移过来的嵌入式开发者，也适合刚开始在Linux上写代码的学生。下面按我实际操作的顺序来写，尽量讲清楚每一步为什么这样做。

1. 为什么嵌入式要把代码交给Git

1.1 三个让人想砸电脑的瞬间

嵌入式开发的特点决定了它的代码更容易乱。第一个典型场景是“改一个配置参数，改不回去了”。比如为适配一块新的LCD面板，设备树里的时序参数来回调，今天调一组，明天调一组，到最后根本记不清哪组参数能和面板配合好。压缩包备份只能覆盖到“某个时间点”，一旦中间穿插了多次尝试，回退成本极高。

第二个场景是“产品线分支同时维护”。同一个主控平台，可能同时存在A项目、B项目，它们在引导参数、内核裁剪、文件系统打包脚本上各有差异。很多人会复制整个源码树，然后改其中一份。初期没事，等到上游代码的安全补丁下来，几十个目录手动对比差异，工作效率基本为零。

第三个场景是“多人写同一个驱动目录”。手里没有版本管理工具时，跨开发者合代码通常靠“发一个补丁文件”或者“你在本地改了发我一份”。一旦同一行被两边同时改动，到底以谁为准，就只能开会聊。这种问题交给Git之后，能把它变成可以跟踪、可回滚、可审查的记录，冲突部分还会被明确标出来，而不是靠人去猜。

1.2 Git和压缩包备份的根本区别

压缩包备份本质上是“快照”思维：定期把整个目录打包，存到另一个位置。问题在于你不知道快照之间改了什么，也无法精确对比。Git则把工程看成一条“提交历史”，每次提交都记录当前版本和父版本之间的关系，代码越改，历史越清晰。

有一点经常被初学者忽略：Git是分布式的。克隆一份仓库后，本地就拥有完整的提交历史，即使暂时联不上远端服务器，也可以正常提交、查看历史、切换分支。嵌入式开发经常在实验室网络环境不稳定的时候干活，这一特性非常实用。和常见集中式版本管理工具不同，Git不需要“必须连接服务器才能提交”，所有版本动作都先在你机器上完成，等到需要协作或备份时再同步到GitHub。

2. Linux下Git安装与首次配置

2.1 安装Git并确认版本

多数Linux发行版自带Git，如果没有，就用发行版包管理器安装。以Debian/Ubuntu系为例：

sudo apt update sudo apt install git -y git --version

CentOS/RHEL/Fedora一类则用：

sudo dnf install git -y

我建议优先用系统自带的包管理器，不要手动编译新版。嵌入式开发机器不一定要求Git版本最新，发行版仓库里的版本足够稳定。如果后续需要用到较新的子命令，比如git switch，要求Git 2.23以上，再考虑升级。

安装完成后，顺手配置一下命令行输出颜色，不然status的结果全是一个颜色，看起来费劲：

git config --global color.ui auto

这套配置写在用户目录的~/.gitconfig里，全局生效。

2.2 这是最容易跳过的全局配置

有些同学第一次git commit就报错，提示需要设置“user.name”和“user.email”。这不是填写到代码里的什么认证，而是每次提交记录里必须写明“这个提交是谁做的”。它可以和GitHub账号不一致，但对于团队协作，建议写真实可识别的信息。

git config --global user.name "Your Name" git config --global user.email "you@example.com"

把分支默认名设为main也是推荐做法。Git老版本默认叫master，但新项目用main更符合当前习惯：

git config --global init.defaultBranch main

验证配置是否生效：

git config --list

另外提一下，某些自动化脚本以中文文件名提交时容易出现编码问题，比较简单的规避方式是不用中文命名源代码文件。这不是Git不支持，而是跨平台工具链在文件名编码上容易踩坑，嵌入式项目的脚本、设备树文件保持英文命名最省事。

2.3 创建第一个版本库

我建议每个独立工程单独建一个仓库，不要把整个工作目录所有东西都塞进一个仓库。比如我的模拟项目X，目录结构可能是uboot/、kernel/、buildroot/、app/，我会按顶层模块分别初始化仓库，或者保持统一工程仓库并在目录里用.gitignore做好排除。对一个刚入门的同学，最简单的做法是：

mkdir ~/dev/board-bsp cd ~/dev/board-bsp git init

执行后目录下会出现一个.git目录，里面保存了全部版本历史、分支指针、配置信息。不要手工去删它，也不要把整个仓库目录拷给别人后继续在副本里写提交，那样容易造成两套历史对不上的局面。

3. Git三区域模型与日常提交流程

3.1 一次提交背后发生了什么

我见过很多新手把git add和git commit当成一个组合来看，觉得多此一举。要理解这条命令链，得先搞清楚Git的三个区域：

• 工作区：你正在编辑的文件目录；
• 暂存区：提交前先放一次“预览名单”的区域，存的是你准备提交的内容；
• 版本库：已经提交进去的历史仓库。

用生活化的场景类比：工作区是你的办公桌，暂存区像是你从办公桌选好放进“待归档纸箱”的文件，版本库则是档案室的柜子。git add是往纸箱里放文件，git commit是把这箱文件正式归入档案，并贴上一个带编号的标签。

为什么需要暂存区？因为实际开发中，你可能同时改了驱动A和设备树B，但只想先把驱动A提交掉，设备树B还在调。如果git commit直接扫描工作区所有改动，你就很难做到“一次只提交一个逻辑单元”。有了暂存区，你能明确告诉Git“本次提交只包含哪些文件”。

3.2 从新建文件到提交

用一个最小的例子走一遍。创建文件并写入内容：

echo 'print("hello")' > app/demo.py git status

git status会告诉你有一个未跟踪的文件。然后加入暂存区并提交：

git add app/demo.py git commit -m "app: add demo script"

第二条命令如果执行成功，终端会输出一行类似“1 file changed”的信息。之后我再强调一次：暂存区不是摆设。习惯上，提交前先用git diff --staged看一眼即将进仓库的内容，确认没有夹带调试打印或临时文件：

git diff --staged

这一步很便宜，但能避免大量“提交了个寂寞”的后悔操作。

3.3 status、diff、log的日常读法

我每天用得最多的三个命令组合是status、diff、log。

• git status：告诉你哪些文件改了，哪些还在暂存区，哪些没被跟踪；
• git diff：展示工作区当前改动，但不包含已经git add的内容；
• git log：查看提交历史，建议配合参数使用。

git log --oneline --graph --decorate --all

--oneline把每个提交压缩成一行，--graph画出分支关系，--decorate显示分支和标签指向，--all把远程分支也列出来。嵌入式工程提交历史不会太短，这个视图能帮你建立“提交链条”的直观感受。嫌命令长可以配置别名：

git config --global alias.tree "log --oneline --graph --decorate --all" git tree

之后只要输入git tree就能看到漂亮的提交图，效率高很多。

4. 分支管理与嵌入式多版本维护

4.1 分支的本质和基础操作

分支相当于在提交历史上拉出一条“平行世界线”。你可以在主版本上继续修公共问题，同时拉一个分支专门适配某个客户的新屏幕。嵌入式开发最大的价值就在这里：不用等主线稳定，新适配扔到分支里慢慢试。

创建并切换分支：

git switch -c feature/lcd-timing

这个命令等同于老式的git checkout -b feature/lcd-timing，含义是“基于当前提交，新建一个分支并切过去”。之后所有提交都会落在新分支上，不会影响main分支。

改完后回到主线并合并：

git switch main git merge --no-ff feature/lcd-timing

--no-ff的意思是强制保留“合并提交”记录。哪怕合并没有冲突，也留下一个明确的合并节点，以后回看时能清楚地知道“这个功能是这时候合进来的”。嵌入式项目维护周期长，保留这种结构比线性历史更直观。

4.2 合并冲突是怎么发生的，怎么处理

两台设备同一个配置文件被两个分支改了同一段内容，合并时就可能冲突。比如双方都改了kernel/drivers/video/fb.c中的同一行，Git不知道以谁为准，会在文件里插入冲突标记：

<<<<<<< HEAD .pixclock = 12800, ======= .pixclock = 14400, >>>>>>> feature/lcd-timing

处理流程是手动打开文件，修正成想要的内容，删掉<<<<<<<、=======、>>>>>>>三行标记，然后：

git add kernel/drivers/video/fb.c git commit

第一次遇到时会紧张，实际就是改文件而已。我比较建议在嵌入式开发里尽量把设备树/配置文件拆得细一些，比如每块外设一个dtsi，每个改动都在独立文件里，冲突概率会大幅下降。两个分支同时改同一个文件是常态，但最好别在同一个文件的同一块区域撞车。

4.3 用tag给固件发布打标记

在嵌入式工程里，硬件版本和软件版本经常需要对应。git tag就是给某次提交打一个永久性标签，内核编译版本、固件版本都能对应到精确的代码位置：

git tag -a v1.2.0 -m "release v1.2.0 for X board lcd support" git tag -l git show v1.2.0

建议用带-a参数的附注标签，而不是轻量标签。因为附注标签记录了打标签的人、时间、说明信息，对追溯很有帮助。发布固件时，我会顺手把git describe的结果写进编译生成的版本文件里，这样现场拿到一个固件，能直接反查到源码提交点，排查问题省太多时间。

5. 把代码同步到GitHub

5.1 在GitHub上建仓库并与本地关联

远程仓库的作用不只是备份，还是团队协作的公共基线。以GitHub为例，登录后在页面右上角找到New repository，填一个仓库名，比如linux-embed-demo。如果没有特殊需求，建议选Private（私有仓库），避免内核源码或板级配置意外公开。

创建页面会提示你初始化README、.gitignore等。这里有个实际操作建议：如果本地已经初始化过仓库，不要在网页上勾选“Add a README file”，否则远端会产生一个没有历史关联的初始提交，本地push时要去处理两套无关历史。最简单的流程是：网页上保持空仓库，回到终端执行：

git remote add origin https://github.com/yourname/linux-embed-demo.git git remote -v

origin只是一个约定俗成的远端名称，用来替代那一长串URL。git remote -v会列出当前关联的拉取/推送地址，我每次都会用它确认地址拼写没有出错。

5.2 推送到远端和拉取远端更新

第一次推送时要把本地main分支和远端main分支建立跟踪关系：

git push -u origin main

-u参数把本地分支与origin/main绑定，以后直接敲git push就能推。之后如果其他设备或同事在远端更新了代码，本地提交前最好先拉取：

git pull --rebase origin main

我习惯给git pull加--rebase而不是直接用默认的merge。原因很简单：远端有别人提交，本地也有自己的提交，如果用merge方式会多生成一个“合并分支”的记录；用rebase相当于先把本地提交暂时挪到一边，拉到远端最新提交后，再把本地提交重新接到最新历史末端，提交历史看起来是一条直线，更清晰。

5.3 认证方式：推荐用个人访问令牌或SSH

GitHub已经不支持用账号密码直接push。现在最简单的方式是token。方法是：GitHub网页右上角头像 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token，勾选repo权限后生成，然后复制保存。token只在生成页显示一次，务必先复制到安全位置。

之后执行git push，提示输入用户名时填GitHub账号，提示输入Password时粘贴token而不是账号密码。它不像账号密码那么长，粘贴后回车即可。

如果不希望每次push都输token，可以把凭据存到本地：

git config --global credential.helper store

执行过一次push并输入token后，它会被明文记录在用户主目录的.git-credentials文件里。在自己个人电脑上方便，但在共用机器上我不建议开，安全风险太大。稍微折中的方案是用cache，让它只缓存几分钟：

git config --global credential.helper cache

如果不想用token，也可以走SSH。生成密钥：

ssh-keygen -t ed25519 -C "you@example.com" cat ~/.ssh/id_ed25519.pub

把.pub文件里的内容整段复制到GitHub账号的SSH keys设置页面，然后把远端地址改成SSH形式：

git remote set-url origin git@github.com:yourname/linux-embed-demo.git git push origin main

SSH方式配置好以后基本不用反复输token，GitHub也鼓励这种方式。第一次连接时会提示确认指纹，输入yes就好。

5.4 一个容易被忽略的远端协作习惯

当远端存在本地没有的提交时，直接git push会报“failed to push some refs”，这是保护机制，不是错误。正确做法是先git pull --rebase origin main，处理冲突后再push。不建议强制推送：

git push --force

这条命令会把本地历史强行覆盖远端。如果远端是公共仓库，会让别人已经拉取的提交全部失效。只有当你确定远端历史已经没用了，或者永久修复一个错误提交时，才能考虑带--force-with-lease的受保护推送：

git push --force-with-lease origin main

这个参数会比裸--force安全，它先检查远端没有别人新推的提交，才允许覆盖。

6. 嵌入式工程专属的Git细节

6.1 用.gitignore管住编译产物

嵌入式工程和纯软件工程最大的差异在于：编译一次会生成大量中间文件、镜像、调试产物。这些二进制文件一旦进仓库，仓库体积会迅速膨胀，而且每次编译都会触发status变化，干扰你判断“到底改了哪些源码”。

我通常在仓库根部放一个.gitignore，至少包含以下模式：

# 构建输出目录 build/ out/ output/ # 编译中间文件 *.o *.a *.d *.cmd # 最终镜像与固件 *.bin *.img *.dtb *.elf *.map # 编辑器与IDE .vscode/ *.swp # 本地配置 local.mk

注意.gitignore只影响尚未被跟踪的文件。如果某个*.bin已经被git add进仓库了，单纯加.gitignore不会让它消失，需要先：

git rm --cached firmware/app.bin

--cached表示只从版本暂存移除，而保留工作区文件。这个命令在误加了编译产物后非常常用。

6.2 大文件和工具链该怎么办

交叉编译工具链、基础库、预编译的第三方SDK，体积动辄几百MB甚至几GB，不适合放进Git仓库。Git对历史里的大文件处理很差，即便后续删除，它也会一直保留在历史对象中。仓库会越来越大，clone一次要很久。

常见的做法是：源代码进Git，工具链和预编译产物放在共享存储/网盘，并在README里写清楚版本号和下载方式。如果必须把二进制纳入版本管理，可以了解Git LFS，它会把大文件替换成指针文件，实际内容单独存储。以跟踪*.bin为例：

git lfs install git lfs track "*.bin" git add .gitattributes

对嵌入式项目，我始终建议“能用脚本重建的东西不要提交”。比如根文件系统镜像，如果来源是buildroot输出目录，那就提交配置和构建脚本，不提交最终镜像，这样仓库轻便，也方便追溯。

6.3 把构建环境信息写进仓库

嵌入式代码常见问题是“在别人机器上编不过”。代码本身没问题，但编译依赖的交叉编译器路径、系统库版本、内核源码路径对不上。Git提交不会记录这些环境信息，需要在仓库里主动补充。

我习惯在每个模块顶层放一个README.md或者build.sh，里面写明：

• 使用的交叉编译链版本和下载路径；
• 需要导出的环境变量；
• 编译命令示例。

这样每次clone到新机器，步骤是：先装依赖，再执行构建脚本，然后根据报错微调工具链路径。用Git管理脚本的好处是，环境配置的演进过程也有历史记录，而不是靠同事口口相传。

6.4 保存修改切换任务，用stash而不是乱提交

嵌入式开发经常被打断：正在调试设备树，突然需要切到另一个分支看其他问题。这时未提交的改动带不走，直接switch会报错，说本地有未保存的更改。不少人图省事就git commit -m "temp"，结果历史里留下大量“临时提交”。

正确的做法是用git stash：

git stash push -m "lcd timing in progress" git switch other-branch # 处理完其他分支后切回来 git switch main git stash pop

stash会把工作区和暂存区的改动保存到“杂物间”，等回到原分支再弹出。弹出的内容可以再次修改后提交。需要注意pop时如果和当前分支改动冲突，解决方式比普通合并还要小心，建议在干净环境里操作。

7. 常见问题与排查实录

7.1 撤销操作速查表

Git最让新手头疼的是“怎么撤销”。我结合嵌入式场景整理了一张速查表：

最后一条特别适合嵌入式发布场景。git reset --hard是危险操作，会把未提交的所有修改连同提交一起丢掉。我用它的唯一场景是“确认旧版本完全没用了”，比如清掉测试用的临时代码。执行前，我会把当前版本关键文件复制一份到/tmp，心里才有底。

7.2 push被拒绝，其实不是代码问题

“push被拒”在初学者眼里像错误，其实是Git的常规保护。常见报错：

! [rejected] main -> main (fetch first) error: failed to push some refs to 'https://github.com/...' hint: Updates were rejected because the remote contains work that you do hint: not have locally.

意思是远端有你本地没有的提交。解决：

git pull --rebase origin main git push origin main

如果rebase过程中有冲突，按7.2节那样解决并继续。注意git pull --rebase如果处理到一半不想继续了，可以用git rebase --abort回到rebase前的状态，这个中止操作不会毁掉本地提交，比较安全。

7.3 GitHub认证反复失败

认证失败常见表现是：

remote: Support for password authentication was removed. fatal: Authentication failed for 'https://github.com/...'

原因基本是用了账号密码，或者token过期/权限不够。解决步骤：

1. 确认远端地址正确：git remote -v；
2. 重新生成一个勾选了repo权限的token；
3. 再次push时，用户名填账号，密码处粘贴新token；
4. 如果之前配置了credential.helper store，旧token可能还在缓存里，需要删除~/.git-credentials中对应行，或直接更新URL。

如果一直不顺利，改用SSH方式基本能绕开这些认证交互，但前提是公钥已经正确添加到GitHub账户。

7.4 误入分离头指针状态

执行git checkout v1.0.0或者git checkout <某提交哈希>后，提示HEAD detached at ...，这就是分离头指针状态。在这个状态下做出的提交不会属于任何分支，重新切回分支后很容易“找不到”，白改一场。

修复办法是在分离头指针状态下基于当前提交创建新分支：

git switch -c temp-fix git switch main git merge temp-fix

记住：检出一个具体提交只是为了看代码，不要直接在上面开发。想看某个历史版本的工程状态，更推荐用git switch -c branch-name xxx提交，顺便把分支拉出来。

8. 给刚上手的嵌入式工程师的几句实操建议

最后分享几个我踩过坑之后才养成的习惯。

第一个习惯：每次改动尽量小，验证通过后及时提交。修改内核配置、设备树、串口寄存器这类事情，经常是改一下就要重新编译烧录，验证时间可能五六分钟。如果拖到下午一起提交，中间调过什么早忘了。提交信息宁可用“uboot: modify DDR timing for X board”这种朴素表达，也不要写“update”。

第二个习惯：不要把一个仓库搞成巨型杂货铺。嵌入式工程里源码、文档、脚本、硬件原理图PDF混在一起很常见。Git能管PDF，但diff很难看；硬件库文件体积大且格式频繁变化，硬塞进Git只会让仓库越来越难用。我比较推荐把文档交给其他协作工具，源代码交给Git。

第三个习惯：熟练使用git log -S和git bisect。前者能查到“哪个提交新增/删除了某个字符串”，后者能在几十个提交里快速定位“哪次改动让启动失败”。这两个命令看起来比add/commit高级一点，但它们才是Git真正超越压缩包备份的价值所在。配套的做法是：确保每个提交都只包含一类逻辑改动，这样排查时才能直接根据提交边界切分验证点。

第四个习惯：定期把提交推到GitHub远端。本地仓库永远存在硬盘坏掉的风险，而远端仓库就是你的“第二块硬盘”。哪怕项目只有自己一个人在做，我也建议一开始就建立remote并保持推送，不要等“代码稳定了”再去同步。同步动作应该是日常习惯，而不是发布前的收尾动作。

我的看法是：在项目还不复杂的时候开始用Git，成本很低；等整个工程已经变成了几十个压缩包，再想回头整理版本历史，那才是真的头痛。把Git当作写代码的一部分，而不是额外负担，你会比想象中更快适应它。