Better Mistakes

我会用 Git，但它到底在做什么？从对象数据库到现代工作流

Sun, 06 Sep 2026 12:00:00 GMT

我会 git add、git commit、git pull 和 git push，但很长时间里，这些命令在我脑中只是一条能让代码抵达 GitHub 的传送带。AI 当然可以替我操作，而且大多数时候会操作得更快；但如果我自己分不清工作区、暂存区、引用和远端跟踪分支，就连 AI 刚刚改写了历史还是只更新了一个指针都无法判断。于是我用 Git 2.54.0 建了一个隔离仓库，从对象数据库开始，把平时敲下的命令逐层拆开。

这不是一张命令速查表。我的目标是先建立模型，再从模型推导命令。Git 自己给出的冷幽默式描述是 “the stupid content tracker”，但它的底层其实相当小：一个内容寻址对象数据库，加上一组会移动的名字，再配一个准备下一次快照的 index。命令很多，核心没有那么多。

git add

git commit

移动当前分支

git push

merge 或 rebase

工作区 Working Tree

暂存区 Index

对象数据库 Objects

refs/heads/main

HEAD

git fetch

refs/remotes/origin/main

远端 refs/heads/main

git add

git commit

移动当前分支

git push

merge 或 rebase

工作区 Working Tree

暂存区 Index

对象数据库 Objects

refs/heads/main

HEAD

git fetch

refs/remotes/origin/main

远端 refs/heads/main

这张图是全文的地图。后面的绝大多数 Git 操作，都只是复制内容、创建不可变对象，或者让某个引用从一个 commit 移到另一个 commit。

先把几个基础概念钉牢#

我以前会说”这个文件已经在 Git 里了”，但这句话至少可能指 4 件不同的事：文件出现在工作目录里、内容进入 index、内容被某个 commit 引用，或者 commit 已经推到远端。Git 的难点有一半来自把这些状态压成了一个模糊的”保存”。

仓库与工作区不是同一个东西#

Repository（仓库） 主要指 .git 中的对象、引用和配置。Working tree（工作区或工作树） 是我在编辑器里看到、编译器会读取的那份文件集合。一个普通项目目录通常把两者放在一起：

1
pocket-git/          # 工作区根目录
2
├── README.md        # 可以直接编辑的文件
3
├── src/
4
│   └── app.txt
5
└── .git/            # 仓库元数据与对象数据库

删除工作区文件不等于立即删除历史中的 blob；删除 .git 则会让这个目录失去本地 Git 历史、refs 和 index，只剩普通文件。bare repository 没有普通工作区，服务器端仓库经常采用这种形态。

Note

上一段中的”工作区”是 Git working tree，不是 IDE 把多个文件夹组织起来时所说的 workspace。两者可能指向同一目录，也可能完全不是一层概念。

暂存区不是待上传清单#

Index（索引，也叫 staging area 或暂存区） 保存下一次 commit 准备采用的路径、文件模式和 blob ID。它不是一个只有文件名的勾选列表，也不是尚未 push 的 commit 队列，而是一份接近完整目录快照的二进制数据结构。

这解释了一个初学时很反直觉的现象：

Terminal window

1
printf 'version 1\n' > app.txt
2
git add app.txt
3
printf 'version 2\n' > app.txt
4
git commit -m 'record app'

这个 commit 收进去的是 version 1，因为 git add 当时把那份内容写入对象数据库并让 index 指向它。之后写入工作区的 version 2 仍未暂存。git add 更准确的理解不是”开始跟踪这个文件”，而是”把这些路径此刻的内容放入下一张快照”。

`HEAD`、branch 与 commit#

Commit 是不可变对象，记录根 tree、parent、身份、时间和消息。Branch 是 refs/heads/... 下会移动的引用。HEAD 表示当前检出位置，通常间接指向某个本地分支。

1
HEAD -> refs/heads/main -> commit 0063127 -> parent cd5e714

执行 git commit 时，Git 创建新 commit，再让当前分支指向它；旧 commit 没有被修改。执行 git switch topic 时，Git 改变 HEAD 所指分支，并让 index 与工作区尽量匹配目标快照。分支是名字，commit 才是历史节点。

tracked、untracked、modified 与 staged#

这些词描述的是路径与 3 份状态之间的关系：

状态	含义	常见下一步
untracked	工作区有这个路径，但 index 与 `HEAD` 都没有记录它	`git add <path>` 或写入 `.gitignore`
unmodified	工作区、index 与 `HEAD` 对该路径的内容一致	不需要动作
modified	工作区内容不同于 index	查看 `git diff`，再暂存或恢复
staged	index 内容不同于 `HEAD`	查看 `git diff --staged`，再 commit 或取消暂存
deleted	某次比较的一侧已有路径，另一侧没有	暂存删除、恢复文件或提交删除
conflicted	index 中存在尚未解决的高 stage 条目	解决内容，`git add` 后继续操作

一个文件可以同时 modified 与 staged。前面的 MM src/app.txt 就是：index 已准备一个版本，工作区又在它上面继续修改。git status 给状态摘要，git diff 展开具体内容；前者像仪表盘，后者才是示波器。

本地分支、远端跟踪分支与 upstream#

这 3 个名字也经常被混成”远端分支”：

main 是本地分支，我可以离线提交并移动它；
origin/main 是本地保存的 remote-tracking ref，表示上次 fetch 后我看到的远端 main；
服务器上的 refs/heads/main 才是远端此刻真正的分支。

Upstream 是给本地分支配置的默认比较、pull 和 push 对象。例如 git push -u origin topic 会在发布分支的同时设置 upstream。upstream 不是父 commit，也不意味着本地分支会自动与服务器同步。

最后把最常见的状态流压成 4 步：

远端仓库本地仓库Index工作区远端仓库本地仓库Index工作区我编辑文件git add：写入 blob 并更新 indexgit commit：创建快照并移动本地 branchgit push：发送对象并请求移动远端 ref我

这 4 步可以分开检查，也应该分开理解。

先说结论：Git 保存的是快照，不是补丁#

很多介绍会把 Git 描述成一个逐行保存差异的工具。这对阅读 git diff 很直观，但不适合作为底层模型。

每次 commit 指向一棵完整目录树。没有变化的文件会继续引用原来的 blob，所以 Git 不需要重复创建内容相同的对象；发生变化的文件得到新的 blob。Git 在对象语义上保存快照，在 packfile 的物理存储里才会为了压缩寻找 delta。换句话说：快照是数据模型，差异是比较结果和存储优化。

我把 Git 想成一座仓库：对象是贴着内容指纹的密封箱，commit 是一张指向整批箱子的装箱单，branch 只是贴在某张装箱单上的可移动书签。这个比喻到这里就够了，接下来直接看字节。

从零建一个可以解剖的仓库#

我不会拿正在工作的项目做实验。先创建临时目录，并显式指定初始分支名：

Terminal window

1
repo=$(mktemp -d)
2
cd "$repo"
3
git init --initial-branch=main
4
git config user.name Ada
5
git config user.email ada@example.com

我的实验版本是：

1
git version 2.54.0

git init 没有创建任何 commit。它只创建 .git 管理目录。下面是采用默认 files 引用后端的仓库在后续使用中会出现的关键路径；index、refs/remotes 和 logs 并不一定在刚初始化时就存在：

1
.git/
2
├── HEAD
3
├── config
4
├── index              # 第一次 add 后出现
5
├── objects/           # 对象数据库
6
├── refs/heads/        # 本地分支引用
7
├── refs/remotes/      # fetch 后的远端跟踪引用
8
└── logs/              # 启用 reflog 的引用发生更新后出现

现代脚本应使用 git init --initial-branch=main，而不是依赖某个 Git 版本或用户配置碰巧采用什么默认分支名。长期偏好则可以配置：

Terminal window

1
git config --global init.defaultBranch main

Note

--global 修改当前用户的 Git 配置，不应该不加判断地写进项目安装脚本。项目级策略尽量放在仓库配置、服务端规则或文档中，个人偏好留给个人。

第一个 blob：内容如何变成 ID#

写一个 13 字节文件（结尾换行也算 1 字节）：

Terminal window

1
printf '# pocket-git\n' > README.md
2
git hash-object README.md

我得到：

1
5d87241c4953134b72c3ef069243777aa25121d9

这个 40 位 object ID 不是只对文件内容计算 SHA-1。Git 实际哈希的是：

1
blob 13\0# pocket-git\n

也就是对象类型、一个空格、十进制长度、NUL 字节，再接原始内容：

1
import hashlib
2

3
content = b"# pocket-git\n"
4
raw = f"blob {len(content)}\0".encode() + content
5
print(hashlib.sha1(raw).hexdigest())

输出仍然是：

1
5d87241c4953134b72c3ef069243777aa25121d9

git hash-object README.md 默认只计算，不写入数据库；加 -w 才会写。平时不需要直接执行它，因为 git add 会完成这一步。

Git 2.54.0 新仓库仍默认使用 SHA-1，也支持 git init --object-format=sha256。不过 SHA-1 与 SHA-256 仓库目前不能直接互操作，所以不要为了看起来更现代就擅自切换团队仓库的对象格式。这里的 object ID 首先承担内容寻址和完整性校验；它不是文件加密，也不等于 commit 签名。

`git add` 不是”添加文件”，而是更新下一张快照#

再写一个文件，然后暂存两者：

Terminal window

1
mkdir src
2
printf 'version 1\n' > src/app.txt
3
git add README.md src/app.txt
4
git ls-files --stage

我看到：

1
100644 5d87241c4953134b72c3ef069243777aa25121d9 0 README.md
2
100644 83baae61804e65cc73a7201a7252750c76066a30 0 src/app.txt

这就是 index 的可读投影。每行记录文件模式、blob ID、stage 编号和路径。100644 是普通非可执行文件；最后的 0 表示正常条目。普通内容冲突中，同一路径最多还可能出现 stage 1、2、3，分别保存 merge base、ours 和 theirs；删除等冲突类型可能缺少其中某项，而且 rebase 里的 ours 与 theirs 要从重放操作而非原分支名理解。

所以 git add 这个名字稍微有点误导。它不仅”添加新文件”，还会把已修改文件的当前内容写成 blob，并更新 index 中对应路径。之后继续编辑同一个文件，不会自动改变已经暂存的内容。

从 index 写出 tree，再创建 commit#

index 还不是 tree 对象，但它是 tree 的施工图。执行：

Terminal window

1
git write-tree

我的根 tree ID 是：

1
208dc736f90acf95e1f43a0a0ae122b906953eef

查看它：

Terminal window

1
git cat-file -p 208dc736f90acf95e1f43a0a0ae122b906953eef

会看到根目录中的 blob 和 src 子 tree。tree 保存名字、模式和下一级对象 ID；blob 只保存内容，不知道自己叫 README.md 还是 copy.md。两个路径内容完全相同，可以指向同一个 blob。

现在提交。为了让下面的 commit ID 可以复算，我除了使用前面配置的身份，还临时固定 author date 和 committer date：

Terminal window

1
export GIT_AUTHOR_DATE='2026-09-06T12:00:00+08:00'
2
export GIT_COMMITTER_DATE="$GIT_AUTHOR_DATE"
3
git commit -m 'feat: build the first snapshot'

我得到：

1
cd5e7140591d1099e8a990fe16f839a4b91be271

直接查看对象：

Terminal window

1
git cat-file -p HEAD

1
tree 208dc736f90acf95e1f43a0a0ae122b906953eef
2
author Ada <ada@example.com> 1788667200 +0800
3
committer Ada <ada@example.com> 1788667200 +0800
4

5
feat: build the first snapshot

第一个 commit 没有 parent。后续普通 commit 有 1 个 parent，merge commit 通常有 2 个或更多 parent。commit 本身不装文件内容，只记录：

根 tree；
parent commit；
author 与 author date；
committer 与 committer date；
commit message；
可选签名等 header。

因此修改 commit message、作者、时间、parent 或 tree 中任意一个字节，都会得到新的 commit ID；它之后的所有子 commit 也必须改写，因为每个子 commit 都记录 parent ID。这就是 rebase、commit --amend 和历史过滤为什么会成串地产生新 ID。

把这些对象连起来以后，第一张快照实际是一张由 ID 串起的 DAG：

README.md / 100644

src / 040000

app.txt / 100644

commit cd5e714

作者、时间、消息

root tree 208dc73

blob 5d87241

# pocket-git

tree src

blob 83baae6

version 1

README.md / 100644

src / 040000

app.txt / 100644

commit cd5e714

作者、时间、消息

root tree 208dc73

blob 5d87241

# pocket-git

tree src

blob 83baae6

version 1

路径名活在 tree 的边上，文件内容活在 blob 中，commit 只从根 tree 进入整张图。这也是相同内容能够复用同一个 blob 的原因。

一次普通 git commit 在概念上做了 4 件事：

从 index 写出 tree 对象；
创建指向该 tree 和当前 parent 的 commit 对象；
把当前 branch ref 移到新 commit；
在已启用的 HEAD 和当前本地分支 reflog 中记录这次移动。

它不会自动提交工作区里尚未暂存的修改。git commit -a 只会自动暂存已跟踪文件的修改和删除，仍不会包含未跟踪文件。我更偏好显式 git add -p，因为省掉一次检查通常也顺便省掉了思考（这个优化不太划算）。

我实际做了一次：

Terminal window

1
printf 'version 2\n' > src/app.txt
2
git add src/app.txt
3
printf 'version 3\n' > src/app.txt
4
git status --short

输出是：

1
MM src/app.txt

左边的 M 表示 index 相对 HEAD 有修改，右边的 M 表示工作区相对 index 又有修改。同一个路径此时同时存在 3 个版本：

位置	内容	查看方式
`HEAD`	`version 1`	`git show HEAD:src/app.txt`
index	`version 2`	`git show :src/app.txt`
工作区	`version 3`	`cat src/app.txt`

git diff --staged

git diff

HEAD

version 1

index

version 2

工作区

version 3

git diff --staged

git diff

HEAD

version 1

index

version 2

工作区

version 3

这里的箭头表示比较方向，不表示内容自动流动。它把 MM 的两个 M 直接摊开了：左列比较 HEAD 与 index，右列比较 index 与工作区。

对应的两次比较也完全不同：

Terminal window

1
git diff                  # 工作区 vs index
2
git diff --staged         # index vs HEAD

这是我认为最值得形成肌肉记忆的提交循环：

Terminal window

1
git status --short --branch
2
git diff
3
git add --patch
4
git diff --staged
5
git commit

git add --patch（缩写 git add -p）按 hunk 选择内容，比不看差异就 git add . 更接近”设计一个 commit”。如果同一段修改同时修 bug、改命名和格式化，我会先把它们拆成能独立解释的快照。commit 的边界是给未来的我、同事、git bisect 和 AI 阅读的 API。

Warning

git add . 本身没有错，但它表达的是”暂存当前目录以下所有变化”。在运行前后都看 git status 和 git diff --staged，不要把它当作关闭红点的按钮。

`git diff` 到底在比较什么#

diff 是我每天最应该多敲几次的 Git 命令。它不修改状态，只把两个端点之间的变化编码成 patch。真正的第一个问题不是”改了什么”，而是”拿哪两份状态比较”。

先选对两端#

命令	旧端	新端	我通常用它回答
`git diff`	index	工作区	我改了但还没暂存什么？
`git diff --staged`	`HEAD`	index	下一次 commit 会包含什么？
`git diff HEAD`	`HEAD`	工作区	当前全部已跟踪修改是什么？
`git diff <A> <B>`	commit A	commit B	从 A 变成 B 要应用什么 patch？
`git diff <A>...<B>`	A 与 B 的 merge base	commit B	B 分支从分叉点引入了什么？
`git show <commit>`	普通 commit 的 parent	该 commit	这个普通 commit 引入了什么？

方向很重要。git diff A B 描述的是把 A 变成 B：- 行来自 A，+ 行来自 B。交换参数，patch 的正负也会反过来。

git diff A..B 对 diff 来说与 git diff A B 基本等价，只比较两个端点；这里的 .. 不具有 git log A..B 那种”可达 commit 集合之差”语义。三点 A...B 才会先求 merge base，再把 merge base 与 B 比较。两个点和三个点长得只差一个点，含义差了一棵分叉历史（非常 Git）。

只看某些路径时，我会用 -- 明确结束 revision 参数：

Terminal window

1
git diff HEAD -- src/app.txt
2
git diff main...topic -- src/

这也能避免一个路径名恰好像 branch 名时产生歧义。

逐行拆一份 unified diff#

在前面的实验里，index 保存 version 2，工作区保存 version 3。运行：

Terminal window

1
git diff -- src/app.txt

实际输出是：

1
diff --git a/src/app.txt b/src/app.txt
2
index 1f7a7a4..7170a52 100644
3
--- a/src/app.txt
4
+++ b/src/app.txt
5
@@ -1 +1 @@
6
-version 2
7
+version 3

从上往下读。

`diff --git`：一个文件级变化开始了#

1
diff --git a/src/app.txt b/src/app.txt

这一行标记新的 file patch。a/ 表示变化前一侧，b/ 表示变化后一侧；它们通常不是仓库里真实存在的两个目录。重命名或复制时，两侧路径会不同。

`index`：前后 blob 与文件模式#

1
index 1f7a7a4..7170a52 100644

1f7a7a4 是旧端内容的 blob ID 缩写，对应 version 2；
7170a52 是新端内容计算出的 blob ID 缩写，对应 version 3；
100644 表示普通非可执行文件。

工作区版本即使还没被 git add 写成 loose object，Git 仍可以根据内容算出它应有的 object ID。文件模式发生变化时，输出通常改为独立的 old mode 和 new mode 行。

`---` 与 `+++`：旧文件和新文件标签#

1
--- a/src/app.txt
2
+++ b/src/app.txt

--- 永远标旧端，+++ 永远标新端。这里的 3 个减号和 3 个加号是 header 语法，不表示删除了 3 行或增加了 3 行。新建文件的旧端、删除文件的新端会在这里显示 /dev/null。

`@@`：hunk 在两边的坐标#

1
@@ -1 +1 @@

一个 patch 可以包含多个相隔较远的修改块，每一块叫 hunk。一般格式是：

1
@@ -<旧起始行>,<旧行数> +<新起始行>,<新行数> @@ <可选上下文>

-1 表示旧文件从第 1 行开始、共 1 行；+1 对新文件含义相同。行数为 1 时逗号和行数会省略，所以这里不是”缺了一个数字”。例如：

1
@@ -10,4 +10,6 @@ function parseConfig()

表示旧端从第 10 行取 4 行，新端从第 10 行取 6 行。末尾的函数名或章节名只是帮助定位的 hunk context，不参与 patch 内容。

hunk 正文：看每行第一个字符#

1
version 2
2
version 3

空格开头：context line，两边都存在，内容没变；
- 开头：只在旧端存在，要删除；
+ 开头：只在新端存在，要加入。

这几个前缀是 patch 数据，不是装饰颜色。终端常把删除染红、增加染绿，但把颜色关掉或把 patch 发给程序后，真正可靠的仍是行首字符。

若文件最后一行缺少换行，Git 还会输出：

1
\ No newline at end of file

这不是新增的文件内容，而是说明紧邻的那一侧末行没有 line feed。文本文件看起来完全一样，末尾字节却不同，Git 当然会认真记账（它对字节的原则性比我强得多）。

新建、删除、改权限和重命名怎么看#

普通内容修改之外，extended headers 会描述文件级元数据：

1
new file mode 100644
2
deleted file mode 100644
3
old mode 100644
4
new mode 100755
5
rename from old-name.txt
6
rename to new-name.txt
7
similarity index 98%

100644 -> 100755 通常表示 executable bit 发生变化，不代表文件正文改变。重命名则需要一个重要修正：Git commit 并不存储”rename old to new”操作。Git 保存前后 tree，diff 再把一个删除和一个新增按内容相似度推断为 rename。similarity index 98% 表示 Git 认为 98% 的行没有变化；调整 rename detection 阈值可能得到不同展示，但 commit 对象没有改变。

想明确启用并设置阈值，可以：

Terminal window

1
git diff --find-renames=50% <A> <B>

二进制文件默认通常只显示 Binary files ... differ，不会假装把任意字节流解释成文本行。项目可以通过 .gitattributes 配置 textconv 或专用 diff driver，但那改变的是展示，不是对象内容。

适合不同阅读阶段的 diff 视图#

完整 patch 不是每次都最合适。我通常从概览逐层放大：

Terminal window

1
git diff --stat                 # 每个文件的增删规模
2
git diff --name-status          # 路径及 M/A/D/R 等状态
3
git diff                        # 完整未暂存 patch
4
git diff --staged               # 完整待提交 patch
5
git diff --word-diff            # 观察行内词级变化
6
git diff --check                # 检查空白错误与冲突标记

--stat 适合先判断变化范围，不能代替阅读 patch；--word-diff 对长段文字和一行内改多个 token 很有用，但它不是常规 unified patch；--check 适合提交前发现 trailing whitespace 等问题。

只想让脚本判断有无差异时：

Terminal window

1
git diff --quiet --exit-code

退出码 0 表示没有差异，1 表示存在差异，其他非零值通常表示真正的错误。这里不能用”命令没有打印东西，所以相同”来判断，因为 --quiet 本来就不打印。

Git 也可以离开仓库比较两个普通路径：

Terminal window

1
git diff --no-index old.txt new.txt

这时它很像系统 diff -u，仍使用 Git 熟悉的 patch 展示和退出码。至于 --patience、--histogram 等 diff algorithm，它们会改变 hunk 如何对齐，适合默认 Myers 算法给出难读结果时尝试；它们不会改变两端真实内容。

Important

审查 commit 前看 git diff --staged，push 前看 branch 间的 diff。git status 只能告诉我”哪个文件处于什么状态”，不能告诉我删掉的条件判断是不是刚好把权限检查也带走了。

branch 和 HEAD 原来如此轻#

第一次提交后，我直接看两个文件：

Terminal window

1
cat .git/HEAD
2
cat .git/refs/heads/main

输出分别是：

1
ref: refs/heads/main
2
cd5e7140591d1099e8a990fe16f839a4b91be271

main 只是一个指向 commit 的 ref，HEAD 通常又是一个指向当前 branch ref 的符号引用。创建分支几乎不复制数据：

Terminal window

1
git branch experiment cd5e714

这只是新建 refs/heads/experiment，写入同一个 commit ID。无论仓库有 10 KB 还是 100 GB，创建普通分支都不是复制完整项目。

第二次提交后，我得到：

mainexperimentcd5e7140063127HEAD

此时 main 指向 0063127，experiment 仍指向 cd5e714。所谓”在某个分支上提交”，就是 Git 创建新 commit 后移动 HEAD 间接指向的那个分支。

detached HEAD 是什么#

如果执行：

Terminal window

1
git switch --detach cd5e714

HEAD 会直接保存 commit ID，而不再指向 refs/heads/...。这适合检查历史或做可丢弃实验。此时提交仍然会创建合法 commit，只是没有 branch 名自动跟着它移动。切走后，那些 commit 可能变得不可达，但通常还能暂时从 reflog 找回。

refs/heads/main

0063127

cd5e714

普通 HEAD

detached HEAD

refs/heads/main

0063127

cd5e714

普通 HEAD

detached HEAD

普通状态下，HEAD -> branch -> commit；detached 状态则跳过 branch，变成 HEAD -> commit。少掉的正是那个会自动移动、也方便以后寻找的名字。

如果实验值得保留，在切走前给它一个名字：

Terminal window

1
git switch -c rescued-experiment

为什么现在更推荐 `switch` 和 `restore`#

传统 git checkout 同时承担两类工作：

切换分支或进入 detached HEAD；
用 index 或某个 commit 覆盖路径。

同一个命令既移动 HEAD，又可能覆盖文件，意图不够显眼。Git 2.23 在 2019 年加入 git switch 和 git restore，把两组职责拆开。checkout 没有被废弃，也不是错误命令；现代交互式工作流更推荐语义专一的命令，因为代码审查和终端历史更容易读懂。

常见映射如下：

意图	现代命令	传统写法
切换已有分支	`git switch topic`	`git checkout topic`
创建并切换分支	`git switch -c topic`	`git checkout -b topic`
切回上一个分支	`git switch -`	`git checkout -`
临时查看 commit	`git switch --detach <commit>`	`git checkout <commit>`
丢弃工作区路径修改	`git restore <path>`	`git checkout -- <path>`
取消暂存	`git restore --staged <path>`	`git reset HEAD <path>`
从某 commit 取回路径	`git restore --source=<commit> <path>`	`git checkout <commit> -- <path>`

我在前面的 3 版本实验里运行：

Terminal window

1
git restore src/app.txt
2
git restore --staged src/app.txt

第一条把工作区从 version 3 恢复到 index 的 version 2；第二条把 index 从 version 2 恢复到 HEAD 的 version 1，但工作区仍保留 version 2。这里没有魔法，只是明确指定复制的来源和目的地。

git restore --staged

git restore

HEAD

version 1

index

version 2

工作区

version 3

git restore --staged

git restore

HEAD

version 1

index

version 2

工作区

version 3

restore 的危险程度取决于箭头落在哪里：落到工作区就可能覆盖未保存内容，落到 index 则只是重新安排下一次快照。

Caution

git restore <path> 会覆盖尚未暂存的工作区修改。先运行 git diff -- <path>。如果内容重要但还不适合 commit，可以先建临时分支提交，通常比把唯一副本塞进 stash 更容易找回。

merge、rebase 和 cherry-pick 都在改什么#

假设历史分叉成：

maintopicOABCD

Fast-forward：历史没分叉，只移动指针#

先看最简单的情况。main 停在 O，topic 从 O 继续提交了 C、D，而 main 自己没有新 commit：

合并前：

maintopicOCD

合并后：

mainOCD

两张图中的 O、C、D 是同一批 commit。前一张图里 main 留在 O；后一张只画发生变化的 main，它已经抵达 D。topic 没有移动，仍然指向 D。

O 是 D 的祖先，所以 git merge topic 不必创建 merge commit。Git 只把 main 从 O 移到 D，commit 图一个节点都没增加；这就是 fast-forward，缩写为 ff。之后看到的 pull --ff-only 和 push 检查都在问同一个祖先关系。

`merge`：保留分叉，增加汇合点#

在 main 上执行：

Terminal window

1
git switch main
2
git merge topic

若不能 fast-forward，Git 创建一个 merge commit M：

maintopicOABCDM

M 有两个 parent。历史明确记录两条工作线曾经并行存在。

我会在需要保留集成边界时使用 merge，例如合入一个完整功能分支。想明确保留这个边界，可以：

Terminal window

1
git merge --no-ff topic

`rebase`：复制 commit，换一组 parent#

在 topic 上执行：

Terminal window

1
git switch topic
2
git rebase main

Git 找到共同祖先 O，取出 C、D 引入的补丁，再以 B 为新基底重放，得到新 commit C'、D'：

maintopicOABC'D'

C' 与 C 的 parent 不同，所以 ID 必然不同；D' 的 parent 又变了，因此也有新 ID。rebase 不是”移动原 commit”，而是复制出一条语义相似的新历史，再移动分支引用。

我的规则很简单：

尚未共享的个人分支，可以 rebase、commit --amend、rebase --interactive；
已被其他人基于其开发的公开历史，不随意 rebase；
集成策略服从项目，不把”线性历史”当宗教。

交互式整理常用：

Terminal window

1
git rebase --interactive <base>

如果评审后只想把修补自动折叠进原 commit：

Terminal window

1
git commit --fixup=<commit>
2
git rebase --interactive --autosquash <base>

rebase 前后想确认 patch series 是否意外变化：

Terminal window

1
git range-diff <old-base>..<old-tip> <new-base>..<new-tip>

`cherry-pick`：复制选定的 commit#

Terminal window

1
git cherry-pick <commit>

它把某个 commit 引入的变化应用到当前 HEAD，再创建一个新 commit。因为 parent 通常不同，新 ID 也不同。适合把一个独立修复移到维护分支，不适合长期用来手工同步两条本应合并的分支。

冲突不是文件坏了，而是 Git 无法自动决定 3 方合并结果。先看：

Terminal window

1
git status
2
git diff

解决每个文件后暂存，再继续对应操作：

Terminal window

1
git add <resolved-path>
2
git merge --continue       # merge 场景
3
git rebase --continue      # rebase 场景
4
git cherry-pick --continue # cherry-pick 场景

不想继续时，使用相应的 --abort，不要边慌边 reset --hard。

远端不是云端魔法，只是另一个仓库#

origin 只是远端的默认昵称，不是 Git 的保留关键字。查看配置：

Terminal window

1
git remote --verbose
2
git remote get-url origin

一个本地仓库通常同时有：

1
refs/heads/main                 # 我的本地分支
2
refs/remotes/origin/main        # 我上次 fetch 后看到的远端状态
3
远端仓库的 refs/heads/main       # 远端此刻真正的分支

后两者不是同一个东西。origin/main 是本地的远端跟踪引用，它不会凭空知道服务器刚刚发生了什么。

远端仓库 origin

本地仓库 .git

fetch 缺少的对象

fetch 更新观察值

merge 或 rebase

push 缺少的对象

push 请求更新 ref

objects

refs/heads/main

本地 main

refs/remotes/origin/main

上次 fetch 的观察值

objects

refs/heads/main

远端此刻的 main

远端仓库 origin

本地仓库 .git

fetch 缺少的对象

fetch 更新观察值

merge 或 rebase

push 缺少的对象

push 请求更新 ref

objects

refs/heads/main

本地 main

refs/remotes/origin/main

上次 fetch 的观察值

objects

refs/heads/main

远端此刻的 main

关键是不把 origin/main 画到服务器里。它住在我的 .git 中，是一次成功 fetch 留下的本地观察值；网络断开以后，它当然不会自己刷新。

`fetch`：下载对象，更新远端跟踪引用#

Terminal window

1
git fetch origin --prune

它与远端协商本地缺少的对象，接收 packfile，再按 refspec 更新 refs/remotes/origin/*。--prune 删除远端已经不存在的远端跟踪引用，但不会删除我的本地分支。

fetch 通常不改当前工作区、index 或本地 main，所以它是理解远端变化的好分界点：

Terminal window

1
git log --oneline --graph --decorate --all
2
git log --left-right --cherry-pick main...origin/main
3
git diff main...origin/main

`pull`：先 fetch，再选择一种集成策略#

git pull 不是与 fetch 并列的下载协议。它先 fetch，然后把上游分支集成进当前分支。真正需要决定的是第二步。

1. fetch

ff-only

rebase

no-rebase

远端 upstream

本地 origin/main

2. 如何集成？

只允许移动 main

复制本地 commit 到新基底

merge，必要时创建 M

本地 main

1. fetch

ff-only

rebase

no-rebase

远端 upstream

本地 origin/main

2. 如何集成？

只允许移动 main

复制本地 commit 到新基底

merge，必要时创建 M

本地 main

所以 pull 不是第四种历史操作。它只是把 fetch 与某一种已有的集成操作串起来。

我不喜欢让一个无参数 git pull 隐藏策略。现代、安全而可读的写法是明确选择：

Terminal window

1
git pull --ff-only   # 只允许快进，分叉就停下
2
git pull --rebase    # fetch 后把本地 commit 重放到上游
3
git pull --no-rebase # fetch 后 merge

对于还在建立心智模型的人，我更推荐拆成两步：

Terminal window

1
git fetch origin --prune
2
git log --oneline --graph --decorate --all
3
git rebase origin/main  # 或 git merge origin/main

这样每个命令只做一类事，出错时也知道哪一层出了问题。Git 版本之间默认 pull 策略可能变化，项目策略也不同；显式参数比背默认值可靠。

长期配置应选自己和团队真正采用的策略，例如：

Terminal window

1
git config --global pull.ff only
2
# 或
3
git config --global pull.rebase true

不要把两条都照抄。ff-only 在本地与上游分叉时停止；rebase 会重写本地尚未发布的 commit。它们表达不同政策。

`push`：上传缺少的对象，请远端移动 ref#

第一次发布分支：

Terminal window

1
git push --set-upstream origin topic

--set-upstream（缩写 -u）建立本地 topic 与上游分支的关系。以后在 push.default=simple 的常见配置下，可以直接：

Terminal window

1
git push

push 分成两件事：

把远端缺少的可达对象发送过去；
请求远端把某个 ref 从旧 ID 更新到新 ID。

普通 push 默认要求更新是 fast-forward，也就是远端旧 tip 必须是新 tip 的祖先。否则 Git 拒绝 non-fast-forward，因为直接移动 ref 可能让别人已发布的 commit 失去分支入口。

是

否

push：远端旧 tip R -> 本地新 tip N

R 是 N 的祖先吗？

fast-forward

允许把远端 ref 移到 N

non-fast-forward

默认拒绝

先 fetch 并集成远端历史

或确认后使用 force-with-lease

是

否

push：远端旧 tip R -> 本地新 tip N

R 是 N 的祖先吗？

fast-forward

允许把远端 ref 移到 N

non-fast-forward

默认拒绝

先 fetch 并集成远端历史

或确认后使用 force-with-lease

服务器检查的是可达关系，不是比较谁的时间戳更新。如果远端 tip 不是本地 tip 的祖先，直接移动 ref 就可能把一段别人仍需要的历史甩出分支可达范围。

如果我确实 rebase 了自己的远端分支，需要改写它，我使用：

Terminal window

1
git push --force-with-lease

它比 --force 多一个租约条件：远端 ref 必须仍是我预期的值，否则拒绝覆盖。需要最严格地表达预期值时，可以写：

Terminal window

1
git push \
2
  --force-with-lease=refs/heads/topic:<expected-old-oid> \
3
  origin topic

裸 --force-with-lease 通常以本地远端跟踪引用作为预期值；后台自动 fetch 可能更新这个依据，所以它不是绝对保险。--force 则直接关闭这层保护，可能丢掉远端 commit。我不会把 push -f 做成 shell alias，这种便利与拔掉烟雾报警器差不多。

撤销操作：先问要改哪一层#

Git 最让人害怕的地方通常不是保存，而是撤销。只要先回答两个问题，命令会清楚很多：

要改工作区、index、branch ref，还是追加一个反向 commit？
目标历史是否已经共享？

常用决策表#

意图	推荐命令	改动层	是否改写 branch 历史
丢弃未暂存的路径修改	`git restore <path>`	工作区	否
取消暂存并保留工作区	`git restore --staged <path>`	index	否
从某快照恢复路径	`git restore --source=<rev> <path>`	工作区	否
修正最后一次未发布提交	`git commit --amend`	commit + ref	是
撤销已发布提交	`git revert <commit>`	新增反向 commit	否
本地分支退回但保留暂存	`git reset --soft <rev>`	ref	是
本地分支退回并重置 index	`git reset --mixed <rev>`	ref + index	是
本地分支、index、工作区全退回	`git reset --hard <rev>`	三者	是，并丢工作区修改
找回刚刚移丢的 commit	`git reflog`	只查看日志	否

restore 面向路径，reset 主要移动当前 branch 并按模式决定是否同步 index 和工作区，revert 则创建新 commit。名字相似，历史兼容性完全不同。

`revert` 为什么适合公开历史#

Terminal window

1
git revert <bad-commit>

它不删除坏 commit，而是计算反向变化并创建一个新 commit。所有协作者仍共享同一条已有历史，只需继续 fast-forward。对于已经推送到公共分支的错误，这通常是最无聊也最安全的方案。

reflog：引用移动的本地黑匣子#

我做了一个故意的事故：先记住第二个 commit 0063127，再把 main 硬重置回第一个 commit：

Terminal window

1
git reset --hard cd5e714

git log 看不到第二个 commit 了，但 git reflog --oneline 仍显示：

1
cd5e714 HEAD@{0}: reset: moving to cd5e714...
2
0063127 HEAD@{1}: commit: feat: advance the app
3
cd5e714 HEAD@{2}: commit (initial): feat: build the first snapshot

于是我恢复：

Terminal window

1
git reset --hard 0063127

main 又回到了第二个 commit。reflog 记录启用了日志的 refs 与 HEAD 的近期移动；普通非裸仓库通常会记录 HEAD 和本地分支，但不是所有引用都必然有 reflog。它不会 push 到远端，也不是永久备份；条目会过期，不可达对象最终可能被垃圾回收。但在误操作之后，第一反应应该是停止继续改写，运行 git reflog，给目标 commit 新建分支：

Terminal window

1
git branch rescue 0063127

这条更稳妥的恢复路径最终得到下面这张历史图：

mainrescuecd5e7140063127

main 仍停在 cd5e714，而新建的 rescue 重新指向 0063127。这张图描述的是恢复后的 commit DAG，不是重新执行 commit 的过程：git branch rescue 0063127 只补回一个引用，没有创建 0063127。

只要对象还在，名字丢了通常比内容丢了容易修。

Note

图里的 reflog 是恢复窗口，不是永久引用或远端备份。不要把”现在还能找回”理解成”永远不会被回收”。

Git 为什么不会为每个版本保存一整份大文件#

为了观察物理存储，我创建了一个 255000 字节文本文件，提交后只追加 15 字节，再提交一次。两个 blob 的逻辑大小分别是：

1
255000 bytes
2
255015 bytes

在运行 git gc 前，实验仓库有 15 个 loose objects，zlib 压缩后合计 44641 字节。运行：

Terminal window

1
git gc
2
git verify-pack -v .git/objects/pack/*.idx

packfile 变成 14239 字节，索引为 1492 字节。verify-pack 显示较新的 255015 字节 blob 在 pack 中占 13080 字节，旧版本则被表示成深度 1 的 delta，数据只有 15 字节（加上对象编码后占 26 字节）。仅比较原 44641 字节 loose objects 与 14239 字节 pack，主体存储缩小约 68.1%。

这解释了两个看似矛盾的事实：

Git 的逻辑模型是完整快照；
Git 的物理 packfile 可以跨相似对象做 delta compression。

packfile：一种物理编码

逻辑模型：两个完整 blob

ID 不变

blob A

255000 bytes

blob B

255015 bytes

保存 blob B 的基底

blob A 的 delta

数据 15 bytes

packfile：一种物理编码

逻辑模型：两个完整 blob

ID 不变

blob A

255000 bytes

blob B

255015 bytes

保存 blob B 的基底

blob A 的 delta

数据 15 bytes

左边回答”对象是什么”，右边回答”这次 pack 如何省空间”。重新打包可以更换基底和 delta 链，却不能改动对象按完整内容计算出的 ID。

对象的 ID 仍由规范化的完整内容决定，不由”它是哪个对象的 delta”决定。Git 可以随时重新打包而不改变 commit ID。git gc、push 和服务端维护可能触发打包；日常不需要手工管理每个 pack。

我最后运行：

Terminal window

1
git fsck --full

命令没有输出并以 0 退出，表示这份小仓库的对象连通性和有效性检查通过。

clone 到底复制了什么#

Terminal window

1
git clone <url> project

概念上它做了这些事：

创建本地仓库；
配置默认远端 origin；
与远端协商并下载所需对象；
建立远端跟踪引用；
创建并检出默认本地分支。

工作区本地 .git远端仓库Git 客户端工作区本地 .git远端仓库Git 客户端我git clone URL project创建仓库并配置 origin协商 refs 与缺少的对象发送 packfile 与远端 ref 值建立 origin/main 与本地 main检出默认分支快照我

clone 之后出现的是一个能独立工作的本地仓库，而不是远端文件夹的网络映射。origin 只是把这个新仓库与来源仓库重新连起来的配置。

Git 是分布式版本控制系统，因为普通 clone 通常拥有项目历史和对象数据库，不只是服务器工作区的一个薄视图。离线时我仍能 log、diff、branch、commit、merge 和 rebase；只有与别的仓库交换对象和 refs 时才需要网络。

大仓库可以选择浅克隆、部分克隆或稀疏检出，但三者解决不同问题：

Terminal window

1
git clone --depth=1 <url>           # 截断历史深度
2
git clone --filter=blob:none <url>  # 按需获取 blob
3
git sparse-checkout set src docs    # 限制工作区展开路径

不要把它们统称为”只下载一部分代码”。浅克隆改变可用历史，partial clone 延迟对象获取，sparse-checkout 主要改变工作区呈现。

多任务开发：`worktree` 比反复 stash 更直接#

当我正在 feature 分支写到一半，突然要修 main 上的线上 bug，传统动作常常是 stash、switch、修复、切回、pop，然后祈祷 stash 冲突别来凑热闹。

更清楚的方式是附加工作树：

Terminal window

1
git worktree add -b hotfix ../project-hotfix main

同一个仓库对象数据库现在对应两个工作目录：原目录继续停在 feature，新目录检出 hotfix。两边有各自的 HEAD 和 index，共享 objects 和大部分 refs。

project-hotfix/：附加 worktree

project/：主 worktree

共享的 common Git dir

checkout / restore

add

checkout / restore

add

读写共享对象

objects

全部 commit、tree、blob

refs/heads/feature

refs/heads/hotfix

HEAD

独立 index

工作目录

未完成的 feature 修改

HEAD

独立 index

工作目录

hotfix 修改

project-hotfix/：附加 worktree

project/：主 worktree

共享的 common Git dir

checkout / restore

add

checkout / restore

add

读写共享对象

objects

全部 commit、tree、blob

refs/heads/feature

refs/heads/hotfix

HEAD

独立 index

工作目录

未完成的 feature 修改

HEAD

独立 index

工作目录

hotfix 修改

worktree 不是再 clone 一次。昂贵的对象数据库和大部分 refs 只保留一份；每个工作树只增加自己的工作目录、HEAD、index 与少量管理状态。于是两个任务可以同时脏、同时运行构建，却不会争夺同一份 checkout。

同一个本地 branch 默认不能同时检出到两个 worktree。这层保护避免两个目录都试图移动同一个 branch ref，却给人一种自己互不相关的错觉。

完成后再移除附加工作树：

Terminal window

1
git worktree remove ../project-hotfix

这对并行运行测试、比较两个版本，以及让多个 AI agent 各自在独立分支工作尤其有用。它不是复制两份完整仓库，也避免一个工作区被不同任务来回覆盖。

git stash 仍适合很短的临时收纳：

Terminal window

1
git stash push --include-untracked -m 'wip: parser experiment'
2
git stash list
3
git stash show --patch stash@{0}
4
git stash pop

但 stash 本质上仍由 commit-like 对象和 refs 管理，不是神秘抽屉。我会给它消息，并尽快处理；需要跨天保存或交给别人时，临时分支上的普通 commit 更可见、更可审查。

一套我现在愿意长期使用的命令行#

初始配置#

Terminal window

1
git config --global user.name 'Your Name'
2
git config --global user.email 'you@example.com'
3
git config --global init.defaultBranch main
4
git config --global fetch.prune true
5
git config --global merge.conflictStyle zdiff3
6
git config --global rerere.enabled true

这里前两项进入 commit 身份；fetch.prune 清理失效的远端跟踪引用；zdiff3 在冲突标记中显示 base，帮助判断双方分别改了什么；rerere 记录冲突解决结果，在相同冲突再次出现时复用。签名、凭据管理、换行符和 pull 策略依平台与团队而定，不适合复制一份”万能配置”。

检查配置来源比只看最终值更有用：

Terminal window

1
git config --list --show-origin

每日开始#

Terminal window

1
git switch main
2
git fetch origin --prune
3
git pull --ff-only
4
git switch -c feature/readable-name

如果项目要求 rebase 工作流，我会显式采用它，而不是同时配置互相冲突的习惯。

制作原子 commit#

Terminal window

1
git status --short --branch
2
git diff
3
git add --patch
4
git diff --staged
5
git commit

commit message 解释变化的意图和原因。标题能独立读懂，正文写约束、权衡和行为变化；不要把 update files 这种只能证明键盘工作过的句子留给历史。

同步并复核#

Terminal window

1
git fetch origin --prune
2
git rebase origin/main
3
git range-diff origin/main...@{upstream} origin/main...HEAD
4
git push --set-upstream origin HEAD

@{upstream} 需要当前分支已经配置 upstream；首次发布前没有它。HEAD 作为 push 源表示当前分支 tip，但目标命名和权限仍由 refspec、配置和服务端规则决定。团队若使用 merge，则换成对应流程，不要为了套模板偷偷改写历史。

阅读历史#

Terminal window

1
git log --oneline --graph --decorate --all
2
git log --first-parent main
3
git show <commit>
4
git diff <a>..<b>
5
git blame -L <start>,<end> -- <path>

blame 回答”这一行最后由哪个 commit 引入”，不是”该怪谁”。拿到 commit 后继续 git show 和阅读上下文，通常才有答案。

定位引入 bug 的 commit#

当我有一个可重复判定好坏的命令时，bisect 通常能在 NNN 个 commit 中用大约 log⁡2N\log_2 Nlog2N 次判断定位边界。在线性、每个候选都可测试的理想历史中，1024 个候选 commit 约需 10 轮，而不是从头读 1024 次 diff；复杂 merge DAG 和被跳过的 commit 会增加轮数，甚至让 Git 无法唯一定位。

Terminal window

1
git bisect start
2
git bisect bad HEAD
3
git bisect good <known-good>
4
git bisect run ./reproduce.sh
5
git bisect reset

reproduce.sh 必须以 0 表示 good，1 到 127（除 125）表示 bad，125 表示无法测试。这个脚本值得认真写，因为错误的 oracle 会高效地把我带到错误答案，计算机在这方面一如既往地非常配合。

哪些旧习惯该换，哪些只是需要理解#

旧习惯或高风险写法	我现在使用	原因
`git checkout <branch>`	`git switch <branch>`	明确表达切分支
`git checkout -- <path>`	`git restore <path>`	明确表达覆盖工作区路径
`git reset HEAD <path>`	`git restore --staged <path>`	明确表达取消暂存
无参数 `git pull`	显式 `--ff-only`、`--rebase` 或 `--no-rebase`	明确集成策略
`git push --force`	`git push --force-with-lease`	避免覆盖意外出现的远端更新
`git filter-branch`	`git filter-repo` 等专用工具	官方文档明确警告其安全和性能陷阱
用 stash 在任务间来回切	`git worktree add`	两个工作目录保持独立 index 与工作状态
一次 `git add .` 后盲提交	`add -p` + `diff --staged`	设计并验证 commit 边界

这里最重要的修正是：旧不等于废弃，现代也不等于更短。 checkout、reset 和 merge 都仍然是合法且必要的 Git 概念。我要淘汰的是含糊意图和无保护的危险默认，而不是为了追新把能工作的命令全部换皮。

git filter-branch 是少数官方文档直接写着”不推荐使用”的例子；文档建议改用 git filter-repo 等替代工具。反过来，git checkout 并没有这种弃用声明。准确区分”职责过载，所以有更清晰的新命令”和”官方明确不推荐”，比传播一张真假混合的现代化清单更重要。

把 AI 放回正确的位置#

理解这些内部结构后，我并不打算少用 AI。恰恰相反，我可以给出更准确、也更可验证的任务：

1
请先展示工作区与 index 的 diff，只暂存解析器修复相关 hunk；
2
创建一个原子 commit；fetch 后不要直接 pull；
3
比较当前分支与 origin/main，再告诉我应 merge 还是 rebase；
4
禁止 force，确需改写个人远端分支时使用 force-with-lease。

这比”帮我把代码传上去”多了一点字，却把数据损失、历史策略和 commit 边界都变成了显式约束。AI 能替我执行命令，但它不能替我承担仓库策略。至少目前如此，我怀疑以后也仍然如此：工具会越来越善于推断意图，而真正稀缺的东西会变成能否清楚表达意图，并检查结果是否符合约束。

如果未来的 Git UI 只剩一个”完成我的修改”按钮，底层大概率仍要回答今天这些问题：下一张快照是什么，哪条引用应该移动，是否允许改写已经共享的历史，远端当前值是否仍符合预期。按钮可以消失，状态机不会。

我现在仍会让 AI 帮我 rebase、拆 commit、找回 reflog 里的对象，甚至写那段无聊的 bisect oracle。但当它说”已完成”时，我至少知道该看 status、diff --staged、log --graph 和 refs，而不是只看终端最后一行是不是绿色。很好，接下来终于可以放心地让机器替我敲命令了。

继续拆下去#

一台不存在的计算机：QEMU 工作原理与实践

Fri, 04 Sep 2026 14:00:00 GMT

写完 Kconfig 和 Kbuild 之后，我已经能配置、编译并加载一个 Linux 内核模块，却发现实验台中央还摆着一块巨大的黑盒：我会复制一行 qemu-system-x86_64 命令，但不知道它究竟造了哪台机器、CPU 在哪里执行、磁盘为何既是文件又是设备，也不知道按下 Ctrl+A X 时到底在和谁说话。于是我写了一个 512 字节启动扇区，把它放进 QEMU 10.2.4，又从 QMP、Device Tree 和一份 992 字节的 AArch64 ELF 反向拆开这台并不存在的计算机。

TCG

KVM

Guest 指令

加速器

翻译成 Host 指令

让 Host CPU 执行

Machine 与内存映射

设备前端

块、网络、字符后端

固件或直接内核启动

HMP / QMP / GDB

TCG

KVM

Guest 指令

加速器

翻译成 Host 指令

让 Host CPU 执行

Machine 与内存映射

设备前端

块、网络、字符后端

固件或直接内核启动

HMP / QMP / GDB

这张图是本文的地图。QEMU 不是单纯的”虚拟 CPU”，也不是一个好看的虚拟机窗口。它把指令执行、整机拓扑、设备模型、宿主机后端和控制接口拼成一个进程。命令行之所以长，只是因为我们在一行文本里描述了一台计算机。

先把名字拆开#

QEMU 最常见的 3 组程序做的是不同事情：

程序	输入	模拟范围	典型用途
`qemu-system-x86_64`、`qemu-system-aarch64`	固件、内核、磁盘和设备参数	CPU、内存、总线、中断控制器、设备等整机	启动操作系统、固件和裸机程序
`qemu-aarch64`、`qemu-riscv64`	某个目标架构的用户态 ELF	指令集、系统调用、信号和线程接口	在 x86_64 Linux 上运行或测试异构 Linux 程序
`qemu-img`	磁盘镜像	不运行 Guest	创建、检查、转换、比较镜像

另外 3 个名字经常与它混在一起：

KVM 是 Linux 内核里的虚拟化接口。它让兼容架构的 Guest 指令直接在硬件虚拟化模式中执行，但不负责给我造 UART、网卡和磁盘。
QEMU 可以只用 TCG 完成跨架构模拟，也可以调用 KVM 执行 vCPU，同时继续提供设备模型和进程生命周期。
libvirt 是更高一层的管理 API。它探测能力、生成 QEMU 参数并管理网络、存储和生命周期；virsh 和 virt-manager 通常站在这一层。

所以”QEMU 还是 KVM”不是一个很好的二选一。常见的 Linux 虚拟机恰好是 QEMU + KVM：KVM 跑 CPU，QEMU 造其余机器。只写 qemu-system-x86_64 而不指定加速器时，QEMU 默认使用 TCG；安装了 KVM 并不等于这条命令自动用上它。

本文固定在以下实验环境：

项目	实验值
Host	x86_64 Linux
QEMU	`10.2.4`
GNU Binutils	`2.46`
Guest 实验 1	16-bit x86 裸机启动扇区
Guest 实验 2	AArch64 Linux 用户态静态 ELF
加速器	TCG 与 KVM 均实际启动

先问正在使用的二进制，而不是问搜索引擎记得哪个版本：

Terminal window

1
qemu-system-x86_64 --version
2
qemu-system-x86_64 -accel help
3
qemu-system-x86_64 -machine help
4
qemu-system-x86_64 -cpu help
5
qemu-system-x86_64 -device help
6
qemu-system-x86_64 -nic help
7
qemu-system-x86_64 -display help

在我的 QEMU 10.2.4 构建中，x86_64 的 -machine help 打印 43 行 machine 类型，-device help 列出 455 个设备模型；AArch64 的 machine 列表则有 113 行。这里包含版本化 machine 和别名，不能直接当成 113 块不同开发板，但它已经很好地解释了为什么背命令行是个坏主意。QEMU 自己就是可查询的硬件目录。

一条命令其实在描述什么？#

我会把 system emulator 的参数按 7 层阅读：

1
qemu-system-$ARCH \
2
  [machine] [cpu] [accelerator] \
3
  [devices] [backends] [interfaces] [boot]

层	回答的问题	常见参数
Machine	这是什么板子，地址图和默认设备是什么？	`-machine`、`-m`、`-smp`
CPU	Guest 看见哪种 CPU 和哪些 feature？	`-cpu`
Accelerator	指令由 TCG 翻译还是交给 Hypervisor？	`-accel`
Device	Guest 驱动看见什么硬件？	`-device`
Backend	设备的数据通向 Host 哪里？	`-blockdev`、`-netdev`、`-chardev`
Interface	人和管理程序怎样观察、控制和调试？	`-display`、`-serial`、`-qmp`、`-gdb`
Boot	第一条 Guest 代码来自哪里？	`-bios`、`-kernel`、`-initrd`、`-append`、`-drive`

这里最有用的分界是 device 与 backend。virtio-net-pci 是 Guest 能枚举并由驱动绑定的 PCI 设备；user、tap 或 passt 是 Host 侧真正收发包的后端。virtio-blk-pci 是 Guest 磁盘控制器；raw 文件、qcow2 文件或 Host 块设备是后端。前者像插座，后者像插座后面的电线，只是这个比喻用一次就够了。

我先启动 512 字节，而不是一个发行版#

如果一上来就启动 Debian，屏幕上会同时出现固件、引导器、内核、initramfs、systemd 和虚拟硬件。每一层都可能成功地遮住上一层。为了只观察 QEMU，我写了一个 BIOS 启动扇区：初始化 COM1，输出一行字，然后向测试退出设备写一个值。

1
.code16
2
.global _start
3

4
_start:
5
  cli
6
  xorw %ax, %ax
7
  movw %ax, %ds
8
  movw %ax, %ss
9
  movw $0x7c00, %sp
10

11
  # COM1: 115200 baud, 8N1, FIFO on.
12
  movw $0x3f9, %dx
13
  xorb %al, %al
14
  outb %al, %dx
15
  movw $0x3fb, %dx
16
  movb $0x80, %al
17
  outb %al, %dx
18
  movw $0x3f8, %dx
19
  movb $0x01, %al
20
  outb %al, %dx
21
  movw $0x3f9, %dx
22
  xorb %al, %al
23
  outb %al, %dx
24
  movw $0x3fb, %dx
25
  movb $0x03, %al
26
  outb %al, %dx
27
  movw $0x3fa, %dx
28
  movb $0xc7, %al
29
  outb %al, %dx
30
  movw $0x3fc, %dx
31
  movb $0x0b, %al
32
  outb %al, %dx
33

34
  movw $message, %si
35
print:
36
  lodsb
37
  testb %al, %al
38
  jz done
39
  movb %al, %ah
40
wait_tx:
41
  movw $0x3fd, %dx
42
  inb %dx, %al
43
  testb $0x20, %al
44
  jz wait_tx
45
  movb %ah, %al
46
  movw $0x3f8, %dx
47
  outb %al, %dx
48
  jmp print
49

50
done:
51
  movw $0xf4, %dx
52
  movb $0x10, %al
53
  outb %al, %dx
54
  hlt
55

56
message:
57
  .asciz "hello from sector 0\r\n"
58

59
.org 510
60
.word 0xaa55

展开收起

构建时我先链接 ELF，让 message 得到以 0x7c00 为基准的正确地址，再只抽取 .text：

Terminal window

1
as --32 -o boot.o boot.S
2
ld -m elf_i386 -Ttext 0x7c00 -o boot.elf boot.o
3
objcopy -O binary --only-section=.text boot.elf boot.bin
4
stat --format='%n %s bytes' boot.bin

输出刚好是：

1
boot.bin 512 bytes

最后 16 字节为：

1
00 00 00 00 00 00 00 00 00 00 00 00 00 00 55 aa

0x55 0xaa 位于偏移 510，BIOS 才把它当成可启动扇区。现在启动：

Terminal window

1
qemu-system-x86_64 \
2
  -machine pc,accel=tcg \
3
  -drive file=boot.bin,format=raw,if=floppy \
4
  -display none \
5
  -serial stdio \
6
  -monitor none \
7
  -no-reboot \
8
  -device isa-debug-exit,iobase=0xf4,iosize=0x04

实际输出只有一行：

1
hello from sector 0

进程退出码为 33。这不是随机事故。isa-debug-exit 收到 0x10 后按 (value << 1) | 1 生成退出码，所以得到 0x10×2+1=330x10 \times 2 + 1 = 330x10×2+1=33。这个设备不是现实 PC 上的标准零件，而是我明确加进实验机的测试出口。Guest 写一个 I/O port，QEMU 的设备回调收到访问并结束 Host 进程。512 字节代码已经跨过了 CPU、I/O 地址空间、UART、字符后端和进程生命周期 5 层。

从复位向量到 `0x7c00`#

这条路径仍有固件参与：

Host16550A UARTGuest RAM虚拟软盘SeaBIOSx86 vCPUHost16550A UARTGuest RAM虚拟软盘SeaBIOSx86 vCPU从复位向量开始执行读取第 0 扇区放到物理地址 0x7c00跳到 0x7c00OUT 到 COM1写入 stdio chardev

boot.bin 不是 Host 进程可直接执行的 ELF。SeaBIOS 经虚拟软盘控制器读它，检查签名并复制到 Guest RAM。我的 outb 也没有直接碰 Host 的物理串口；QEMU 捕获 Guest I/O 指令，把访问路由到 16550A 设备模型，再由 -serial stdio 连接终端。

我把 -accel tcg 换成 -accel kvm 后，同一个扇区也输出同一行并以 33 退出。可观察的 machine contract 没变，变化的是 vCPU 执行引擎。这正是加速器应该有的边界。

TCG 到底模拟了什么？#

TCG 是 Tiny Code Generator。粗略但有用的数据流是：

分支、异常、I/O、失效

Guest 指令

Guest 前端解码

TCG 中间操作

Host 后端生成代码

Translation Block 缓存

Host CPU 执行

分支、异常、I/O、失效

Guest 指令

Guest 前端解码

TCG 中间操作

Host 后端生成代码

Translation Block 缓存

Host CPU 执行

QEMU 通常以 translation block 为单位翻译一段 Guest 指令，而不是每执行一条就启动一次解释器。已经生成的 Host 代码可以缓存和复用；控制流、异常、自修改代码、MMIO 等事件再让执行返回 QEMU。具体边界是实现细节，不能把 TB 简化成 C 语言 basic block 的永久一一映射。

TCG 的价值不是”比硬件快”，而是 Host 与 Guest 架构可以不同。x86_64 Host 能运行 AArch64、RISC-V、MIPS 等 Guest，也能提供较强的可观察性、确定性相关选项和软件断点能力。代价是翻译、状态同步和设备模拟都有成本。

常用写法：

Terminal window

1
qemu-system-aarch64 \
2
  -machine virt,accel=tcg \
3
  -cpu max \
4
  -smp 4

-cpu max 表示 TCG 能提供的丰富功能集合，不代表某颗真实 SoC。若目标是复现 Cortex-A57 的行为，就应选 -cpu cortex-a57，并接受这个模型实现了什么、不实现什么。

-accel tcg,thread=multi 允许支持的目标为多个 vCPU 使用多个 TCG 线程。它不保证 4 个 Guest vCPU 就得到 4 倍性能；锁竞争、设备路径和 Guest 工作负载都在场。one-insn-per-tb=on 则故意把每个 TB 缩到一条指令，适合分析日志，不适合假装性能还正常（这次真的不能两全）。

KVM 为什么快，又为什么仍然需要 QEMU？#

当 Host 与 Guest 架构兼容、CPU 支持硬件虚拟化且 /dev/kvm 可用时，可以写：

Terminal window

1
qemu-system-x86_64 \
2
  -machine q35 \
3
  -accel kvm \
4
  -cpu host \
5
  -m 2G \
6
  -smp 4

QEMU 通过 KVM API 创建 VM 和 vCPU，把 Guest RAM 注册给内核，然后让 vCPU 进入硬件虚拟化执行。普通 Guest 指令不必先翻译成 Host 指令；遇到需要 Host 处理的事件，例如某些 I/O、MMIO 或停机状态，KVM 退出到 QEMU，QEMU 再运行对应设备逻辑。

QEMU device modelHost CPU/dev/kvmQEMUQEMU device modelHost CPU/dev/kvmQEMU创建 VM、vCPU、映射 Guest RAMKVM_RUN进入 Guest modeMMIO/PIO 等 VM exit返回 exit 原因执行设备访问返回结果再次 KVM_RUN

-cpu host 暴露 Host CPU 的大量特性，通常适合单机开发和性能实验，却会把 VM 绑得更紧。需要跨不同 Host live migration 时，应选择双方共同支持的命名 CPU model 和 feature 集，而不是默认假设另一台机器也长着同一颗 CPU。

我不会用 512 字节启动扇区比较 TCG 与 KVM 性能。这个 workload 的 Guest 只输出 21 个字符，QEMU 进程启动和固件执行占据了绝大多数时间；测出来的主要是噪声，不是 CPU 加速比。要比较加速器，至少应固定 machine、CPU feature、vCPU 数、Guest 镜像和 workload，再分别测 Guest 内部 CPU 时间、I/O 吞吐与 Host 消耗。

也不要把 KVM 当成安全魔法。QEMU 的设备模型仍然处理 Guest 提交的数据，QEMU 官方文档明确指出 TCG 不是安全边界；测试不可信镜像时仍应使用非特权账户、最小设备集合、受控网络和宿主机沙箱策略。

Machine 不是一个无关紧要的名字#

Machine type 决定主板级拓扑：地址空间、总线、芯片组、中断控制器、固件接口和一组默认设备。CPU 只是板子上的一个节点。

x86_64 常见两族是：

pc-i440fx-*：较老的 i440FX + PIIX PC 平台，兼容面广。
pc-q35-*：较现代的 Q35 + ICH9 平台，原生 PCIe 拓扑更符合新设备。

我的 QEMU 10.2.4 默认项是 pc-i440fx-10.2，而 pc 是指向当前默认版本的别名。用于一次性内核实验时，别名很方便；用于长期保存或迁移的 VM 时，应记录版本化 machine，例如 pc-q35-10.2。升级 QEMU 后，q35 别名可能指向新兼容级别，而版本化名字存在的目的正是固定 Guest 可见的硬件 contract。

ARM 更能暴露这个事实。x86 PC 长期有相对统一的启动和硬件传统；ARM 镜像往往绑定到具体 SoC、UART 地址、中断控制器和 Device Tree。qemu-system-aarch64 因此没有默认 machine，必须写：

Terminal window

1
qemu-system-aarch64 -machine virt

virt 不是某块真实开发板。它是专门为虚拟化设计的通用平台，提供可配置 CPU、RAM、PL011、GIC、PCI/PCIe、VirtIO 和生成的 Device Tree。若目的是学习 Linux、U-Boot 和驱动框架，它通常比假装某块量产板更干净；若目的是复现真实板卡寄存器和启动 ROM，就必须检查 -machine help 是否真的包含那块板。没有 machine model 时，一份真实固件不会因为加上 -dtb board.dtb 就突然能运行。DTB 描述硬件，不负责实现硬件。

我让 QEMU 自己交出 ARM 硬件图#

QEMU 可以把 virt machine 生成的 DTB 写出来：

Terminal window

1
qemu-system-aarch64 \
2
  -machine virt,dumpdtb=virt.dtb \
3
  -cpu cortex-a57 \
4
  -m 256M \
5
  -display none
6

7
dtc -I dtb -O dts -o virt.dts virt.dtb

QEMU 写出的 virt.dtb 是一个预留到 1,048,576 字节的 blob。反编译后，关键节点包括：

1
memory@40000000 {
2
  reg = <0x00 0x40000000 0x00 0x10000000>;
3
  device_type = "memory";
4
};
5

6
pl011@9000000 {
7
  interrupts = <0x00 0x01 0x04>;
8
  reg = <0x00 0x9000000 0x00 0x1000>;
9
  compatible = "arm,pl011", "arm,primecell";
10
};
11

12
virtio_mmio@a000000 {
13
  interrupts = <0x00 0x10 0x01>;
14
  reg = <0x00 0xa000000 0x00 0x200>;
15
  compatible = "virtio,mmio";
16
};

展开收起

实验中的 -m 256M 变成从 0x40000000 开始、长度 0x10000000 的 RAM。串口是 0x09000000 的 PL011，chosen.stdout-path 也指向它。DTB 还预留了从 0x0a000000 到 0x0a003e00 的 32 个 VirtIO MMIO slot，每个间隔 0x200。命令行不再是一串咒语，它已经变成内核实际消费的硬件描述。

因此 ARM64 串口启动参数通常是：

1
console=ttyAMA0

而上一篇 x86_64 实验使用的是：

1
console=ttyS0

这不是 Linux 随机换了名字。两个 machine 分别提供 PL011 和 16550A 风格 UART，对应不同驱动与设备节点。

固件启动、磁盘启动和直接内核启动#

QEMU 可以从不同层进入 Guest。它们不是同一条路径的不同拼写。

1. 固件加磁盘#

典型 PC VM：

Terminal window

1
qemu-system-x86_64 \
2
  -machine q35,accel=kvm \
3
  -m 2G \
4
  -drive file=system.qcow2,format=qcow2

QEMU 启动 BIOS 或 UEFI 固件，固件枚举设备并选择启动项，随后进入磁盘里的引导器，再由引导器加载内核。适合安装和运行完整发行版，也最接近通用机器的启动链。

UEFI 的代码镜像通常只读，变量存储则需要单独的可写副本。不要让多个 VM 直接共享同一个可写变量镜像；Secure Boot key、BootOrder 和固件设置都在里面。

2. `-bios` 启动固件或裸机镜像#

对 ARM virt 上的 U-Boot v2026.07，官方文档给出的非安全启动是：

Terminal window

1
make qemu_arm64_defconfig
2
make
3

4
qemu-system-aarch64 \
5
  -machine virt \
6
  -cpu cortex-a57 \
7
  -nographic \
8
  -bios u-boot.bin

这里 QEMU 把 U-Boot 放进模拟 flash，从地址 0x0 执行，并把生成的 DTB 放在 RAM 开头。若要复现 EL3、TF-A 与 OP-TEE，则启动链和镜像组合会继续增加；不能拿一个非安全 u-boot.bin 命令假装已经验证 secure world。

3. `-kernel` 直接内核启动#

上一篇文章中，我用下面的命令启动自己构建的 Linux 6.18：

Terminal window

1
qemu-system-x86_64 \
2
  -machine accel=tcg \
3
  -cpu max \
4
  -m 256M \
5
  -smp 1 \
6
  -nographic \
7
  -no-reboot \
8
  -kernel arch/x86/boot/bzImage \
9
  -initrd initramfs.cpio \
10
  -append "console=ttyS0 rdinit=/init panic=-1"

它绕过 Guest 磁盘上的 GRUB 和 root filesystem 查找，直接把 kernel、initramfs 和 command line 交给 QEMU 的直接 Linux boot 路径。它很适合内核迭代：不必每次把 bzImage 复制进磁盘分区，也不必调试一个与当前问题无关的 bootloader。

ARM64 对应的实验骨架是：

Terminal window

1
qemu-system-aarch64 \
2
  -machine virt,accel=tcg \
3
  -cpu cortex-a57 \
4
  -m 512M \
5
  -smp 2 \
6
  -nographic \
7
  -no-reboot \
8
  -kernel arch/arm64/boot/Image \
9
  -initrd initramfs.cpio \
10
  -append "console=ttyAMA0 rdinit=/init panic=-1"

内核必须真的包含 virt 所需的 CPU、GIC、PL011、timer、PCI 或 VirtIO 支持。QEMU 能造出设备，不会替 Linux 打开 Kconfig。于是前两篇文章与这一篇形成了闭环：Kconfig 允许驱动存在，Kbuild 把驱动放进镜像，QEMU machine 决定启动后是否真有匹配的硬件。

`-nographic` 不等于 `-display none`#

这两个选项看起来接近，行为并不相同：

选项	图形窗口	串口	Monitor
`-display none`	不创建显示输出	不自动重定向	不自动重定向
`-nographic`	禁用图形输出	通常把串口接到 stdio	将 Monitor 与串口复用到 stdio
`-serial stdio -monitor none -display none`	无	只把串口接到 stdio	禁用 HMP

我在自动实验中偏爱第三种显式写法，因为日志里只有 Guest 串口，不会意外把 (qemu) Monitor prompt 混进去。交互调试时 -nographic 很方便：

Ctrl+A H 查看快捷键。
Ctrl+A C 在串口与 HMP Monitor 之间切换。
Ctrl+A X 退出 QEMU。

这些是 QEMU chardev multiplexer 的转义，不是 Guest 收到的 Ctrl+A。要把真的 Ctrl+A 送给 Guest，需要按两次 Ctrl+A。

console=ttyS0 或 console=ttyAMA0 同样不可省略。QEMU 把虚拟串口接到终端，只解决 Host 端；Linux command line 还要告诉内核把 console 写到哪个 Guest 设备。两边必须在同一根虚拟电线上见面。

设备前端与后端必须成对阅读#

考虑网络：

Terminal window

1
-netdev user,id=net0,hostfwd=tcp:127.0.0.1:2222-:22 \
2
-device virtio-net-pci,netdev=net0,mac=52:54:00:12:34:56

virtio-net-pci 是 Guest 枚举到的网卡。
netdev=net0 把它连到 ID 为 net0 的 Host backend。
user 选择无特权用户态网络栈。
hostfwd 把 Host 127.0.0.1:2222 转到 Guest TCP 22。

只写 -netdev 没有 Guest 网卡，Guest 无从发送；只写带 netdev=net0 的 -device 而没有同名 backend，QEMU 会在启动时拒绝这个悬空引用。ID 是这张图里的接线标签。

存储也一样。下面的显式 block graph 经 QEMU 10.2.4 启动验证：

Terminal window

1
qemu-system-x86_64 \
2
  -machine q35,accel=tcg \
3
  -nodefaults \
4
  -display none \
5
  -S \
6
  -blockdev driver=file,node-name=file0,filename=disk.qcow2 \
7
  -blockdev driver=qcow2,node-name=disk0,file=file0 \
8
  -device virtio-blk-pci,drive=disk0

数据路径为：

Guest virtio-blk driver

virtio-blk-pci device

qcow2 block node: disk0

file block node: file0

Host disk.qcow2

Guest virtio-blk driver

virtio-blk-pci device

qcow2 block node: disk0

file block node: file0

Host disk.qcow2

-drive file=...,format=qcow2,if=virtio 是方便的组合式旧入口；-blockdev 加 -device 更啰嗦，却把格式层、文件层和 Guest 设备层分开。要做 overlay、镜像过滤、throttle 或 live block operation 时，显式图更容易审查。

-nodefaults 会移除 machine 的常见默认设备。它适合可重复实验，但不是”删掉全部硬件”；machine 本身不可缺少的控制器和平台对象仍然存在。搭一台最小 VM 时，我会加它，然后只添加实验需要的串口、磁盘和网卡。

raw 与 qcow2 不是”大文件与小文件”#

我创建了两个虚拟容量均为 1 GiB 的空镜像：

Terminal window

1
qemu-img create -f raw disk.raw 1G
2
qemu-img create -f qcow2 disk.qcow2 1G
3
qemu-img info --output=json disk.qcow2

在支持 sparse file 的 Host filesystem 上，结果是：

镜像	Guest 虚拟容量	Host 文件逻辑长度	实际分配空间
raw	`1,073,741,824` B	`1,073,741,824` B	`4,096` B
qcow2	`1,073,741,824` B	`196,624` B	`200,704` B

空 raw 在这里反而只分配 4 KiB，因为它是 sparse file；qcow2 需要约 196 KiB 元数据。于是”qcow2 一定更省空间”在第 0 秒就是错的。两者真正的差别是格式与能力：

维度	raw	qcow2
布局	扇区偏移接近直接映射	L1/L2 table、cluster、refcount 等元数据
稀疏	依赖 Host filesystem	格式原生按 cluster 分配
backing file	无	有
internal snapshot	无	有
压缩/加密能力	格式本身无	支持特定模式
可移植和恢复	简单	需要理解 qcow2 元数据

我又创建了 overlay：

Terminal window

1
qemu-img create \
2
  -f qcow2 \
3
  -F qcow2 \
4
  -b "$PWD/disk.qcow2" \
5
  overlay.qcow2

它的虚拟容量仍是 1 GiB，初始实际分配 200,704 字节。读取未覆盖 cluster 时沿 backing chain 去 base，写入则进入 overlay。这个机制非常适合”一份只读基础镜像 + 多个实验分支”。

Backing chain 是数据结构，不是文件命名约定

移动、修改或删除 base 可能让 overlay 读到错误数据或直接打不开。创建时显式写 -F，用 qemu-img info --backing-chain 检查链，并在分发前用 qemu-img convert 或 rebase 按计划扁平化。不要在不理解 rebase -u 的情况下用它改元数据指针。

QEMU 里至少有 3 种容易都被叫作”快照”的东西：

-snapshot：写入临时 overlay，QEMU 退出后通常丢弃。本质上是一次性运行模式。
qcow2 internal snapshot：用 savevm、loadvm、delvm 保存磁盘与 VM state，受设备支持限制。
external snapshot/overlay：新 qcow2 文件以旧镜像为 backing file，链条显式存在，常用于管理系统。

快照不是备份。Guest filesystem 正在写入时抓到的镜像可能只是 crash-consistent；数据库一致性还需要 Guest 协作、freeze 或应用层 protocol。

VirtIO 为什么不是”模拟一块更快的真网卡”？#

QEMU 可以模拟 e1000、AHCI、NVMe 等现实设备，Guest 使用现实硬件驱动。这对兼容性和固件测试很重要，但每次寄存器访问与硬件语义都要模拟。

VirtIO 选择另一条路：它定义一种专为虚拟环境设计的标准设备 contract。Guest 驱动与 device 通过 virtqueue 交换 descriptor，批量描述 buffer，再用 notification 告知对方。它不需要假装自己是某块 20 年前的网卡。

QEMU/vhost backendVirtqueue in Guest RAMGuest driverQEMU/vhost backendVirtqueue in Guest RAMGuest driver写 descriptor 与 available ringnotification读取 buffer 并处理 I/O更新 used ringinterrupt 或轮询可见

这里还要区分 设备类型 与 transport：

virtio-blk、virtio-net、virtio-rng 描述设备功能。
virtio-*-pci 经 PCI capability 暴露。
virtio-*-device 在某些 machine 上经 VirtIO MMIO 或其他 bus 暴露。
split virtqueue 与 packed virtqueue 描述 ring layout，不是两种磁盘格式。

使用 VirtIO 的前提是 Guest 有对应驱动。initramfs 想从 /dev/vda 挂载 root 时，CONFIG_VIRTIO_BLK、transport 和必要的 PCI 支持必须内建，不能全做成等 root filesystem 挂载后才加载的模块。这又回到了 Kconfig，只是现在我们终于知道那个选项在为哪块虚拟硬件服务。

vhost 还能把部分 VirtIO 数据面移出 QEMU 主循环，例如 vhost-net 借助内核处理网络数据，vhost-user 则通过 Unix socket 连接独立 userspace backend。控制面、feature negotiation、内存共享和安全边界会变复杂，不能只因为名字里有 vhost 就默认打开。

网络：先用 user，理解后再上 TAP#

最省事的无特权配置是：

Terminal window

1
-netdev user,id=net0,hostfwd=tcp:127.0.0.1:2222-:22 \
2
-device virtio-net-pci,netdev=net0

QEMU user-mode network 的默认拓扑通常是：

1
Guest 10.0.2.15
2
  -> gateway 10.0.2.2
3
  -> DNS 10.0.2.3
4
  -> Host/Internet

Guest 位于 NAT 后面，Host 或局域网不能凭空主动连接它，所以 SSH 需要 hostfwd。绑定 127.0.0.1 比省略地址更保守，避免意外把实验 SSH 暴露到所有 Host 接口。

ICMP 是一个常见误判点。user backend 对外部 ping 的支持受 Host 与配置限制，ping 失败不能单独证明 TCP/DNS 坏了。先在 Guest 检查地址、route、DNS，再用实际要验证的 TCP/UDP 流量测试。

TAP 则在 Host 创建二层接口：

Terminal window

1
-netdev tap,id=net0,ifname=tap0,script=no,downscript=no \
2
-device virtio-net-pci,netdev=net0

它适合桥接到 Host bridge、构建多 VM 二层网络或做抓包实验，但创建和配置 TAP/bridge 通常需要额外权限。网络连不通时应分别检查：

Guest NIC 驱动是否绑定。
Guest link、地址和 route 是否正确。
QEMU device 是否连到正确 netdev ID。
TAP 是否 UP 并加入预期 bridge。
Host forwarding、防火墙和 NAT 是否允许流量。

passt 是另一种无特权 backend。它作为独立 daemon 工作，通常比内置 user-mode stack 提供更完整的 IPv6、性能和隔离特性。选择 backend 是网络拓扑与安全决策，不是 VirtIO 驱动决策。

QEMU user mode：只模拟一个进程#

为了确认 qemu-aarch64 和 system emulator 的边界，我写了一个不用 libc 的 AArch64 程序：

1
.global _start
2
.text
3
_start:
4
  mov x0, #1
5
  adr x1, message
6
  mov x2, #message_end - message
7
  mov x8, #64
8
  svc #0
9

10
  mov x0, #7
11
  mov x8, #93
12
  svc #0
13

14
message:
15
  .ascii "hello from AArch64 user mode\n"
16
message_end:

展开收起

交叉链接出一个 992 字节静态 ELF：

Terminal window

1
aarch64-linux-gnu-gcc \
2
  -nostdlib \
3
  -static \
4
  -Wl,--build-id=none \
5
  -o hello-aarch64 hello-aarch64.S
6

7
file hello-aarch64

file 确认它是：

1
ELF 64-bit LSB executable, ARM aarch64, statically linked

x86_64 Host 不能原生执行这份指令，但 user emulator 可以：

Terminal window

1
qemu-aarch64 -strace ./hello-aarch64

我实际看到：

1
write(1,0x400098,29)hello from AArch64 user mode
2
 = 29
3
exit(7)

进程退出码正是 7。这里没有 AArch64 BIOS、GIC、PL011、磁盘或第二个 Linux kernel。QEMU 翻译 AArch64 用户指令，拦截 svc，把 Guest ABI 的 write 和 exit 参数转换后交给 Host Linux kernel。

动态链接程序还需要目标架构的 loader 与 shared libraries：

Terminal window

1
qemu-aarch64 -L /path/to/aarch64-sysroot ./app

-L 指向 Guest ABI sysroot，不是随便一个包含 .so 的目录。混用错误架构、错误 dynamic linker 路径或不兼容 glibc 时，问题发生在 ABI 与文件系统视图，不在虚拟网卡，因为这里根本没有网卡。

user mode 适合交叉编译后的命令行程序测试、CI 和编译器工作；涉及 kernel driver、boot flow、真实 MMIO 或完整网络 namespace 语义时，应回到 system emulation。

HMP、QMP 和 Guest Agent 是 3 个平面#

HMP：给人使用的 Monitor#

HMP 是 (qemu) prompt 后面的交互命令：

1
(qemu) info status
2
(qemu) info registers
3
(qemu) info pci
4
(qemu) info block
5
(qemu) stop
6
(qemu) cont
7
(qemu) quit

它适合临时观察。输出面向人，会随版本调整，不应让生产脚本靠正则解析。

QMP：给程序使用的控制 API#

QMP 使用以 CRLF 分隔的 JSON object。连接建立后，server 先发送 greeting；client 必须完成 qmp_capabilities negotiation，随后才能发普通命令。下面是我实际运行的最小 Unix socket client 的核心：

1
import json
2
import socket
3

4
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
5
sock.connect("/tmp/qmp.sock")
6
stream = sock.makefile("rwb", buffering=0)
7

8
print(json.loads(stream.readline()))  # greeting
9

10
for request in [
11
    {"execute": "qmp_capabilities", "id": 1},
12
    {"execute": "query-status", "id": 2},
13
    {"execute": "query-kvm", "id": 3},
14
    {"execute": "query-cpus-fast", "id": 4},
15
    {"execute": "quit", "id": 5},
16
]:
17
    stream.write((json.dumps(request) + "\r\n").encode())
18
    while True:
19
        response = json.loads(stream.readline())
20
        if response.get("id") == request["id"]:
21
            print(response)
22
            break

展开收起

QEMU 由以下参数启动并停在第一条 Guest 指令之前：

Terminal window

1
qemu-system-x86_64 \
2
  -machine pc,accel=tcg \
3
  -m 64M \
4
  -S \
5
  -display none \
6
  -serial none \
7
  -monitor none \
8
  -qmp unix:/tmp/qmp.sock,server=on,wait=off

关键响应是：

1
{"return":{"status":"prelaunch","running":false},"id":2}
2
{"return":{"enabled":false,"present":true},"id":3}

present=true 表示该 QEMU binary 与环境存在 KVM 能力，enabled=false 则准确反映这台 VM 明确选择了 TCG。-S 让状态停在 prelaunch。我喜欢这种接口：没有从彩色日志猜心情，只有结构化状态。

QMP response 的 id 对应 request；event 则可能异步到来。客户端不能假设读到的下一行一定是刚才命令的 response，必须按 id 配对，并单独处理 event。生产代码还要处理 partial read、断连、schema/version 差异和 error object。

Guest Agent：进入 Guest OS 的通道#

QEMU Guest Agent 是 Guest 内运行的进程，常通过 virtio-serial 与 Host 管理层通信。它能报告 Guest IP、freeze filesystem、关机或执行受支持操作。QMP 能问 QEMU “vCPU 是否暂停”，却不能凭空知道 Guest 里的 ext4 是否 freeze；QGA 正是跨过这条边界。

不要把 QMP 或 GDB socket 暴露到不可信网络。它们通常没有应用层认证；能控制 VM 或调试 Guest 的接口本质上就是高权限接口。Unix socket 加严格文件权限是本地实验的稳妥默认值。

用 GDB 在第一条指令前拦住机器#

QEMU 内置 gdbstub。最短入口是：

Terminal window

1
qemu-system-x86_64 \
2
  -S \
3
  -s \
4
  -kernel arch/x86/boot/bzImage \
5
  -append "console=ttyS0"

-S：创建 machine，但不启动 vCPU。
-s：等价于 -gdb tcp::1234。

另一个终端连接：

Terminal window

1
gdb vmlinux
2
(gdb) target remote :1234
3
(gdb) hbreak start_kernel
4
(gdb) continue

调内核时应给 GDB vmlinux，不是压缩后的 bzImage。vmlinux 保留 ELF section 与 symbol；QEMU 启动的是可引导压缩镜像，两者承担不同角色。若 KASLR 让 runtime address 与 symbol address 不一致，可以在实验 command line 加 nokaslr，或者正确处理 relocation，而不是把断点下在希望它出现的地址。

调 16-bit 启动扇区时，连接后可用：

1
set architecture i8086
2
x/10i $cs*16+$eip
3
info registers

TCG 下 QEMU 可提供大量 hardware breakpoint/watchpoint；KVM 的能力取决于 accelerator 实现与硬件。user-mode TCG 还不支持 watchpoint。调试 multicore machine 时，每个 vCPU 会作为 GDB thread 暴露，多 cluster machine 还可能需要 target extended-remote 与多个 inferior。

为避免固定 TCP port 和误暴露，我更喜欢 Unix socket：

Terminal window

1
-chardev socket,path=/tmp/gdb.sock,server=on,wait=off,id=gdb0 \
2
-gdb chardev:gdb0 \
3
-S

GDB 9.0 及以上可以：

1
target remote /tmp/gdb.sock

日志、trace 和可重复执行#

串口日志、QEMU debug log 与 trace event 是 3 类不同证据：

-serial file:guest.log 记录 Guest 经 UART 输出的内容。
-d ... -D qemu.log 记录 QEMU 的执行或设备 debug 信息。
-trace ... 订阅代码中定义的 trace event。

先查询支持项：

Terminal window

1
qemu-system-x86_64 -d help
2
qemu-system-x86_64 -trace help

调早期启动常见写法：

Terminal window

1
-d guest_errors,int -D qemu.log

-d in_asm 可以看到翻译的 Guest instruction block，但完整 Linux boot 会快速生成巨大日志。先缩小复现、使用 -S 和 breakpoint，或只在目标阶段打开日志。把几 GiB in_asm 当作理解系统的方法，很像为了找一根针而给整个草垛做逐原子 CT，技术上努力，方向上稍微有点可疑。

需要可重放的 TCG 实验时，QEMU 还有 instruction counting 与 record/replay 机制，但它们会约束设备、时钟和加速器。-icount 的虚拟时间不等于真实 wall-clock 性能；不要把确定性工具产生的时间数字拿去做 VM 性能榜。

更深入的动态分析可以使用 TCG plugin，按 instruction、basic block 或 memory access 订阅事件。plugin 能观察非常细的执行，却不应被理解成可以随意修改 Guest state 的通用 hook。先用 QMP、GDB 和现成 trace event，把 plugin 留给确实需要指令级统计的问题。

时钟、SMP 和”偶尔失败”#

VM 里至少同时存在几种时间：Host wall clock、QEMU virtual clock、Guest wall clock、Guest monotonic clock，以及设备 timer。暂停 VM、Host 休眠、过载或迁移都会让它们以不同方式变化。

-smp 也不仅是一个数量：

Terminal window

1
-smp cpus=4,sockets=1,cores=2,threads=2

Guest 会看见拓扑，调度器与软件许可可能据此作决定。若只写 -smp 4，QEMU 会根据 machine 默认规则补齐 topology；需要可复现实验时应把真正相关的拓扑写全。

并发 bug 在 TCG 单线程、TCG 多线程和 KVM 下可能表现不同。TCG 没复现不等于真实硬件没有 bug，KVM 复现也不等于 QEMU 设备模型必然有错。先确定问题落在 Guest 软件、虚拟 CPU、设备 contract 还是 Host backend，再更换加速器做交叉验证。

一套可重复的内核实验命令#

我现在不会从一条不断追加参数的历史命令开始，而是明确命名每一层：

Terminal window展开收起

1
qemu-system-x86_64 \
2
  -name pocket-kernel \
3
  -machine pc-q35-10.2,accel=tcg \
4
  -cpu max \
5
  -m 256M \
6
  -smp cpus=1,sockets=1,cores=1,threads=1 \
7
  -nodefaults \
8
  -no-reboot \
9
  -display none \
10
  -chardev stdio,id=serial0 \
11
  -device isa-serial,chardev=serial0 \
12
  -monitor none \
13
  -qmp unix:/tmp/pocket-kernel.qmp,server=on,wait=off \
14
  -chardev socket,path=/tmp/pocket-kernel.gdb,server=on,wait=off,id=gdb0 \
15
  -gdb chardev:gdb0 \
16
  -kernel arch/x86/boot/bzImage \
17
  -initrd initramfs.cpio \
18
  -append "console=ttyS0 rdinit=/init panic=-1 nokaslr"

展开收起

-nodefaults 移除了常见默认外设，所以我显式创建 isa-serial，再通过 ID 为 serial0 的 chardev 接到 stdio。最小化的目标是让依赖可见，不是参加参数最短比赛。

用于网络和持久 rootfs 时再加：

Terminal window

1
-blockdev driver=file,node-name=root-file,filename=root.qcow2 \
2
-blockdev driver=qcow2,node-name=root,read-only=off,file=root-file \
3
-device virtio-blk-pci,drive=root \
4
-netdev user,id=net0,hostfwd=tcp:127.0.0.1:2222-:22 \
5
-device virtio-net-pci,netdev=net0

对应内核至少要检查：

1
CONFIG_SERIAL_8250=y
2
CONFIG_SERIAL_8250_CONSOLE=y
3
CONFIG_VIRTIO=y
4
CONFIG_VIRTIO_PCI=y
5
CONFIG_VIRTIO_BLK=y
6
CONFIG_VIRTIO_NET=y

具体符号仍以目标 Linux 版本和 machine 为准。root 设备还要在 -append 中给出正确 root=/dev/vda...、filesystem driver 和等待策略。看到 VFS: Unable to mount root fs 时，我会先核对 4 件事：Guest 设备类型、transport driver、block/filesystem driver 是否内建、root path 是否与实际分区一致。

常见失败怎样沿层次定位？#

QEMU 启动前就报 property 或 bus 错误#

这是 Host 侧 machine graph 没建起来。检查 -device TYPE,help、ID 拼写、bus 名、machine 是否提供该 bus，以及当前 QEMU build 是否包含设备。Guest kernel 尚未执行，不要先改 Kconfig。

屏幕全黑或终端没有日志#

分别检查显示与 console：

-display none 是否把唯一图形输出关闭。
-serial stdio 或 -nographic 是否连接正确 UART。
kernel command line 是否使用 ttyS0、ttyAMA0 等正确设备。
UART driver 和 console support 是否内建。
使用 -S 时是否忘了从 GDB 或 QMP cont。

`No bootable device`#

固件没有找到可启动介质。检查镜像内容、boot signature/EFI executable、bootindex、磁盘 interface 与 firmware 能否驱动它。一个包含 ext4 的文件不自动等于含有 bootloader 的 boot disk。

内核看不见磁盘或网卡#

先用 QMP/HMP 确认 device 真的存在并连接 backend，再看 Guest dmesg、PCI/Device Tree 枚举和驱动配置。VirtIO PCI 与 VirtIO MMIO 需要不同 transport；设备存在但没有 driver 与设备根本没创建，会得到相似的”看不见”，修复层却完全不同。

`Could not access KVM kernel module`#

检查 /dev/kvm、Host CPU virtualization、内核模块、权限和容器 device passthrough。需要兼容 fallback 时可写：

Terminal window

1
-accel kvm:tcg

但性能实验不应静默 fallback。用 QMP query-kvm 记录 enabled，否则以为自己测了 KVM，实际跑了一夜 TCG，也算一种很昂贵的类型错误。

SSH 端口转发连不上#

检查 Host port 是否被占用、hostfwd 的绑定地址、Guest sshd 是否监听、Guest firewall 和地址配置。QEMU user networking 默认不接受任意外部入站，端口转发是明确开的洞。

镜像提示 format probing 警告#

显式写 format=raw 或 format=qcow2。格式自动探测不仅让行为含糊，对 raw 镜像还可能因安全限制阻止对第 0 block 的写入。命令行里知道格式，就把它写出来。

安全边界不能靠”它只是虚拟机”#

我会保留这些默认纪律：

用普通用户运行 QEMU，不给整个进程 root。
不可信 Guest 只配置需要的设备与 backend。
QMP、HMP、GDB 和 migration socket 使用 Unix socket 或绑定 loopback，并限制权限。
不随意添加 Host 目录共享、USB passthrough、VFIO、/dev/mem 或可写物理块设备。
user networking 的 hostfwd 显式绑定 127.0.0.1。
对 base image 只读，实验写入 overlay。
semihosting 只给可信裸机代码使用，因为它可以绕过 Guest/Host 隔离访问 Host 资源。
记录 QEMU version、machine version、CPU model、firmware、镜像 hash 和完整参数。

VFIO passthrough 能减少设备模拟并接近原生性能，但它把 IOMMU group、DMA 隔离、reset semantics 和 Host driver ownership 带进系统。它不是”再加一个 -device”级别的学习步骤。我会先把纯模拟设备与 VirtIO 路径弄清，再碰 passthrough。

我最终保留的心智模型#

现在我把 QEMU 看成 5 张互相连接的图：

执行图：Guest ISA 经 TCG 或 KVM 前进。
machine 图：CPU、RAM、bus、中断控制器和设备占据确定位置。
I/O 图：Guest device 经 block、network、character backend 连接 Host。
启动图：reset 后进入 firmware、bootloader 或 direct kernel boot。
控制图：人用 HMP，程序用 QMP，调试器用 gdbstub，Guest Agent 报告 OS 内部状态。

512 字节启动扇区只用了 1 个 vCPU、1 个 UART、1 个软盘和 1 个测试退出设备，却已经证明了这 5 张图如何接起来。随后 992 字节 AArch64 ELF 又拿掉整台 machine，只留下指令翻译与 syscall translation。最后，virt 的 1 MiB DTB 把 ARM machine 的 RAM、PL011、GIC、PCI 和 32 个 VirtIO MMIO slot 全部摊在文本里。QEMU 没有变简单，但黑盒变成了几张可以逐边检查的图。

接下来我最想做的是把上一篇 pocket_sensor 从一个靠 insmod 自说自话的模块，改成真正的 platform driver：在 ARM virt 上增加一个小型 MMIO 设备模型，让 QEMU 生成对应 Device Tree 节点，再观察 Linux 从 compatible 匹配到 probe()、中断与 remove()。到那一步，Kconfig、Kbuild、Device Tree、driver core 和 QEMU device model 会在同一条可执行链上相遇。

很好。我终于不再把 -nographic 当作启动虚拟机的咒语了。它只是把一根虚拟串口线接到了我的终端，剩下 455 个设备还在后面安静地等着制造新问题。

参考资料#

我追了一遍 Kbuild: 从一行 obj-m 到可以加载的 Linux 内核模块

Fri, 04 Sep 2026 12:00:00 GMT

上一篇文章停在一行很小的 Makefile 上：

1
obj-$(CONFIG_POCKET_SENSOR) += pocket_sensor.o

Kconfig 已经算出 CONFIG_POCKET_SENSOR=m，但这一行怎么变成一个能让内核执行的 .ko？我从 Linux v6.18 拉出这根线，写了一个双文件模块，编译它，拆开中间产物，再把它塞进 QEMU 里的 Linux 6.18。最后我真的看到了 module_init() 和 module_exit() 各执行一次。很好，配电柜之后，我们终于开始追电线了。

Kconfig

CONFIG_POCKET_SENSOR=m

auto.conf 与 obj-m

选择模块路径

scripts/Makefile.build

编译 core.o 和 stats.o

ld -r

合成 pocket_sensor.o

modpost 与 modfinal

生成 pocket_sensor.ko

finit_module()

执行 pocket_sensor_init()

Kconfig

CONFIG_POCKET_SENSOR=m

auto.conf 与 obj-m

选择模块路径

scripts/Makefile.build

编译 core.o 和 stats.o

ld -r

合成 pocket_sensor.o

modpost 与 modfinal

生成 pocket_sensor.ko

finit_module()

执行 pocket_sensor_init()

本文只讨论 Linux Kbuild。U-Boot 也继承了 Kbuild 的许多写法，但它没有 Linux 这条可加载模块链，最终镜像路径也不同。这里不把两种系统勉强揉成一种。

先把实验钉在具体版本上#

我的实验环境如下：

项目	实验值
Linux 源码	`v6.18`
架构	`x86_64`
GNU Make	`4.4.1`
GCC	`15.2.0`
GNU Binutils	`2.46`
kmod	`31`
QEMU	`10.2.4`
BusyBox	`1.37.0`

内核和外部模块统一使用 GCC 15.2.0 与 GNU Binutils 2.46。正式构建也应复用目标内核的工具链、配置和构建目录，因为 Linux 不向外部模块提供稳定的内核内 ABI。

我用下面的源码固定分析基准：

Terminal window

1
git clone --depth 1 --branch v6.18 \
2
  https://github.com/torvalds/linux.git linux-6.18

Linux 6.18 是这里的机制快照。后续版本可能移动规则、拆分生成文件或改变命令行，所以文中的源码链接都锁在 v6.18 标签。

先做出一个真的 `.ko`#

时机	可观察行为
加载	读取 `label` 和 `samples` 两个模块参数
运行	`stats.c` 分配并初始化一小段样本数组
卸载	释放数组并打印样本数

目录只有 5 个输入文件：

1
pocket-sensor/
2
├── Kbuild
3
├── Makefile
4
├── core.c
5
├── stats.c
6
└── pocket_sensor.h

core.c 负责模块生命周期和参数：

GPL-2.0展开收起

1
#include <linux/init.h>
2
#include <linux/module.h>
3

4
#include "pocket_sensor.h"
5

6
static char *label = "desk";
7
module_param(label, charp, 0444);
8
MODULE_PARM_DESC(label, "Sensor label");
9

10
static unsigned int samples = 4;
11
module_param(samples, uint, 0444);
12
MODULE_PARM_DESC(samples, "Number of synthetic samples");
13

14
static int __init pocket_sensor_init(void)
15
{
16
  int ret;
17

18
  ret = pocket_stats_start(samples);
19
  if (ret)
20
    return ret;
21

22
  pr_info("pocket_sensor: loaded label=%s samples=%u\n",
23
    label, samples);
24
  return 0;
25
}
26

27
static void __exit pocket_sensor_exit(void)
28
{
29
  pr_info("pocket_sensor: unloaded samples=%u\n",
30
    pocket_stats_stop());
31
}
32

33
module_init(pocket_sensor_init);
34
module_exit(pocket_sensor_exit);
35

36
MODULE_AUTHOR("bfmhno3");
37
MODULE_DESCRIPTION("Small Kbuild experiment");
38
MODULE_LICENSE("GPL");

展开收起

stats.c 提供第二个编译单元：

GPL-2.0展开收起

1
#include <linux/errno.h>
2
#include <linux/slab.h>
3
#include <linux/types.h>
4

5
#include "pocket_sensor.h"
6

7
static u32 *values;
8
static unsigned int value_count;
9

10
int pocket_stats_start(unsigned int count)
11
{
12
  unsigned int i;
13

14
  if (!count || count > 4096)
15
    return -EINVAL;
16

17
  values = kcalloc(count, sizeof(*values), GFP_KERNEL);
18
  if (!values)
19
    return -ENOMEM;
20

21
  for (i = 0; i < count; i++)
22
    values[i] = i;
23
  value_count = count;
24
  return 0;
25
}
26

27
unsigned int pocket_stats_stop(void)
28
{
29
  unsigned int count = value_count;
30

31
  kfree(values);
32
  values = NULL;
33
  value_count = 0;
34
  return count;
35
}

展开收起

头文件只是两个编译单元之间的接口：

GPL-2.0

1
#ifndef POCKET_SENSOR_H
2
#define POCKET_SENSOR_H
3

4
int pocket_stats_start(unsigned int count);
5
unsigned int pocket_stats_stop(void);
6

7
#endif

真正交给 Kbuild 的文件只有两行：

1
obj-m += pocket_sensor.o
2
pocket_sensor-y := core.o stats.o

第一行声明最终模块，第二行声明组成这个模块的对象。pocket_sensor-y 里的 y 不是说整个模块内建；它表示这些对象无条件组成 pocket_sensor.o。最终走内建还是模块路径，仍由外层的 obj-y 或 obj-m 决定。

为了让目录里直接执行 make，我另外放一个很薄的包装 Makefile：

1
KDIR ?= /path/to/linux-6.18-build
2

3
.PHONY: all clean
4
all:
5
  $(MAKE) -C $(KDIR) M=$(CURDIR) modules
6

7
clean:
8
  $(MAKE) -C $(KDIR) M=$(CURDIR) clean

KDIR 指向已经配置并完成构建的 Linux 6.18 输出目录。只运行 modules_prepare 可以补齐很多生成头和脚本，但在 CONFIG_MODVERSIONS=y 时，它不会生成 Module.symvers。我这次完整构建了实验内核和 modules 目标，避免把缺失符号版本伪装成模块问题。

第一次构建输出是：

1
$ make
2
  CC [M]  core.o
3
  CC [M]  stats.o
4
  LD [M]  pocket_sensor.o
5
  MODPOST Module.symvers
6
  CC [M]  pocket_sensor.mod.o
7
  CC [M]  .module-common.o
8
  LD [M]  pocket_sensor.ko

干净构建耗时 1.78 秒，立刻再构建一次耗时 0.89 秒，第二次没有执行任何 CC、LD 或 MODPOST。这里的绝对时间包含启动多层 Make 的固定成本，不适合拿去跑编译器排行榜；有趣的是工作量从 7 个构建动作降到了 0。

5 个输入文件旁边出现了 19 个生成文件：

1
core.o
2
stats.o
3
pocket_sensor.mod
4
pocket_sensor.o
5
modules.order
6
Module.symvers
7
pocket_sensor.mod.c
8
pocket_sensor.mod.o
9
.module-common.o
10
pocket_sensor.ko
11
.core.o.cmd
12
.stats.o.cmd
13
.pocket_sensor.mod.cmd
14
.pocket_sensor.o.cmd
15
.pocket_sensor.mod.o.cmd
16
.pocket_sensor.ko.cmd

展开收起

此外还有为 modules.order、Module.symvers 和 .module-common.o 保存命令的 3 个隐藏 .cmd 文件。连同上面的 16 项，总数是 19。Kbuild 很像一条留下完整货运单的装配线：.ko 是箱子，旁边这些小文件告诉它箱子为什么需要重新装。

成品大小为 6944 字节：

1
core.o               4064 bytes
2
stats.o              1608 bytes
3
pocket_sensor.o      5136 bytes
4
pocket_sensor.mod.o  2448 bytes
5
pocket_sensor.ko     6944 bytes

我还编译了一个只有单个 .c 的最小模块。它生成 4552 字节的 .ko 和 15 个派生文件；双文件实验生成 19 个派生文件。两个模块行为不同，所以 2392 字节的体积差不能全算作”多文件税”。真正由复合模块新增的关键动作，是把两个局部 .o 用 ld -r 合成最终的 pocket_sensor.o。

`make -C ... M=... modules` 为什么像走了两遍？#

命令是：

Terminal window

1
make -C "$KDIR" M="$PWD" modules

部分	作用
`-C "$KDIR"`	进入目标内核构建目录；这里必须有 `.config`、生成头、构建工具和 `Module.symvers`
`M="$PWD"`	声明外部模块，并给出源码目录的绝对路径
`modules`	选择模块构建目标；它也是外部模块的默认目标
外层 Makefile	把调用送进内核 Kbuild，不自行拼接内核编译参数

如果把包装逻辑和 Kbuild 声明写在同一个 Makefile，传统写法会检查 KERNELRELEASE：

1
ifneq ($(KERNELRELEASE),)
2
obj-m += pocket_sensor.o
3
pocket_sensor-y := core.o stats.o
4
else
5
KDIR ?= /path/to/linux-6.18-build
6
all:
7
  $(MAKE) -C $(KDIR) M=$(CURDIR) modules
8
endif

第一次读取时，普通 Make 看见 all 并调用内核。第二次进入 Kbuild 后，KERNELRELEASE 已经存在，于是同一文件只暴露 obj-m。我选择独立的 Kbuild 文件后，不再需要这个分支；Kbuild 会优先读取 Kbuild，找不到才读取 Makefile。

内核 Kbuild外层 Makefile用户内核 Kbuild外层 Makefile用户makemake -C KDIR M=CURDIR modules设置 KERNELRELEASE读取 Kbuild 或 Makefile 的内核部分生成 pocket_sensor.ko

Linux 6.13 以后还支持 -f 入口，它不要求先切换工作目录：

Terminal window

1
make -f "$KDIR/Makefile" M="$PWD" modules

两种入口最终进入同一套规则。这里的”两遍”不是 GNU Make 神秘地重复编译，而是包装层和内核构建层各读一次自己负责的描述。

`src`、`obj`、`srctree`、`objtree`#

变量	指向
`srctree`	内核源码树根目录
`objtree`	内核输出树根目录；非分离构建时通常等于 `srctree`
`src`	当前 Kbuild 目录的源码路径
`obj`	当前 Kbuild 目录的输出路径或处理位置

构建内核时，O=/path/to/out 选择 objtree。它不等于”把外部模块输出放到这里”。Linux 6.18 为外部模块单独提供 MO=/path/to/module-out：

Terminal window

1
make -C "$KDIR" M="$PWD" MO="$PWD/out" modules

所以我会把边界记成：O= 管内核输出树，M= 指外部模块源码，MO= 可选地管外部模块输出。3 个路径混在一起时，很多看似缺头文件的问题其实只是拿错了构建目录。

一行 `obj-m` 怎样进入 `scripts/Makefile.build`？#

上一篇文章已经追到这个入口：

1
build := -f $(srctree)/scripts/Makefile.build obj

内核随后用近似下面的子 Make 调用处理一个目录：

Terminal window

1
make -f scripts/Makefile.build obj=<current-directory>

Linux 6.18 的 scripts/Makefile.build 先清空 obj-y、obj-m、flags 等局部变量，再按顺序读入配置和规则：

scripts/Makefile.build

include/config/auto.conf

scripts/Kbuild.include

scripts/Makefile.compiler

当前目录 Kbuild 或 Makefile

scripts/Makefile.lib

展开 obj-y、obj-m 和复合对象

scripts/Makefile.build

include/config/auto.conf

scripts/Kbuild.include

scripts/Makefile.compiler

当前目录 Kbuild 或 Makefile

scripts/Makefile.lib

展开 obj-y、obj-m 和复合对象

这解释了为什么一个目录中的 Kbuild 可以非常短。公共文件已经定义了如何编译 .c、怎样保存命令、如何归档 built-in.a、怎样生成 modules.order。目录文件只声明输入图，不重复写编译器菜谱。

对这两行输入：

1
obj-m += pocket_sensor.o
2
pocket_sensor-y := core.o stats.o

Makefile.build 算出几组直接影响实验的集合：

1
obj-m       = pocket_sensor.o
2
multi-obj-m = pocket_sensor.o
3
real-obj-m  = core.o stats.o

multi-obj-m 是需要部分链接的复合模块。real-obj-m 是真正从源码生成的叶子对象。scripts/Makefile.lib 再通过 part-of-module 给叶子编译追加 -DMODULE、KBUILD_MODNAME 等 flags。我的 V=1 输出中，core.c 的命令确实带有：

1
-DMODULE
2
-DKBUILD_BASENAME='"core"'
3
-DKBUILD_MODNAME='"pocket_sensor"'

Kbuild 先生成一个内容只有两行的响应文件 pocket_sensor.mod：

1
./core.o
2
./stats.o

然后执行实质上的：

Terminal window

1
ld -r -o pocket_sensor.o @pocket_sensor.mod

-r 产生仍可重定位的合并对象，不把它链接成用户空间可执行文件。此时 core.o 对 pocket_stats_start() 的未解析引用由同一次部分链接中的 stats.o 满足。这个阶段像把两个零件焊成一个仍带接口的总成，内核符号的插头还留在外面，稍后加载器再接。

obj-y 和 obj-m 也可能错误地同时列出同一个对象。Linux 6.18 明确执行：

1
obj-m := $(filter-out $(obj-y),$(obj-m))

也就是内建版本优先，模块副本被移除。Kbuild 不会为同一个目标同时制造一份内建对象和一份 .ko，然后让我们猜哪份算数。

完整的模块前半段现在变成：

core.c

core.o

stats.c

stats.o

ld -r

pocket_sensor.o

modpost

core.c

core.o

stats.c

stats.o

ld -r

pocket_sensor.o

modpost

`.cmd` 才是增量构建的记忆#

判断	Kbuild 使用的依据
编译命令是否改变	`.cmd` 中保存的上一次完整命令
输入是否改变	源文件、头文件和被引用的 `CONFIG_*` 标记依赖

core.o 构建后，.core.o.cmd 开头保存完整命令：

1
savedcmd_core.o := gcc ... -DMODULE ... -c -o core.o core.c
2
source_core.o := core.c

后面是一长串真实依赖。例如 core.c 包含的 linux/module.h 使用了模块开关，因此文件中出现：

1
$(wildcard include/config/MODULES)
2
$(wildcard include/config/MODULE_UNLOAD)

规则链是：

否

是

if_changed_dep

目标、依赖或命令变化？

跳过编译

cmd_and_fixdep

执行 GCC 编译命令

生成临时 .d 依赖文件

scripts/basic/fixdep

写入 .core.o.cmd

删除临时 .d

否

是

if_changed_dep

目标、依赖或命令变化？

跳过编译

cmd_and_fixdep

执行 GCC 编译命令

生成临时 .d 依赖文件

scripts/basic/fixdep

写入 .core.o.cmd

删除临时 .d

if_changed_dep 会在目标缺失、普通依赖更新或保存的命令变化时重建。fixdep 还会扫描依赖文件里出现的 CONFIG_FOO，把它转成 include/config/FOO 标记依赖。它并不完整解析 C；Linux 6.18 的源码注释甚至直说，注释中出现的 CONFIG_FOO 也会被抓到。多编一次可以接受，漏编一次不行。

我实际做了 4 轮增量实验：

操作	重新执行的主要步骤
不改任何文件	无 `CC`、`LD`、`MODPOST`
只改 `core.c` 中的普通注释	`core.o`、复合链接、`modpost`、最终链接
修改编译 flags	`core.o` 和 `stats.o`、复合链接、`modpost`、最终链接
修改两者共同包含的 `pocket_sensor.h`	两个叶子对象及后续链全部更新

配置依赖不需要额外造一个与模块无关的开关。后面的树内迁移直接用 CONFIG_POCKET_SENSOR 和 CONFIG_POCKET_SENSOR_STATS 验证：切换 n/m/y 后，Kbuild 会选择不编译、生成 .ko 或进入 vmlinux。目标内核配置或构建目录改变后，外部模块则应对匹配的新构建树做干净重建，不要复用旧 .o。

Important

.cmd 是派生状态，不是稳定接口。需要诊断时可以读它，不能把项目逻辑建立在它的具体文本格式上。

`modpost` 不是又一个链接器#

第一阶段结束时，我们已经有 pocket_sensor.o、pocket_sensor.mod 和 modules.order。modules.order 在这个实验里只有：

1
pocket_sensor.o

它记录 Kbuild 发现模块的顺序。随后 scripts/Makefile.modpost 调用主机程序 scripts/mod/modpost。modpost 主要做静态审查和元数据生成：

阶段	`modpost` 的工作
符号扫描	扫描导入、导出、`EXPORT_SYMBOL()` 和命名空间关系
符号检查	对照内核 `Module.symvers` 检查未解析符号
版本处理	在启用 `CONFIG_MODVERSIONS` 时处理符号 CRC
静态检查	执行 section mismatch 等检查
代码生成	为每个模块生成 `<module>.mod.c`
符号输出	为当前构建写出 `Module.symvers`

这里有一个很好用的失败实验。我最初只构建了 bzImage，没有构建内核的 modules 目标，于是目标输出树中缺少 Module.symvers。modpost 没有含糊地吐出一个坏 .ko，而是列出：

1
WARNING: .../Module.symvers is missing.
2
ERROR: modpost: "param_ops_uint" [pocket_sensor.ko] undefined!
3
ERROR: modpost: "__kmalloc_noprof" [pocket_sensor.ko] undefined!
4
ERROR: modpost: "kfree" [pocket_sensor.ko] undefined!
5
ERROR: modpost: "_printk" [pocket_sensor.ko] undefined!
6
ERROR: modpost: "param_ops_charp" [pocket_sensor.ko] undefined!

运行内核的 make modules 生成 Module.symvers 后，同一个模块通过。这正是 modpost 的价值：在 QEMU 启动前就指出内核符号账本不完整。

Linux 6.18 为我的模块生成了很短的 pocket_sensor.mod.c：

1
#include <linux/module.h>
2
#include <linux/export-internal.h>
3
#include <linux/compiler.h>
4

5
MODULE_INFO(name, KBUILD_MODNAME);
6

7
__visible struct module __this_module
8
__section(".gnu.linkonce.this_module") = {
9
  .name = KBUILD_MODNAME,
10
  .init = init_module,
11
#ifdef CONFIG_MODULE_UNLOAD
12
  .exit = cleanup_module,
13
#endif
14
  .arch = MODULE_ARCH_INIT,
15
};
16

17
MODULE_INFO(depends, "");

展开收起

这段代码把模块名、入口、退出函数和依赖写成内核加载器认识的结构。它被编译为 pocket_sensor.mod.o。

旧文章常把 vermagic 也指向 <module>.mod.c。Linux 6.18 已经把公共部分放进 scripts/module-common.c，编译为 .module-common.o；其中包含：

1
MODULE_INFO(vermagic, VERMAGIC_STRING);

所以最终输入比常见简图多一个对象：

ld -r

pocket_sensor.o

模块代码

scripts/Makefile.modfinal

pocket_sensor.mod.o

入口、退出与依赖

.module-common.o

vermagic 等公共元数据

scripts/module.lds

pocket_sensor.ko

ld -r

pocket_sensor.o

模块代码

scripts/Makefile.modfinal

pocket_sensor.mod.o

入口、退出与依赖

.module-common.o

vermagic 等公共元数据

scripts/module.lds

pocket_sensor.ko

版本锁定在这里立刻有了价值。机制没变，但元数据从哪一个生成文件进入 .ko 已经变了。

`.ko` 仍然是一个可重定位 ELF#

scripts/Makefile.modfinal 最终执行近似下面的链接：

Terminal window

1
ld -r -T scripts/module.lds \
2
  -o pocket_sensor.ko \
3
  pocket_sensor.o pocket_sensor.mod.o .module-common.o

readelf -h pocket_sensor.ko 给出：

1
Class:   ELF64
2
Data:    little endian
3
Type:    REL (Relocatable file)
4
Machine: Advanced Micro Devices X86-64
5
Entry:   0x0

它没有用户程序那种固定入口地址，也还没有落到最终运行地址。readelf -SW 在 6944 字节中找到了 31 个 section，其中最关键的是：

1
.text
2
.init.text
3
.exit.text
4
.modinfo
5
__param
6
.gnu.linkonce.this_module
7
.rela.text
8
.rela.init.text
9
.rela.exit.text

__init 把初始化函数放进 .init.text，__exit 把退出函数放进 .exit.text。module_param() 产生 __param 数据，MODULE_* 宏向 .modinfo 填字符串，链接器保留 relocation section 等待内核处理。

readelf -Ws 还能看到尚未解析的内核符号：

1
UND param_ops_uint
2
UND __kmalloc_noprof
3
UND kfree
4
UND _printk
5
UND param_ops_charp

这不是链接失败留下的垃圾。模块必须调用当前内核提供的分配器、日志和参数实现，所以 .ko 有意保留这些外部引用。modpost 已用 Module.symvers 检查它们是否合法，内核加载器稍后给它们填入运行地址。

modinfo 则把 .modinfo 翻译成人容易读的结果：

1
filename:    pocket_sensor.ko
2
license:     GPL
3
description: Small Kbuild experiment
4
author:      bfmhno3
5
depends:
6
name:        pocket_sensor
7
vermagic:    6.18.0 mod_unload
8
parm:        label:Sensor label (charp)
9
parm:        samples:Number of synthetic samples (uint)

到这里，.ko 已经不神秘了。它是一个附带模块元数据、参数描述、未解析内核符号和重定位记录的 ELF relocatable object。

我把它真的装进了 Linux 6.18#

我没有向宿主机加载实验模块。宿主机是工作环境，不是祭坛。我构建了一个精简的 x86_64 Linux 6.18、一个 1,422,848 字节的 initramfs，然后用 QEMU 启动：

Terminal window

1
qemu-system-x86_64 \
2
  -machine accel=tcg \
3
  -cpu max \
4
  -m 256M \
5
  -smp 1 \
6
  -nographic \
7
  -no-reboot \
8
  -kernel arch/x86/boot/bzImage \
9
  -initrd initramfs.cpio \
10
  -append "console=ttyS0 rdinit=/init panic=-1"

/init 挂载 /proc 和 /sys，然后执行：

Terminal window

1
insmod /pocket_sensor.ko label=qemu samples=7
2
cat /sys/module/pocket_sensor/parameters/label
3
cat /sys/module/pocket_sensor/parameters/samples
4
rmmod pocket_sensor

串口日志是：

1
=== pocket_sensor experiment ===
2
pocket_sensor: loading out-of-tree module taints kernel.
3
pocket_sensor: loaded label=qemu samples=7
4
label=qemu
5
samples=7
6
pocket_sensor: unloaded samples=7
7
=== experiment complete ===

两个参数真的进入 /sys/module/pocket_sensor/parameters/，stats.c 分配的 7 个槽位在卸载时释放，初始化和退出日志各出现一次。外部模块 taint 也符合预期；它表示内核装入了树外代码，不表示实验失败。

从 `insmod` 到 `module_init()`#

insmod 很薄。现代 kmod 通常打开模块文件并调用 finit_module()；内核也保留接收用户缓冲区的 init_module() syscall。Linux 6.18 的核心路径在 kernel/module/main.c：

insmod pocket_sensor.ko

finit_module()

load_module()

module_sig_check()

签名与策略

ELF、modinfo 与 vermagic 检查

layout_and_allocate()

布局并分配内存

simplify_symbols()

解析内核符号

apply_relocations()

应用重定位

解析模块参数并建立 sysfs

do_init_module()

pocket_sensor_init()

insmod pocket_sensor.ko

finit_module()

load_module()

module_sig_check()

签名与策略

ELF、modinfo 与 vermagic 检查

layout_and_allocate()

布局并分配内存

simplify_symbols()

解析内核符号

apply_relocations()

应用重定位

解析模块参数并建立 sysfs

do_init_module()

pocket_sensor_init()

load_module() 先检查签名，再验证 ELF 和 vermagic，计算各 section 布局并分配模块内存。simplify_symbols() 遍历 SHN_UNDEF 符号，把 _printk、kfree 等名字解析成内核或其他已加载模块中的地址。apply_relocations() 再按架构处理 .rela.*，把地址写进刚分配的代码和数据。

参数解析发生在入口函数之前。因此 label=qemu samples=7 已经写入静态变量，pocket_sensor_init() 一开始就能读。内核还根据 __param 建立 sysfs 属性。最后 do_init_module() 调用 .mod.c 中记录的 init_module，也就是宏展开后的 pocket_sensor_init()。

insmod 只加载指定文件，不主动解决依赖。真实驱动有依赖时通常用 modprobe，让它根据模块索引先加载依赖；但无论用户空间怎么安排文件，最终都进入上面的内核加载路径。

4 类错误分别在说什么？#

模块错误经常只在终端留下一句短话，真正上下文在内核日志。我的排查顺序是先看 dmesg，再把错误放回加载链。

用户空间错误	加载阶段	首要检查
`Invalid module format`	ELF、`vermagic` 或符号版本检查	架构、目标构建目录、内核配置和 `dmesg`
`Unknown symbol`	符号解析	依赖模块、导出符号、命名空间和 `Module.symvers`
`Operation not permitted`	权限或安全策略	`CAP_SYS_MODULE`、`modules_disabled`、LSM 和 lockdown
`Required key not available`	模块签名验证	签名、可信 keyring 和强制签名策略

`Invalid module format`#

它通常对应 ENOEXEC，但原因不只一个。常见情况包括：

.ko 的架构或 ELF 结构不符合当前内核。
vermagic 不匹配。
启用 CONFIG_MODVERSIONS 后，关键符号 CRC 不匹配。
生成 struct module 的构建配置与运行内核不一致。

Linux 6.18 的 check_modinfo() 会比较模块和内核的 magic，并在日志中打印两边字符串。正确修复是用运行内核对应的构建目录和配置重新编译，不是删掉 vermagic 或使用强制加载把检查蒙住。

`Unknown symbol`#

simplify_symbols() 无法为某个 SHN_UNDEF 找到可用的导出符号。可能是依赖模块没有加载、目标内核没导出该符号、命名空间导入缺失，或外部模块调用了不该调用的内部接口。

先用 modinfo 查看依赖，再检查 Module.symvers 和目标内核配置。若 modpost 已经警告 unresolved symbol，不要期待运行时突然心软。

`Operation not permitted`#

加载入口先执行 may_init_module()。Linux 6.18 在调用者缺少 CAP_SYS_MODULE 或 modules_disabled=1 时返回 EPERM；LSM、lockdown 和容器策略也可能拒绝加载。sudo 只能解决普通权限，不会自动推翻 Secure Boot lockdown 或宿主机给容器划下的边界。

`Required key not available` 或 `Key was rejected by service`#

启用强制模块签名后，module_sig_check() 会验证附在模块末尾的 PKCS#7 签名。模块未签名、算法不支持或密钥不在可信 keyring 中时，Linux 6.18 的强制路径返回 EKEYREJECTED，用户空间显示的短句随 errno 翻译和加载路径而异。正确路径是用目标系统信任的密钥签名并部署证书，不是关闭检查。

Warning

强制加载、伪造版本字符串和关闭签名策略会把”构建产物不匹配”变成”内核正在执行未经验证的代码”。它们不是调试捷径，而是在移除护栏。

把 `obj-m` 换成 `obj-y` 会发生什么？#

模块路径现在完整了，但上一篇真正留下的问题还有一半：CONFIG_FOO=y 去了哪里？

对树内目录，父级 Makefile 写：

1
obj-$(CONFIG_POCKET_SENSOR) += pocket_sensor/

当值为 y，scripts/Makefile.build 递归进入目录，并把子目录的内建对象装进：

1
drivers/misc/pocket_sensor/built-in.a

Linux 6.18 使用：

1
ar cDPrST built-in.a ...

其中 T 创建 thin archive。它主要保存成员路径，不复制每个 .o 的完整内容。我的归档由两个成员组成：

1
drivers/misc/pocket_sensor/core.o
2
drivers/misc/pocket_sensor/stats.o

目录层级继续向上汇聚：

core.o + stats.o

pocket_sensor/built-in.a

drivers/misc/built-in.a

drivers/built-in.a

根 built-in.a

vmlinux.a

vmlinux.o

scripts/link-vmlinux.sh

vmlinux

core.o + stats.o

pocket_sensor/built-in.a

drivers/misc/built-in.a

drivers/built-in.a

根 built-in.a

vmlinux.a

vmlinux.o

scripts/link-vmlinux.sh

vmlinux

顶层 Makefile 用 KBUILD_VMLINUX_OBJS 生成 vmlinux.a，scripts/Makefile.vmlinux_o 通过 --whole-archive vmlinux.a 生成 vmlinux.o，scripts/link-vmlinux.sh 再完成架构相关的最终链接。y 状态不会生成或更新 pocket_sensor.ko；若刚从 m 切到 y，输出树里可能仍留着旧 .ko，它只是陈旧产物，make clean 才会移除。

modules.builtin 中仍会记录一个逻辑路径：

1
kernel/drivers/misc/pocket_sensor/pocket_sensor.ko

它告诉 modprobe 这个模块名已经内建，不表示磁盘上真的生成了那份 .ko。我的 System.map 则能找到 pocket_sensor_init、pocket_stats_start 和对应 initcall，证明代码已经进入 vmlinux。

内建时 `module_init()` 变成 initcall#

构建形态	`module_init()` 的结果
可加载模块	提供 `.mod.c` 所引用的 `init_module` 入口
内建代码	映射到 `device_initcall()`，把函数指针放进 initcall section

Linux 按 initcall level 执行；同一 level 内的次序受链接顺序影响。obj-y 的排列因此不只是审美问题。两个驱动若偷偷依赖初始化先后，调换 Makefile 中对象顺序就可能改变启动行为。更好的设计仍是显式表达依赖，而不是拿链接顺序当隐藏 API。

module_exit() 对可卸载模块是 rmmod 路径。内建代码正常运行期间不会被卸载，所以退出函数没有对应的日常生命周期意义；我的 System.map 仍保留了 pocket_sensor_exit，但内核不会把它当作可卸载模块的退出回调来调用。不要因为同一份源码能用 y 和 m 编译，就假设两种生命周期完全对称。

我把外部模块迁回了内核树#

实验目录改为：

1
drivers/misc/pocket_sensor/
2
├── Kconfig
3
├── Makefile
4
├── core.c
5
├── stats.c
6
└── pocket_sensor.h

父级 drivers/misc/Kconfig 加一行：

1
source "drivers/misc/pocket_sensor/Kconfig"

配置文件为：

GPL-2.0-only

1
config POCKET_SENSOR
2
  tristate "Pocket sensor experiment"
3
  help
4
    Build the pocket sensor used to trace the Kbuild pipeline.
5

6
config POCKET_SENSOR_STATS
7
  bool "Pocket sensor statistics"
8
  depends on POCKET_SENSOR
9
  default y
10
  help
11
    Add the synthetic sample storage used by the experiment.

父级 drivers/misc/Makefile 决定是否进入目录：

1
obj-$(CONFIG_POCKET_SENSOR) += pocket_sensor/

子目录 Makefile 决定总成和可选零件：

GPL-2.0-only

1
obj-$(CONFIG_POCKET_SENSOR) += pocket_sensor.o
2
pocket_sensor-y := core.o
3
pocket_sensor-$(CONFIG_POCKET_SENSOR_STATS) += stats.o

当 statistics 关闭时，头文件提供不分配内存的 inline 实现；当它打开时，stats.o 进入复合对象。这样配置和链接图一致，不会让 core.o 留下无人提供的函数。

我在同一个 Linux 6.18 输出树里验证了 3 种状态：

配置	实际构建结果
`CONFIG_POCKET_SENSOR=n`	没有创建 `drivers/misc/pocket_sensor/` 输出目录
`CONFIG_POCKET_SENSOR=m`	编译 `core.o`、`stats.o`，部分链接并生成 `pocket_sensor.ko`
`CONFIG_POCKET_SENSOR=y`	两个对象进入 thin `built-in.a`，随后进入 `vmlinux`

y 状态的增量构建日志把路径完整打印出来：

1
CC      drivers/misc/pocket_sensor/core.o
2
CC      drivers/misc/pocket_sensor/stats.o
3
AR      drivers/misc/pocket_sensor/built-in.a
4
AR      drivers/misc/built-in.a
5
AR      drivers/built-in.a
6
AR      built-in.a
7
AR      vmlinux.a
8
LD      vmlinux.o
9
MODPOST vmlinux.symvers
10
LD      vmlinux.unstripped
11
OBJCOPY vmlinux

这也把两篇文章真正接上了：

Kconfig

CONFIG_POCKET_SENSOR

不进入构建

obj-m

pocket_sensor.o

modpost

pocket_sensor.ko

obj-y

built-in.a

vmlinux.a

vmlinux

Kconfig

CONFIG_POCKET_SENSOR

不进入构建

obj-m

pocket_sensor.o

modpost

pocket_sensor.ko

obj-y

built-in.a

vmlinux.a

vmlinux

外部模块和树内模块的维护边界#

两条路径共享 Kbuild 语法和大量编译规则，但维护契约不同。

维度	外部模块	树内模块
适合场景	快速验证、尚未上游的厂商驱动、独立发布或 DKMS	与内核同步演进、接入子系统测试、准备上游或长期维护产品内核
版本关系	内核内部 API 和 ABI 变化后，可能需要重编或修改源码	接口与调用方可以在同一次内核提交中原子修改
构建要求	构建目录、`.config`、`Module.symvers` 和工具链必须匹配目标内核	由同一内核源码树、配置和 Kbuild 图统一构建
安全与交付	需要单独处理安装、依赖索引、Secure Boot 签名和密钥部署	跟随内核镜像或模块安装流程交付
集成成本	初期低，但升级兼容工作由模块维护者承担	初期要补齐 Kconfig、测试、文档和子系统审查

DKMS 解决的是自动重编与安装流程，不会把不稳定的内核 ABI 变稳定。

树内也不是把目录复制到 drivers/ 就结束。正式驱动还要遵守子系统接口、代码风格、MAINTAINERS、文档与设备绑定规范，并写出准确的 Kconfig 依赖。我的 pocket_sensor 故意没有 platform bus、Device Tree、I2C 或真实寄存器访问；伪造硬件只会让 Kbuild 主线被一堆无意义的驱动样板淹没。

ARM64 工程只多哪一层？#

Kbuild 数据流不因架构改变。交叉构建 ARM64 外部模块时，通常在内核配置、内核构建和模块构建中保持同一组变量：

Terminal window展开收起

1
make O="$KOUT" \
2
  ARCH=arm64 \
3
  CROSS_COMPILE=aarch64-linux-gnu- \
4
  my_board_defconfig
5

6
make O="$KOUT" \
7
  ARCH=arm64 \
8
  CROSS_COMPILE=aarch64-linux-gnu- \
9
  -j"$(nproc)"
10

11
make -C "$KOUT" \
12
  M="$PWD" \
13
  ARCH=arm64 \
14
  CROSS_COMPILE=aarch64-linux-gnu- \
15
  modules

展开收起

新增的是目标架构、交叉工具链和真实板卡的启动链，不是第二套 obj-m -> modpost -> .ko 机制。加载时仍要保证运行内核就是这份配置和符号账本对应的内核。

继续往下追#

这次我从 2 行 Kbuild 得到了一个 6944 字节的 ELF，在 QEMU 中给它传入 2 个参数，观察它分配 7 个样本槽位，再完整卸载。沿途最让我意外的不是链接器，而是那些小账本：.cmd 记住命令和依赖，pocket_sensor.mod 记住复合对象，modules.order 记住模块顺序，Module.symvers 记住内核可见符号，.mod.c 把入口写回 C。

如果继续向下走，下一站应该是真实总线和设备模型：让同一个模块不再凭 insmod 自说自话，而是由 Device Tree 描述硬件，由 platform 或 I2C core 完成匹配，再看 probe、defer 和 remove 如何与 Kbuild 产物相遇。到那时 .ko 已经不是神秘黑盒，只是驱动生命周期被装进 ELF 后的运输形态。

很好。我现在可以停止盯着 obj-m 猜 Make 的心情，开始给那块并不存在的传感器寻找一块真正的板子了。

参考资料#

我拆开了 Kconfig: 从一个选项到 U-Boot 和 Linux 的条件编译

Wed, 02 Sep 2026 12:00:00 GMT

我最近需要自己裁剪并构建 U-Boot 和 Linux Kernel。两个项目都让我先选一个 defconfig，再面对 menuconfig 里几千个选项，最后得到一片 CONFIG_FOO=y。我会用这些命令，却不知道中间发生了什么。于是我取出 Linux 6.18 的 Kconfig 实现，写了一棵只有 7 个符号的配置树，并一路追到 Makefile 和 C 预处理器。30 行 Kconfig 之后，这套系统终于不再像一个蓝色背景的许愿池。

本文以 Linux 6.18 和 U-Boot v2026.07 为准。Linux 6.18 是 2025 年 11 月 30 日发布的 longterm 内核，预计维护到 2028 年 12 月；U-Boot v2026.07 则是写作时适合新项目参考的稳定版本。Kconfig 的核心模型很稳定，但具体符号、默认值和 U-Boot 的兼容生成步骤会随版本变化，所以我会把机制和某个板子的配置内容分开。

先纠正一个名字#

Kconfig 不是完整的构建系统。

我更愿意把整个过程分成 3 层：

Kconfig 描述有哪些配置符号、它们的类型、默认值和约束，并求出一份合法配置。
Kbuild/Makefile 读取配置，决定哪些目录和 .o 文件参加编译，以及传递哪些编译选项。
编译器和链接器 根据宏继续裁剪 C 代码，最后生成内核或 U-Boot 镜像。

Kconfig 像配电柜：它决定哪些回路通电，但并不亲自制造电器。make menuconfig 只是配电柜的一块操作面板，不是配电柜本身，更不是发电厂。

Kconfig 文件

conf/mconf 等前端

defconfig 或旧 .config

完整 .config

include/config/auto.conf

include/generated/autoconf.h

Kbuild/Makefile 选择目标文件

C 预处理器选择代码

编译与链接

Kconfig 文件

conf/mconf 等前端

defconfig 或旧 .config

完整 .config

include/config/auto.conf

include/generated/autoconf.h

Kbuild/Makefile 选择目标文件

C 预处理器选择代码

编译与链接

这张图是本文最重要的地图。后面的每个文件都只是在这条数据流上承担一个角色。

我先造一个口袋大小的配置系统#

我使用 Linux 6.18 自带的 scripts/kconfig/，因为 U-Boot 的 Kconfig 语言源自 Linux，而 Linux 版本还保留了 m 这个最容易暴露三值逻辑的状态。先取得源码：

Terminal window

1
git clone --depth 1 --branch v6.18 \
2
  https://github.com/torvalds/linux.git linux-6.18
3
cd linux-6.18
4
mkdir -p lab/drivers

Kconfig 前端需要主机上的 C 编译器、GNU Make、Flex 和 Bison。menuconfig 还需要 ncurses 开发文件。这里只运行非交互的 alldefconfig，所以先不碰 ncurses。

根配置 lab/Kconfig 如下：

1
mainmenu "Pocket Board Configuration"
2

3
config MODULES
4
  bool "Enable loadable modules"
5
  modules
6
  default y
7

8
menu "Board"
9

10
config SOC_ALPHA
11
  bool "Alpha SoC"
12
  default y
13

14
config HAS_I2C
15
  bool
16
  default y if SOC_ALPHA
17

18
config LOG_LEVEL
19
  int "Log level"
20
  range 0 4
21
  default 2
22

23
endmenu
24

25
source "lab/drivers/Kconfig"

展开收起

驱动配置放在 lab/drivers/Kconfig：

1
menu "Drivers"
2

3
config SENSOR
4
  tristate "Temperature sensor"
5
  depends on HAS_I2C
6
  default m
7

8
config SENSOR_DEBUG
9
  bool "Verbose sensor debugging"
10
  depends on SENSOR
11

12
config APP
13
  bool "Sensor application"
14
  select SENSOR_CORE
15

16
config SENSOR_CORE
17
  bool
18
  depends on HAS_I2C
19

20
endmenu

展开收起

现在让 Linux 的构建入口编译 Kconfig 前端，并用所有符号的默认值求解一次：

Terminal window

1
make O="$PWD/out" KBUILD_KCONFIG=lab/Kconfig alldefconfig

O= 把生成物放进 out/，KBUILD_KCONFIG 把入口从内核根目录的 Kconfig 换成我的实验文件。第一次运行还会把 conf.c、解析器和词法分析器编译成主机程序 out/scripts/kconfig/conf。换句话说，配置 Linux 之前，Linux 先在我的电脑上编译了一个小型配置求解器（构建系统也要先构建自己，乌龟下面还是乌龟）。

我得到的 out/.config 核心部分是：

1
CONFIG_MODULES=y
2
CONFIG_SOC_ALPHA=y
3
CONFIG_HAS_I2C=y
4
CONFIG_LOG_LEVEL=2
5
CONFIG_SENSOR=m
6
# CONFIG_SENSOR_DEBUG is not set
7
# CONFIG_APP is not set

这里已经发生了几件值得追踪的事：

我没有直接设置 HAS_I2C，它从 SOC_ALPHA=y 的条件默认值得到 y。
SENSOR 的上限允许到 y，默认值把它设成 m。
SENSOR_DEBUG 没有显式 default，所以默认为 n。
APP 同样默认为 n，因此它还没有触发 select。

Kconfig 文件不是按顺序执行的 Shell 脚本。解析器先收集符号与关系，再计算值、可见性和取值上下限。把它当成一个受约束的配置数据库，比把它当成一串赋值语句准确得多。

一个 `config` 到底定义了什么？#

最常见的条目是：

1
config SENSOR
2
  tristate "Temperature sensor"
3
  depends on HAS_I2C
4
  default m
5
  help
6
    Build support for the temperature sensor.

SENSOR 是符号名。写入配置文件时，前端通常给它加上 CONFIG_ 前缀，于是得到 CONFIG_SENSOR。Kconfig 源码中的依赖表达式仍然写 SENSOR，不要写 CONFIG_SENSOR。

一个符号常见的属性包括：

属性	回答的问题
`bool` / `tristate` / `string` / `int` / `hex`	值属于什么类型？
`prompt` 或类型后的字符串	用户能否在界面中看到并修改它？
`default`	用户没有给值时，从哪里开始？
`depends on`	这个符号允许取到多大的值？
`select`	当前符号启用时，强制抬高哪个符号的下限？
`imply`	当前符号启用时，弱建议哪个符号？
`range`	整数或十六进制值允许在哪个区间？
`help`	用户在配置界面请求帮助时看到什么？

类型后的提示文字其实是 prompt 的简写：

1
bool "Alpha SoC"

等价于：

1
bool
2
prompt "Alpha SoC"

这解释了一个常见现象：符号存在，不代表它会出现在 menuconfig。 HAS_I2C 和 SENSOR_CORE 没有 prompt，它们是内部符号。用户不能直接操作它们，只能让 default、select 等关系计算出值。编辑 .config 强塞一个值也不会把内部符号变成公开开关；下一次解析时，Kconfig 仍按它的定义处理。

menu、comment 和 mainmenu 主要组织界面。source 把另一份 Kconfig 文件读入同一棵配置树。它们不会因为排版漂亮就自动让任何 .c 文件参加编译。

`n`、`m`、`y` 不是 3 个字符串#

Linux 的 tristate 使用三值逻辑：

文本	数值	含义
`n`	0	不构建
`m`	1	构建为可加载模块
`y`	2	内建

表达式中的 && 取较小值，|| 取较大值，! 则做 2−x2-x2−x：

1
m && y = m
2
m || n = m
3
!m = m

这不是普通布尔代数中随手多塞了一个字母。它让依赖能够表达一个关键约束：内建代码不能依赖只在运行时才加载的模块。例如 FOO=y 且 BAR=m 时，FOO depends on BAR 会把 FOO 的上限压到 m，因此 FOO 不能保持 y。

modules 属性指定哪一个符号负责开启模块状态。Linux 使用它让大量 tristate 真正拥有 m。U-Boot v2026.07 没有 Linux 那样的可加载内核模块体系，也没有定义全局 MODULES 符号。它的树中仍能看到一些 tristate 声明，但日常板级裁剪应把 U-Boot 配置理解为主要在 n/y 之间选择，不要看到 tristate 就期待生成 .ko。

`depends on` 是上限，不是自动开关#

假设：

1
config SENSOR
2
  tristate "Temperature sensor"
3
  depends on HAS_I2C

当 HAS_I2C=n 时，SENSOR 的最大值是 n，界面也会把它隐藏或禁用。当 HAS_I2C=y 时，Kconfig 只是允许 SENSOR 取 n、m 或 y，并不会替用户启用它。

所以 depends on 的读法不是：

选择 SENSOR 时，顺便打开 HAS_I2C。

而是：

只有 HAS_I2C 足够可用时，SENSOR 才允许达到相应状态。

菜单也会传递依赖：

1
menu "I2C drivers"
2
  depends on HAS_I2C
3

4
config SENSOR_A
5
  tristate "Sensor A"
6

7
config SENSOR_B
8
  tristate "Sensor B"
9

10
endmenu

这里 SENSOR_A 和 SENSOR_B 都继承 HAS_I2C 依赖。if ... endif 也会把表达式附加到内部条目。它们不只是界面折叠工具。

`default` 只在用户没有决定时说话#

Kconfig 允许一个符号出现多个 default：

1
config BUFFER_SIZE
2
  int "Buffer size"
3
  default 4096 if ARCH_64BIT
4
  default 1024

如果多个默认值的条件都成立，源码中第一个可见的默认值生效。但默认值只在用户没有提供值时使用。用户已经通过配置界面或已有 .config 选过 2048，default 4096 不会每次构建都把它夺回来。

这也解释了为什么新增配置通常保持 default n。旧配置升级到新源码时，make olddefconfig 会替新符号采用默认值；如果每个新驱动都 default y，一次版本升级就会把内核悄悄养胖。Linux 文档只为保留旧行为、纯粹打开下级菜单的 gatekeeper，以及少数用户普遍预期的基础设施等情况建议 default y。

`select` 很方便，也很锋利#

实验中的 APP 写成：

1
config APP
2
  bool "Sensor application"
3
  select SENSOR_CORE
4

5
config SENSOR_CORE
6
  bool
7
  depends on HAS_I2C

我又准备了一份故意不合法的输入：

1
# CONFIG_SOC_ALPHA is not set
2
CONFIG_APP=y

此时 HAS_I2C=n。我把它交给同一个 Linux 6.18 conf，得到：

Terminal window

1
WARNING: unmet direct dependencies detected for SENSOR_CORE
2
  Depends on [n]: HAS_I2C [=n]
3
  Selected by [y]:
4
  - APP [=y]

select 强制抬高目标符号的值，不会沿着目标符号的 depends on 继续解决依赖。于是 APP 可以把 SENSOR_CORE 推到 y，同时留下 HAS_I2C=n 这个自相矛盾的组合。

这不是求解器忘了帮忙，而是 select 的定义。Linux 文档明确建议谨慎使用它，最好只选择没有 prompt、也没有依赖的内部符号。若用户应该理解并控制前置条件，使用 depends on；若只是希望另一个功能通常随当前功能开启，但仍允许用户关闭，考虑 imply。

一个无聊但安全的重构通常是把能力和实现拆开：

1
config HAVE_SENSOR_CORE
2
  bool
3

4
config SENSOR_CORE
5
  bool "Sensor core"
6
  depends on HAVE_SENSOR_CORE && HAS_I2C

平台可以 select HAVE_SENSOR_CORE，却不绕过 SENSOR_CORE 自己的运行条件。多写一个内部符号，比得到一份能通过配置但不能链接的组合便宜得多。

`defconfig`、`.config` 到底谁是谁？#

这是我以前最容易混淆的部分。

`Kconfig` 是规则库#

散布在源码树中的 Kconfig 文件定义全部符号和关系。Linux 6.18 的 Git 索引中有 1881 个文件名包含 Kconfig，U-Boot v2026.07 中有 1098 个。单靠一个平铺的配置文件维护这种规模，大概会迅速演化成考古学。

`defconfig` 是最小起点#

Linux 的架构默认配置通常位于：

1
arch/<arch>/configs/<name>_defconfig

U-Boot 的板级默认配置位于：

1
configs/<board>_defconfig

它们通常只保存偏离 Kconfig 默认值的决定，不是完整快照。我实际运行：

Terminal window

1
make O=/tmp/uboot-out sandbox_defconfig

U-Boot v2026.07 的 configs/sandbox_defconfig 中有 392 行已启用的 CONFIG_ 赋值，展开后的 /tmp/uboot-out/.config 有 1125 行已启用赋值，约为 2.87 倍。剩余值来自默认值、架构选择、依赖和反向依赖。

Important

不要把 defconfig 直接复制成 .config 后立刻编译，也不要假设它已经列出每个关闭项。应该通过 make <board>_defconfig 或对应配置目标，让当前源码树重新求解完整配置。

`.config` 是当前构建的完整用户配置#

.config 是某个源码版本、架构和用户选择组合后的工作状态。它比 defconfig 完整，也更容易在版本升级后变旧。

常见的关闭项写作：

1
# CONFIG_SENSOR_DEBUG is not set

这不是普通注释，而是 Kconfig 保存 n 的标准形式。对于 Makefile 消费的 auto.conf 和 C 代码消费的 autoconf.h，关闭符号通常直接缺席。

`savedefconfig` 做反向压缩#

完成配置后：

Terminal window

1
make savedefconfig

Kconfig 会在源码树或输出树中生成名为 defconfig 的最小配置，只保留相对当前默认规则有必要记录的选择。U-Boot 新板级配置的常见工作流是：

Terminal window

1
make my_board_defconfig
2
make menuconfig
3
make savedefconfig
4
cp defconfig configs/my_board_defconfig

提交前应重新从保存的 defconfig 展开一次，确认它确实复现预期配置。默认值会变化，所以 savedefconfig 是相对于当前 Kconfig 规则做的压缩，不是跨所有未来版本的数学最小集。

一次配置命令实际经过什么？#

以 U-Boot 为例：

Terminal window

1
make O=build my_board_defconfig

可以拆成下面几步：

顶层 Makefile 识别 <board>_defconfig 配置目标。
构建主机程序 scripts/kconfig/conf。这里用的是主机编译器 HOSTCC，不是给目标板生成代码的交叉编译器。
conf 从根 Kconfig 开始，递归解析 source 引入的文件，建立符号、菜单和依赖图。
conf 读取 configs/my_board_defconfig 作为输入，补齐默认值并施加约束。
完整结果写入 build/.config。
后续同步生成 Makefile 和 C 代码需要的配置文件。

menuconfig、nconfig、xconfig 和 gconfig 共享同一套解析与求值核心，只是前端不同：

目标	交互方式
`config`	逐行询问
`menuconfig`	ncurses 菜单
`nconfig`	另一套 ncurses 界面
`xconfig`	Qt 图形界面
`oldconfig`	读取旧配置，并逐个询问新符号
`olddefconfig`	读取旧配置，新符号直接采用默认值
`alldefconfig`	从所有默认值生成新配置
`allnoconfig`	尽量全部设为 `n`，仍受强制关系约束
`savedefconfig`	把当前配置压缩成最小 defconfig
`listnewconfig`	列出旧配置中没有的新符号

menuconfig 并不拥有特殊的求值能力。它只是让人类更容易编辑同一张配置图。自动化构建通常更偏爱 olddefconfig，因为 CI 不太擅长在蓝色菜单里按空格键（至少目前如此）。

配置怎样进入 Makefile？#

同步配置后，Linux 和 U-Boot 都会生成：

1
include/config/auto.conf

内容类似：

1
CONFIG_HAS_I2C=y
2
CONFIG_LOG_LEVEL=3
3
CONFIG_SENSOR=y

顶层构建系统把它当作 Makefile 片段包含进来。子目录 Makefile 就可以写：

1
obj-$(CONFIG_SENSOR) += sensor.o

展开过程非常直接：

CONFIG_SENSOR=y 得到 obj-y += sensor.o，对象内建。
CONFIG_SENSOR=m 得到 obj-m += sensor.o，Linux 把对象送入模块构建路径。
CONFIG_SENSOR 未定义时得到 obj- += sensor.o，正常的 obj-y / obj-m 收集逻辑不会选择它。

目录也能用同样方式裁剪：

1
obj-$(CONFIG_HAS_I2C) += i2c/

所以关闭一个驱动最彻底的效果不是给整份 C 文件套上 #if 0，而是让它根本不进入编译输入。编译器少工作，链接器也不必期待稍后用 section garbage collection 擦屁股。

U-Boot 还要处理 SPL、TPL、VPL 等不同阶段，因此源码中常见：

1
obj-$(CONFIG_$(PHASE_)ADC) += adc-uclass.o

PHASE_ 会让构建阶段选择 CONFIG_ADC、CONFIG_SPL_ADC、CONFIG_TPL_ADC 等对应符号。裁剪 U-Boot 时必须问清楚一个功能属于完整 U-Boot 还是早期阶段；只关 CONFIG_FOO，不代表 CONFIG_SPL_FOO 自动消失。

Linux 中谁消费 `obj-y` 和 `obj-m`？#

上面的表达式还留下了一个问题：谁读取这些变量并把它们变成编译动作？在 Linux 6.18 中，关键入口叫 scripts/Makefile.build。scripts/Kbuild.include 先定义一段缩写：

1
build := -f $(srctree)/scripts/Makefile.build obj

因此顶层 Makefile 中的：

1
$(Q)$(MAKE) $(build)=drivers/i2c

大致等价于再次调用 Make，并指定当前处理的目录：

Terminal window

1
make -f scripts/Makefile.build obj=drivers/i2c

scripts/Makefile.build 是逐目录工作的通用引擎。它先清空 obj-y、obj-m、lib-y、编译 flags 等变量，避免环境中的同名变量混进来；然后读取 include/config/auto.conf、公共 Kbuild 规则、编译器规则、当前目录的 Kbuild 或 Makefile，最后再读取 scripts/Makefile.lib。如果同一目录同时存在 Kbuild 和 Makefile，Kbuild 基础设施优先使用 Kbuild。

顶层 Makefile

make build=目录

scripts/Makefile.build

当前目录 Kbuild 或 Makefile

obj-y 与 obj-m

built-in.a 与 modules.order

顶层 Makefile

make build=目录

scripts/Makefile.build

当前目录 Kbuild 或 Makefile

obj-y 与 obj-m

built-in.a 与 modules.order

读取当前目录规则后，scripts/Makefile.build 会展开复合对象，找出要递归进入的子目录，并把 obj-y 中的子目录映射为对应的 built-in.a。启用模块构建时，它也会沿 obj-m 收集模块目标并生成 modules.order。例如 drivers/i2c/ 不是由顶层 Makefile 硬编码每一个源文件，而是同一套引擎带着不同的 obj 参数逐层下钻。

这就是本文需要抵达的 Kbuild 边界：Kconfig 求出 CONFIG_FOO，auto.conf 把值交给 Make，目录中的 Kbuild 文件把它展开成 obj-y 或 obj-m，scripts/Makefile.build 再把列表变成当前目录的编译和归档目标。至于 .c 如何变成 .o、多文件模块如何合并、modpost 怎样生成模块元数据，以及 built-in.a 最后如何进入 vmlinux，那已经是另一条足够写满一篇文章的数据流。

U-Boot 也继承了 Kbuild 风格，并维护自己的 scripts/Makefile.build，但它的镜像阶段、SPL/TPL/VPL 和兼容配置让后续链接路径与 Linux 不完全相同。这里借 Linux 6.18 看清通用接口，不把两套最终链接过程强行说成一回事。

配置怎样进入 C 代码？#

另一份关键生成物是：

1
include/generated/autoconf.h

我的实验配置生成了：

1
#define CONFIG_LOG_LEVEL 3
2
#define CONFIG_HAS_I2C 1
3
#define CONFIG_APP 1
4
#define CONFIG_MODULES 1
5
#define CONFIG_SOC_ALPHA 1
6
#define CONFIG_SENSOR_CORE 1
7
#define CONFIG_SENSOR 1

C 代码因此可以做更细粒度的选择：

1
#if IS_ENABLED(CONFIG_SENSOR)
2
register_sensor();
3
#endif

Linux 中优先使用项目提供的 IS_ENABLED()、IS_BUILTIN()、IS_MODULE() 等宏，而不是把所有判断都写成裸 #ifdef。原因之一是模块状态：CONFIG_SENSOR=m 通常表现为 CONFIG_SENSOR_MODULE=1，并不等同于 #define CONFIG_SENSOR 1。IS_ENABLED(CONFIG_SENSOR) 能同时覆盖内建和模块两种启用状态。

对于数值和字符串，生成结果保留相应值：

1
#define CONFIG_LOG_LEVEL 3
2
#define CONFIG_LOCALVERSION "-lab"

Warning

不要手改 include/config/auto.conf 或 include/generated/autoconf.h。它们是派生文件，下一次同步就会重写。要改变配置，修改 Kconfig、defconfig 或通过受支持的配置前端修改 .config。

Linux 6.18 已把 syncconfig 标为内部实现细节。正常用户运行 make 或配置目标即可，顶层 Makefile 会在 .config 或 Kconfig 输入变化时更新这些生成物。手工调用 make syncconfig 通常是在绕过正确入口。

U-Boot 为什么看起来还多一层？#

U-Boot 从 v2014.10-rc1 开始用 Kconfig 替代旧的板级配置体系，但 v2026.07 仍保留一些兼容生成步骤。除了与 Linux 相同的 .config、include/config/auto.conf 和 include/generated/autoconf.h，它还可能生成或使用：

1
include/config.h
2
include/autoconf.mk
3
spl/include/autoconf.mk
4
tpl/include/autoconf.mk

板级代码中也仍能看到 include/configs/<board>.h。因此在 U-Boot 中遇到一个 CONFIG_ 或 CFG_ 宏时，不能只在 Kconfig 文件里搜索一次就宣布它不存在。要区分：

Kconfig 管理并生成的 CONFIG_*。
旧板级头文件或其他构建步骤提供的兼容配置。
CFG_* 这类不一定由 Kconfig 管理的编译期常量。
Device Tree 描述的硬件实例与运行时数据。

新配置应优先进入 Kconfig，而不是继续往板级头文件塞宏。旧路径存在是迁移历史，不是新代码需要复制的设计模式。

裁剪一个真实功能时，我现在怎么做？#

假设我要在 U-Boot 中去掉某个以太网驱动，或者在 Linux 中加入某个 I2C 控制器。我会沿着同一条链倒着走。

1. 从符号定义开始#

在 menuconfig 中按 / 搜索符号名，查看：

定义位置。
类型和 prompt。
depends on。
被哪些符号 select。
当前值为何被限制。

如果界面显示：

1
Symbol: FOO [=n]
2
Depends on: BAR [=n] && ARCH_BAZ [=y]

真正阻止 FOO 的是 BAR=n。反复按空格不会改变这个上限。

2. 查 Kbuild/Makefile 消费点#

寻找类似：

1
obj-$(CONFIG_FOO) += foo.o

确认符号控制的是单个对象、整个目录，还是一组公共代码。有时 UI 中一个开关只控制上层框架，具体驱动还有第二个符号。

3. 查 C 代码中的条件#

查看 IS_ENABLED(CONFIG_FOO)、#ifdef CONFIG_FOO 和该符号影响的数据结构。一个符号可能既控制对象是否编译，也控制已编译文件中的某段代码。

4. 检查阶段和架构变体#

U-Boot 要额外查看 CONFIG_SPL_FOO、CONFIG_TPL_FOO 和 CONFIG_VPL_FOO。Linux 则要留意 FOO=y 与 FOO=m 的差别，以及目标架构的 Kconfig 是否为它追加了依赖或默认值。

5. 从干净默认配置重放#

U-Boot：

Terminal window

1
make O=build my_board_defconfig
2
make O=build menuconfig
3
make O=build savedefconfig

Linux：

Terminal window

1
make O=build ARCH=arm64 my_defconfig
2
make O=build ARCH=arm64 menuconfig
3
make O=build ARCH=arm64 savedefconfig

交叉编译时再为实际构建设置正确的 CROSS_COMPILE。O=、ARCH 和 CROSS_COMPILE 应在同一输出目录的配置与构建过程中保持一致，避免拿一份架构 A 的 .config 去喂架构 B。

6. 比较语义差异，不比较整份噪声#

Linux 提供：

Terminal window

1
scripts/diffconfig old.config new.config

它比直接 diff 两份完整 .config 更适合查看符号变化。配置升级时还可以使用：

Terminal window

1
make listnewconfig
2
make olddefconfig

前者告诉我出现了哪些新问题，后者按默认值回答它们。需要审查安全、启动或尺寸影响时，我会先看 listnewconfig，而不是让新符号在日志里无声飘过。

几个容易制造幽灵问题的操作#

直接编辑 `.config` 后不重新求解#

手改 .config 可以用于快速实验，但输入仍受依赖约束。应随后运行 olddefconfig 或受支持的配置目标。否则文件里写着 y，求值结果、生成头和实际构建可能并不支持这个愿望。

把 `select` 当作递归安装依赖#

它不会递归满足目标的依赖。警告已经很直白，修 Kconfig 关系，不要忽视警告。

在 defconfig 中记录所有默认值#

这样得到的是一份巨大快照。默认值改变时，它会把旧决定钉死，也让代码审查看不出板级真正选择了什么。让 savedefconfig 做压缩。

只看 `menuconfig` 中是否可见#

无 prompt 的内部符号不会出现；依赖为 n 的条目也可能隐藏。搜索符号并查看定义，比滚动菜单可靠。

认为 Kconfig 会自动裁剪任何东西#

如果新增了：

1
config FOO
2
  bool "Foo support"

却没有在 Makefile 或 C 代码中消费 CONFIG_FOO，切换它不会改变二进制的一个 bit。Kconfig 只产生决定，构建规则和源码必须执行决定。

我最终保留的心智模型#

我现在把 Kconfig 看成一个有 4 类边的符号图：

depends on 压低取值上限。
select 强制抬高取值下限，但不替目标检查依赖。
imply 提供可被用户拒绝的弱下限。
default 只在用户没有作出决定时给出起点。

defconfig 是送进图中的稀疏输入，.config 是当前版本求解后的工作状态，auto.conf 和 autoconf.h 是分别交给 Make 与 C 的机器接口。随后 obj-$(CONFIG_FOO) 决定文件是否进场，IS_ENABLED(CONFIG_FOO) 决定文件内部哪段代码存活。

这套设计从 1881 份 Linux Kconfig 文件扩展到 U-Boot 的 1098 份，靠的不是某个神奇菜单，而是把配置声明、求值、构建选择和源码条件分开。未来我怀疑更多固件会把硬件描述继续推向 Device Tree，把编译期能力留给 Kconfig；但只要我们仍要为固定板卡在镜像尺寸、启动链和驱动集合之间做取舍，这张符号图就不会消失。

接下来最好的练习不是继续读语法表。选自己板子的一个驱动，从它的 config FOO 追到 obj-$(CONFIG_FOO)，再追到 autoconf.h 和最终镜像。追完一个真实符号，蓝色菜单就只是 UI 了。很好，我终于可以回去裁内核，而不是在 menuconfig 里用空格键进行嵌入式占卜。

参考资料#

从错误码到栈展开: 我如何理解 C++ 异常

Tue, 01 Sep 2026 09:39:28 GMT

“异常不是一种错误返回值。它是一种非局部的控制流。”

我以前写嵌入式 C 时，错误处理基本是一条熟悉的流水线：

1
int result = read_sensor(&value);
2
if (result != 0) {
3
  return result;
4
}

函数返回错误码，调用者检查错误码，然后继续向上传递。一路上每层都写一次 if，最终总有某一层真正处理它 - 或者某一层忘记检查，程序带着错误继续运行。后者当然非常有趣，只是通常不会在你方便调试的时候发生。

C++ 异常做的事情，本质上是把”逐层手动返回错误”改成了”自动向上寻找能够处理错误的位置”。

但这句话里最关键的不是”自动”，而是”能够处理”。

异常最基本的语法#

抛出异常使用 throw：

1
double divide(double a, double b) {
2
  if (b == 0.0) {
3
    throw std::invalid_argument("division by zero");
4
  }
5

6
  return a / b;
7
}

调用者使用 try 和 catch：

1
try {
2
  double result = divide(10.0, 0.0);
3
  std::cout << result << '\n';
4
} catch (const std::invalid_argument& error) {
5
  std::cerr << "参数错误: " << error.what() << '\n';
6
}

几个基本规则：

1
try {
2
  // 可能抛出异常的代码
3
} catch (const SpecificException& error) {
4
  // 处理特定异常
5
} catch (const std::exception& error) {
6
  // 处理其他标准异常
7
} catch (...) {
8
  // 处理所有其他异常
9
}

捕获顺序

catch 按从上到下的顺序匹配，因此具体类型应放在前面，基类放在后面；catch (...) 只能放在最后。

异常一般按值抛出、按 const 引用捕获：

1
throw MyException{"motor stalled"};
2

3
catch (const MyException& error) {
4
  // ...
5
}

不要按值捕获：

1
catch (std::exception error) {  // 不推荐
2
}

这可能发生对象切片，丢失派生异常中的信息。

抛出以后发生了什么？#

假设调用链是：

调用

main()

initialize_system()

load_configuration()

read_file()

调用

main()

initialize_system()

load_configuration()

read_file()

如果 read_file() 抛出异常，它不会像错误码那样正常返回。C++ 会沿调用栈向上寻找匹配的 catch：

开始栈展开

继续传播

找到匹配的处理器

read_file(): 抛出异常

退出 load_configuration()

退出 initialize_system()

main(): catch

开始栈展开

继续传播

找到匹配的处理器

read_file(): 抛出异常

退出 load_configuration()

退出 initialize_system()

main(): catch

这个过程叫做栈展开，stack unwinding。

在展开过程中，已经构造完成的局部对象会被自动销毁：

1
void process() {
2
  std::vector<int> data(1000);
3
  std::lock_guard<std::mutex> lock(mutex);
4

5
  perform_operation();  // 抛出异常
6
}

即使 perform_operation() 抛出异常：

lock 的析构函数仍然执行，互斥锁被释放；
data 的析构函数仍然执行，内存被释放。

RAII 是异常安全的地基

资源放进对象里，清理由析构函数负责，异常只负责改变控制流。不要让 catch 承担本应属于对象生命周期的清理工作。

我跑了一个最小的栈展开实验#

只看规则还是有点抽象，所以我写了一个 34 行的小程序，让 3 个局部对象把构造和析构顺序打印出来，然后在最深处抛出 std::runtime_error：

1
#include <iostream>
2
#include <stdexcept>
3
#include <string_view>
4

5
class Trace {
6
 public:
7
  explicit Trace(std::string_view name) : name_(name) {
8
    std::cout << "construct " << name_ << '\n';
9
  }
10

11
  ~Trace() { std::cout << "destroy " << name_ << '\n'; }
12

13
 private:
14
  std::string_view name_;
15
};
16

17
void read_file() {
18
  Trace trace{"read_file"};
19
  throw std::runtime_error{"disk error"};
20
}
21

22
void load_configuration() {
23
  Trace trace{"load_configuration"};
24
  read_file();
25
}
26

27
int main() {
28
  try {
29
    Trace trace{"main"};
30
    load_configuration();
31
  } catch (const std::runtime_error& error) {
32
    std::cout << "catch runtime_error: " << error.what() << '\n';
33
  }
34
}

展开收起

我用 GCC 15.3 和 -std=c++23 -Wall -Wextra -Wpedantic -Werror 编译，实际输出是：

Terminal window

1
construct main
2
construct load_configuration
3
construct read_file
4
destroy read_file
5
destroy load_configuration
6
destroy main
7
catch runtime_error: disk error

3 个对象按构造的严格逆序销毁，最后才进入 1 个匹配的处理器。异常像按下了调用栈的倒带键：控制流向上走，析构函数沿路把资源收回来。若把同一条 3 层调用链改成 C 风格错误码，每一层都要检查并继续返回；这里中间两层没有错误转发代码，只保留了真正处理错误的边界。

因此，现代 C++ 中通常不应该这样清理资源：

1
Resource* resource = acquire();
2

3
try {
4
  use(resource);
5
} catch (...) {
6
  release(resource);
7
  throw;
8
}
9

10
release(resource);

应该把资源包装成对象：

1
auto resource = make_resource();
2
use(resource);

资源对象的析构函数负责清理。这样正常返回、提前返回和抛出异常都走同一套清理逻辑。

`throw;` 和 `throw e;` 不一样#

捕获后重新抛出当前异常：

1
catch (const std::exception& error) {
2
  log_error(error.what());
3
  throw;
4
}

这里应当使用没有参数的 throw;。它重新抛出当前正在处理的异常，保留原始异常对象及其动态类型。

不要写：

1
catch (const std::exception& error) {
2
  throw error;
3
}

这会用表达式 e 的静态类型 std::exception 初始化一个新的异常对象，因此派生部分会被切掉。

自定义异常#

自定义异常通常继承 std::runtime_error：

1
class ConfigurationError : public std::runtime_error {
2
 public:
3
  using std::runtime_error::runtime_error;
4
};

使用：

1
void load_configuration() {
2
  if (!configuration_exists()) {
3
    throw ConfigurationError{"configuration file is missing"};
4
  }
5
}

捕获：

1
catch (const ConfigurationError& error) {
2
  std::cerr << "配置错误: " << error.what() << '\n';
3
}

不要为每一种小错误都创建一个异常类。异常类型的价值在于让调用者能够采取不同措施，而不仅仅是让类名看起来很完整。

如果两个错误的处理策略完全一样，它们很可能不需要两个异常类型。

到底什么时候应该抛异常？#

我认为最有用的判断标准是：

判断是否应该抛出

当前函数无法完成它承诺的操作，而且调用者不太可能在紧邻的位置用普通分支处理这个失败，此时异常通常是自然的接口。

例如：

1
Configuration load_configuration(const std::filesystem::path& path);

这个函数承诺返回一个有效配置。如果文件损坏，函数无法兑现承诺。此时抛异常很自然：

1
Configuration load_configuration(const std::filesystem::path& path) {
2
  std::ifstream input(path);
3

4
  if (!input) {
5
    throw ConfigurationError{
6
      "cannot open configuration: " + path.string()};
7
  }
8

9
  return parse_configuration(input);
10
}

特别适合异常的情况包括：

构造函数无法建立对象不变量；
初始化过程失败，程序无法继续；
文件、数据库或系统资源出现罕见故障；
某个深层函数无法处理错误，需要跨越多层调用栈；
函数通常成功，而失败属于异常路径。

构造函数尤其适合异常，因为构造函数没有返回值可以装错误码：

1
class SerialPort {
2
 public:
3
  explicit SerialPort(const std::string& device) {
4
    // 约定 open_device 成功时返回空 error_code。
5
    if (const std::error_code error = open_device(device)) {
6
      throw std::system_error{error,
7
                              "cannot open serial port " + device};
8
    }
9
  }
10
};

要么构造出一个有效的 SerialPort，要么构造失败并抛出。不会产生一个”半死不活、需要调用 is_valid() 才敢使用”的对象。

什么情况不应该抛异常？#

异常不适合表达正常、频繁、可预期的业务分支。

例如查找元素：

1
const User* find_user(UserId id);

“没有找到用户”可能完全正常，因此返回空指针或 std::optional 更合适：

1
std::optional<User> find_user(UserId id);

类似情况还有：

队列当前为空；
非阻塞读取暂时没有数据；
用户输入不符合格式；
网络操作需要重试；
传感器偶尔超时，而超时是协议的一部分；
解析器试探某种语法但没有匹配；
高频控制循环中的状态变化。

在 C++23 中，还可以使用 std::expected<T, E>：

1
enum class SensorError {
2
  kTimeout,
3
  kDisconnected,
4
  kChecksumError,
5
};
6

7
std::expected<Reading, SensorError> read_sensor();

调用者显式处理：

1
auto result = read_sensor();
2

3
if (!result) {
4
  if (result.error() == SensorError::kTimeout) {
5
    retry();
6
  }
7
  return;
8
}
9

10
process(*result);

我通常这样区分：

情况	更合适的机制
调用者经常立即处理失败	`optional`、`expected`、错误码
失败罕见，需要跨越多层调用	异常
硬实时路径，需要可预测延迟	错误码或 `expected`
构造函数无法建立有效对象	异常
查询”有没有”	`optional`
可恢复的输入错误或状态不匹配	`expected`、错误码
编程错误或不变量被破坏	断言、契约检查或终止
内存不足、文件系统故障等罕见故障	通常可以使用异常

异常不是”更高级的错误码”。它们适合不同形状的控制流。

应该在哪里捕获？#

这是异常设计中最重要的问题。答案不是”尽量靠近抛出点”，而是：

在能够采取有意义行动的层级捕获。

所谓有意义行动，大致只有几种：

重试操作；
使用备用方案；
请求用户提供新的输入；
把底层错误翻译成当前层的领域错误；
回滚当前事务；
结束当前请求，但保持整个服务继续运行；
在程序最外层记录错误并安全退出。

如果某一层什么都做不了，就不应该为了”看起来处理了错误”而捕获。

这种代码几乎没有价值：

1
try {
2
  load_configuration();
3
} catch (const std::exception& error) {
4
  throw;
5
}

它只是把异常接住，然后原样扔回去。除非这里需要补充上下文，否则让异常自然传播即可。

一个实际的分层例子#

1
std::string read_file(const std::filesystem::path& path);
2
Configuration load_configuration(const std::filesystem::path& path);
3
void initialize_application();
4
int main();

底层文件函数报告它真正知道的事情：

1
std::string read_file(const std::filesystem::path& path) {
2
  std::ifstream input(path);
3

4
  if (!input) {
5
    // 不从 errno 猜测 iostream 失败的原因。
6
    throw std::ios_base::failure{"cannot open " + path.string()};
7
  }
8

9
  return {std::istreambuf_iterator<char>{input},
10
          std::istreambuf_iterator<char>{}};
11
}

配置层知道这个文件对业务意味着什么，因此可以翻译异常：

1
Configuration load_configuration(const std::filesystem::path& path) {
2
  try {
3
    return parse_configuration(read_file(path));
4
  } catch (const std::system_error& error) {
5
    std::throw_with_nested(ConfigurationError{
6
      "failed to load application configuration"});
7
  }
8
}

最外层决定如何向用户呈现：

1
int main() {
2
  try {
3
    auto config = load_configuration("app.conf");
4
    run_application(config);
5
    return EXIT_SUCCESS;
6
  } catch (const ConfigurationError& error) {
7
    std::cerr << "程序无法启动: " << error.what() << '\n';
8
    return EXIT_FAILURE;
9
  } catch (const std::exception& error) {
10
    std::cerr << "未处理的错误: " << error.what() << '\n';
11
    return EXIT_FAILURE;
12
  }
13
}

注意这里的职责分工：

底层发现并描述技术故障；
中间层在必要时翻译语义；
顶层决定程序是重试、降级还是退出。

这有点像消防报警：传感器负责报告烟雾，楼层控制器负责判断区域，最终由消防系统决定疏散。让烟雾传感器自己决定是否撤离整栋楼，职责多少有点超纲。

捕获异常不等于”解决异常”#

这是一个非常常见的困惑。

假设串口打开失败：

1
throw SerialPortError{"COM3 is unavailable"};

捕获以后，你不一定能”修好 COM3”。处理异常可能只是：

尝试另一个串口；
等待一秒后重试；
提示用户检查连接；
禁用相关功能；
记录错误并结束程序。

“处理”指的是把系统带到一个定义良好的状态，而不是必须让原操作成功。

如果当前层做不到这一点，就继续传播。

`try` 块中的代码是不是应该尽量少？#

不是因为 try 天生按行收费，而是因为语义。

在 GCC、Clang 和 MSVC 常见的表驱动异常实现中，未抛出异常的正常路径通常不需要像错误码那样在每一层增加显式分支。代价主要转移到了异常处理元数据、二进制体积和真正抛出时的工作；这是一种常见实现策略，不是 C++ 标准给出的性能保证。

性能模型

没有抛出：常见表驱动实现中的路径成本通常很低，但异常处理元数据和二进制体积并非免费。
真正抛出：运行时需要构造异常对象、查找处理器、展开调用栈并执行析构函数，成本较高且延迟不容易预测。

try 里面有十行还是一百行，并不是主要性能因素。

不过，过大的 try 块会造成另一个问题：

1
try {
2
  load_config();
3
  connect_database();
4
  start_network();
5
  initialize_ui();
6
} catch (const std::exception& error) {
7
  // 到底哪一步失败了？
8
}

这里捕获得太宽，错误上下文容易变模糊。可以让各层的异常信息足够明确，或者按恢复策略划分边界。

所以更准确的原则是：

划定 try 的边界

try 块应当覆盖共享同一种恢复策略的操作，而不是机械地追求行数少。

嵌入式项目为什么经常禁用异常？#

在嵌入式和硬实时系统里，避免异常往往是合理的。原因可能包括：

栈展开延迟难以严格界定；
异常处理会增加代码体积和展开表；
工具链或运行库支持不完整；
项目禁止动态内存分配；
中断服务函数不能允许非局部控制流；
安全规范要求所有控制路径显式可分析；
项目直接使用了 -fno-exceptions。

硬实时路径

平均速度在硬实时控制循环里意义不大，最坏情况延迟才是约束。异常展开的最坏延迟通常难以严格界定，因此这里更适合错误码或 std::expected。

因此我不会提出”现代 C++ 就应该全面使用异常”这种宗教口号。对于嵌入式代码，下面这种组合通常很实际：

中断、驱动、实时循环：错误码或 expected；
上层非实时业务逻辑：根据项目约束决定是否允许异常；
初始化阶段：如果允许异常，异常往往很好用；
跨 C ABI 边界：绝不让异常逃出；
析构函数：通常不得抛出异常。

1
extern "C" int initialize_device() {
2
  try {
3
    initialize_cpp_subsystem();
4
    return 0;
5
  } catch (const std::exception& error) {
6
    log_error(error.what());
7
    return -1;
8
  }
9
}

异常在 C++ 边界内结束，转换为 C 能理解的错误码。

`noexcept` 是一份承诺#

可以声明某个函数不允许异常逃出：

1
void stop_motor() noexcept;

noexcept 是接口承诺

如果异常从 noexcept 函数逃出，程序会调用 std::terminate()，不会继续寻找外层 catch。不要为了性能随手添加 noexcept；它表示函数绝不会通过异常报告失败。

析构函数通常隐式为 noexcept；但如果它的基类或成员析构函数可能抛出，这个结论也会跟着改变。如果异常从非抛出的析构函数逃出，程序会调用 std::terminate()；若此时本来就在栈展开，结果同样是直接终止。

所以析构函数负责释放资源，但不应该通过异常报告清理失败：

1
Connection::~Connection() noexcept {
2
  close_without_throwing();
3
}

异常安全比”有没有 catch”更重要#

一个函数抛出异常后，对象和程序应该处于什么状态？

C++ 通常讨论三种保证：

基本保证：没有资源泄漏，对象仍然有效，但状态可能改变。
强保证：操作失败后，状态和调用前完全一致，类似事务回滚。
不抛保证：函数保证不抛异常。

例如，先构造新状态，成功后再替换旧状态：

1
void Document::set_content(std::string new_content) {
2
  validate(new_content);       // 可能抛出，尚未修改原对象
3
  content_.swap(new_content);  // C++17 起 std::string::swap 为 noexcept
4
}

验证失败时，原内容没有被修改；交换成功后，旧内容由参数 new_content 在离开函数时销毁。这里给出强异常保证，而不是仅仅”接近”它。

相比之下：

1
void update() {
2
  state_.clear();
3
  state_.load();  // 如果这里抛出，旧状态已经丢失
4
}

这里即使外层正确捕获异常，对象也可能已经处于不理想的状态。

所以异常设计的真正难点不是 try/catch 语法，而是：

异常安全的核心问题

操作在任意一步失败时，系统是否仍然保持有效状态？catch 只能决定后续控制流，无法自动修复已经破坏的对象不变量。

我最终会采用的规则#

如果我要从嵌入式 C 迁移到现代 C++，我会先使用下面这套相对保守的规则：

预期内、频繁发生、调用者立即处理的失败，使用 std::expected、std::optional 或错误码。
罕见且无法在本地处理、需要跨越多层调用的失败，可以抛异常。
构造函数无法建立有效对象时，抛异常。
只在能够重试、降级、翻译、回滚或终止当前任务的边界捕获。
不要每层都捕获并重新抛出。
异常按值抛出，按 const 引用捕获。
重新抛出使用 throw;。
用 RAII 管理资源，不要依赖 catch 手动释放。
析构函数、C 接口和实时路径不允许异常逃出。
不用异常表示普通分支，也不用错误码掩盖真正无法继续的故障。
不担心 try 块里有几行代码；担心的是异常是否频繁发生，以及恢复边界是否清晰。

最简洁的判断方式可能是：

是

否

能

不能

是

否

失败是否是正常结果?

使用 optional / expected / 错误码

当前函数能处理吗?

本地处理

是否需要跨越多层调用栈?

抛出异常

优先考虑 expected

是

否

能

不能

是

否

失败是否是正常结果?

使用 optional / expected / 错误码

当前函数能处理吗?

本地处理

是否需要跨越多层调用栈?

抛出异常

优先考虑 expected

异常最适合的角色不是代替所有错误码，而是处理那些”这里已经无法继续，但更高层仍然知道该怎么办”的失败。

底层负责准确报告，中层负责维持不变量，边界层负责恢复或终止。至于每个函数都写一个 try/catch - 大可不必，那只是把错误码时代的 if (error) 换了一件稍微昂贵一点的外套。

我终于学会了 grep，然后换成了 ripgrep

Mon, 31 Aug 2026 07:00:00 GMT

我每天都能看到 grep：查日志时有它，读脚本时有它，甚至 AI 给出的命令里也经常有它。但我对它的理解长期停留在 “把一段神秘字符粘到管道后面”。这多少有点尴尬，所以我建了一个很小的实验目录，从一份 5 行日志开始，最后又让 grep 和 ripgrep 扫了 4096 个文件。搜索工具嘛，最好还是搜点东西再谈。

grep 的名字来自早期 Unix 编辑器 ed 中的命令 g/re/p，大意是全局寻找正则表达式并打印匹配行。名字已经半个世纪了，但它今天仍然在做同一件事：读取文本，寻找匹配模式，输出匹配的行。 它像一把文本世界里的筛子，标准输入或文件从上面倒进去，符合模式的行从下面落出来。这个比喻到这里就够了，后面我们直接看命令。

先做一份可以搜索的日志#

我创建了一个 app.log：

1
INFO boot
2
WARN cache slow
3
ERROR database timeout
4
INFO retry
5
ERROR recovered

最小的 grep 由模式和文件组成：

Terminal window

1
$ grep 'ERROR' app.log
2
ERROR database timeout
3
ERROR recovered

它的通用形状是：

Terminal window

1
grep [选项] '模式' [文件...]

我现在会默认用单引号包住模式。不是 grep 强制要求，而是 shell 也认识 *、$、[ 等字符。加引号等于先告诉 shell “这段别碰，完整交给 grep”，可以少掉一类很无聊的错误。

grep 到底匹配什么#

grep 默认按行工作。只要模式匹配一行中的任意部分，它就输出整行，而不是只输出命中的几个字符。根据 POSIX grep 规范，默认模式是基本正则表达式，也就是 BRE (Basic Regular Expression)。

先看几个我最常用的模式：

Terminal window

1
# 以 ERROR 开头
2
$ grep '^ERROR' app.log
3
ERROR database timeout
4
ERROR recovered
5

6
# 以 timeout 结尾
7
$ grep 'timeout$' app.log
8
ERROR database timeout
9

10
# 匹配 WARN 或 ERROR，-E 启用扩展正则表达式
11
$ grep -E 'WARN|ERROR' app.log
12
WARN cache slow
13
ERROR database timeout
14
ERROR recovered

^ 锚定行首，$ 锚定行尾，| 表示二选一。这里最容易踩的坑是：默认 BRE 和 grep -E 使用的 ERE (Extended Regular Expression) 语法并不完全一样。我如果需要 |、+、? 或分组，通常直接写 grep -E，而不是开始和反斜杠进行某种古老仪式。

如果我根本不需要正则表达式，只想搜索字面文本，就用 -F：

Terminal window

1
$ grep -F 'ERROR database' app.log
2
ERROR database timeout

这在搜索包含 .、[、* 的配置或代码时尤其省心。-F 的意思不是 “更弱的 grep”，而是 “不要解释特殊字符”。

我真正会记住的选项#

grep --help 很长，但日常使用不需要背完整本手册。下面这组已经覆盖了我大部分需求：

选项	作用	示例
`-n`	显示行号	`grep -n 'ERROR' app.log`
`-i`	忽略大小写	`grep -i 'error' app.log`
`-v`	反选不匹配的行	`grep -v '^INFO' app.log`
`-c`	统计匹配行数	`grep -c 'ERROR' app.log`
`-l`	只输出包含匹配的文件名	`grep -l 'ERROR' *.log`
`-w`	匹配完整单词	`grep -w 'ERROR' app.log`
`-x`	匹配完整一行	`grep -x 'INFO retry' app.log`
`-A 2`	输出命中行及后 2 行	`grep -A 2 'timeout' app.log`
`-B 2`	输出命中行及前 2 行	`grep -B 2 'timeout' app.log`
`-C 2`	输出命中行前后各 2 行	`grep -C 2 'timeout' app.log`
`-E`	使用扩展正则表达式	`grep -E ‘WARN
`-F`	按字面字符串匹配	`grep -F 'a[b]' file.txt`

例如带上行号后，我的 5 行日志给出：

Terminal window

1
$ grep -n -E 'WARN|ERROR' app.log
2
2:WARN cache slow
3
3:ERROR database timeout
4
5:ERROR recovered

统计也确实是 2 行：

Terminal window

1
$ grep -c 'ERROR' app.log
2
2

注意，-c 统计的是匹配行数，不是一行内出现了多少次模式。这个区别在脚本里很容易偷偷制造 bug。

grep 为什么总出现在管道里#

如果没有文件参数，grep 就从标准输入读取。于是任何能输出文本的命令都能接到它前面：

Terminal window

1
# 查找进程列表中的 ssh
2
ps aux | grep '[s]sh'
3

4
# 只保留日志中的错误
5
journalctl -u nginx | grep -i 'error'
6

7
# 在命令输出中寻找某个配置项
8
some-command --verbose | grep -F 'cache_dir='

第一条里的 [s]sh 是个老而实用的小技巧：它能匹配 ssh，但 grep 自己的命令行中出现的是 [s]sh，因此不会把自己也匹配出来。不过，如果系统提供 pgrep，按进程名或属性找进程通常更直接。能用结构化工具时，不必强迫文本筛子兼职数据库。

grep 还通过退出状态告诉脚本发生了什么：

0：至少匹配到一行。
1：没有匹配。
大于 1：发生错误。

所以检查是否存在时，我会使用 -q，而不是先输出再扔掉：

Terminal window

1
if grep -q 'ERROR' app.log; then
2
    echo 'found an error'
3
fi

“没有匹配” 是正常结果，不是工具坏了。理解这 3 种状态后，grep 才真正从交互命令变成了可靠的脚本部件。

从单个文件走进整个目录#

GNU grep 和很多现代实现支持递归搜索：

Terminal window

1
grep -R -n --include='*.ts' --exclude-dir=node_modules 'TODO' src

这里 -R 递归遍历目录，--include 只保留 TypeScript 文件，--exclude-dir 排除依赖目录。它能工作，但我必须逐项告诉 grep 什么值得搜索。项目一大，命令就开始长出越来越多的过滤条件。

这也是我开始理解 ripgrep 的位置。它并不是发明了另一种 “找字符串” 的方式，而是把递归搜索代码仓库设成了默认场景。

Note

grep 存在 POSIX、GNU、BSD 以及其他实现，不同系统的扩展选项可能不同。-E、-F、-i、-n、-q、-v 等核心选项有 POSIX 定义；-R、--include 这样的能力应以本机 man grep 或 grep --help 为准。写可移植脚本时，我不会假设所有机器都运行 GNU grep。

ripgrep：把代码仓库当成默认环境#

ripgrep 的可执行文件名是 rg。它同样逐行搜索模式，但直接递归搜索当前目录：

Terminal window

1
# grep 需要显式递归和目录
2
grep -R -n 'TODO' .
3

4
# rg 默认递归搜索当前目录
5
rg 'TODO'

在 Ubuntu 或 Debian、Fedora、Arch Linux 和 macOS 上，可以分别安装：

Terminal window

1
sudo apt install ripgrep
2
sudo dnf install ripgrep
3
sudo pacman -S ripgrep
4
brew install ripgrep

Windows 可以使用 Scoop：

Terminal window

1
scoop install ripgrep

安装后先确认实际版本：

Terminal window

1
rg --version

rg 最重要的特性可能不是速度，而是它默认不搜索什么。根据 ripgrep 官方指南，它默认跳过：

.gitignore、.ignore 和 .rgignore 排除的路径。
隐藏文件和隐藏目录。
检测到的二进制文件。
符号链接指向的内容。

我在一个 Git 仓库里做了 3 文件的小实验：visible.txt、被 .gitignore 排除的 ignored.log，以及隐藏文件 .hidden.txt。三个文件都只有一行 SECRET。为了不让 grep 顺手钻进 .git，我显式排除了它：

Terminal window

1
$ grep -R -n --exclude-dir=.git 'SECRET' .
2
./.hidden.txt:1:SECRET hidden
3
./visible.txt:1:SECRET visible
4
./ignored.log:1:SECRET ignored
5

6
$ rg -n 'SECRET' .
7
./visible.txt:1:SECRET visible

同一个目录里，grep 找到 3 行，rg 默认只给我 1 行。rg 不是漏搜了，它执行了更适合代码仓库的过滤策略。

需要掀开过滤器时，也有明确的开关：

Terminal window

1
# 搜索被 ignore 规则排除的路径
2
rg --no-ignore 'SECRET'
3

4
# 同时搜索隐藏文件
5
rg --hidden --no-ignore 'SECRET'
6

7
# -u 逐级解除限制：-u 忽略 ignore，-uu 包含隐藏文件，-uuu 还包含二进制文件
8
rg -uuu 'SECRET'

-uuu 很好记，但我不会把它设成默认别名。二进制内容可能把控制字符直接送进终端，而且 node_modules、构建产物和 .git 往往正是噪声的主要来源。只有当 “我明明知道它在这里” 时，我才逐级加 u。

rg 中最顺手的几种搜索#

多数 grep 习惯可以直接迁移：

Terminal window

1
rg -i 'error'                 # 忽略大小写
2
rg -F 'array[index]'          # 字面字符串
3
rg -w 'Result'                # 完整单词
4
rg -C 3 'panic'               # 前后各 3 行上下文
5
rg -l 'TODO|FIXME'            # 只列出文件名
6
rg -c 'TODO'                  # 按文件统计匹配行数
7
rg -q 'needle' path/to/file   # 静默检查，依靠退出状态

针对仓库筛选文件时，glob 比一长串目录参数更舒服：

Terminal window

1
rg 'fetchData' -g '*.ts' -g '*.tsx'
2
rg 'password' -g '!dist/**' -g '!*.min.js'

-g 可以重复使用，前面的 ! 表示排除。记得给 glob 加单引号，否则 shell 可能在 rg 看到它之前就先展开。

rg 还内置文件类型：

Terminal window

1
rg -tpy 'def main'       # 只搜索 Python
2
rg -tts 'fetchData'      # 只搜索 TypeScript
3
rg -Tjs 'TODO'           # 排除 JavaScript
4
rg --type-list           # 查看当前支持的类型

这里的文件类型本质上是一组扩展名和 glob，不是在做语法分析。如果我需要寻找真正的函数调用、声明或引用，AST 或语言服务器才是对的工具。正则表达式看起来像一把锤子，而代码仓库里碰巧到处都是长得像钉子的字符串，仅此而已。

两套正则表达式并不完全相同#

grep 默认使用 BRE，grep -E 使用 ERE。rg 默认使用 Rust 的 regex 引擎，支持 Unicode，并保证线性时间搜索，但默认不支持反向引用和 look-around。简单的搜索通常可以直接对应：

Terminal window

1
grep -E 'WARN|ERROR' app.log
2
rg 'WARN|ERROR' app.log

如果确实需要 look-around 或反向引用，并且当前 rg 构建包含 PCRE2，可以使用 -P：

Terminal window

1
rg -P 'ERROR(?= database)' app.log

我不会因为 PCRE2 更 “强” 就默认打开它。大多数代码搜索只需要字面量、字符类、分支和重复；默认引擎更可预测，也更不容易写出性能悬崖。复杂正则如果已经需要一杯咖啡才能读懂，通常也到了该换脚本或结构化工具的时候。

我测了一次速度，但不准备宣布宇宙真理#

为了不只复述 “ripgrep 很快”，我生成了 4096 个文本文件，并让其中每 16 个文件有 1 个包含固定字符串 needle-search-marker。当时我在 Python 会话中直接执行实验；下面把同一段生成逻辑整理成可独立运行的 generate_benchmark.py：

1
#!/usr/bin/env python3
2

3
from pathlib import Path
4

5
ROOT = Path("bench")
6
FILE_COUNT = 4096
7
MATCH_INTERVAL = 16
8
PATTERN = b"needle-search-marker\n"
9

10
if ROOT.exists():
11
    raise SystemExit("bench/ already exists; remove it before regenerating")
12

13
ROOT.mkdir()
14

15
line = ("alpha beta gamma delta epsilon 0123456789 " * 16 + "\n").encode()
16
plain_payload = line * 48
17

18
for index in range(FILE_COUNT):
19
    payload = plain_payload
20
    if index % MATCH_INTERVAL == 0:
21
        payload += PATTERN
22
    (ROOT / f"file-{index:04d}.txt").write_bytes(payload)
23

24
total_bytes = sum(path.stat().st_size for path in ROOT.iterdir())
25
matching_files = FILE_COUNT // MATCH_INTERVAL
26

27
print(f"files: {FILE_COUNT}")
28
print(f"size: {total_bytes} bytes ({total_bytes / 1024 / 1024:.2f} MiB)")
29
print(f"matching files: {matching_files}")

展开收起

这组参数最终生成 4096 个文件，总大小为 132322560 bytes，也就是 126.19 MiB，其中 256 个文件包含目标字符串。接下来的两组命令都会搜索这份固定语料。

Terminal window

1
$ python generate_benchmark.py
2
files: 4096
3
size: 132322560 bytes (126.19 MiB)
4
matching files: 256

下面再把同一次实验的计时逻辑整理成 benchmark.py。它先让每个工具预热 1 次，使语料进入系统缓存，然后正式运行 9 次。time.perf_counter() 测量的是从创建子进程到进程退出的墙钟时间，命令输出则送到 /dev/null，避免终端渲染成为主要开销。

1
#!/usr/bin/env python3
2

3
from pathlib import Path
4
import statistics
5
import subprocess
6
import time
7

8
ROOT = Path("bench")
9
PATTERN = "needle-search-marker"
10
RUNS = 9
11

12
if not ROOT.is_dir():
13
    raise SystemExit("bench/ does not exist; run generate_benchmark.py first")
14

15
commands = {
16
    "grep": ["grep", "-R", "-l", "-F", PATTERN, str(ROOT)],
17
    "rg": ["rg", "-l", "-F", PATTERN, str(ROOT)],
18
}
19

20
timings = {}
21

22
for command in commands.values():
23
    subprocess.run(command, stdout=subprocess.DEVNULL, check=True)
24

25
for name, command in commands.items():
26
    samples = []
27
    for _ in range(RUNS):
28
        started = time.perf_counter()
29
        subprocess.run(command, stdout=subprocess.DEVNULL, check=True)
30
        samples.append((time.perf_counter() - started) * 1000)
31
    timings[name] = samples
32

33
for name, samples in timings.items():
34
    formatted = ", ".join(f"{sample:.2f}" for sample in samples)
35
    print(f"{name}: {formatted} ms")
36
    print(f"{name} median: {statistics.median(samples):.2f} ms")
37

38
ratio = statistics.median(timings["grep"]) / statistics.median(timings["rg"])
39
print(f"grep / rg: {ratio:.2f}x")

展开收起

这份计时脚本通过 subprocess.run() 直接启动外部可执行文件，不经过 shell；在我的环境中，它解析到 GNU grep 3.12 和 ripgrep 15.1.0。因此，下面的数据确实来自 GNU grep 3.12，而不是其他 grep 实现。9 次原始数据按脚本记录的执行顺序列出，没有挑选或删除离群值：

次数	`grep`	`rg`
1	44.67 ms	13.90 ms
2	45. 36ms	14.66 ms
3	43.01 ms	14.96 ms
4	42.65 ms	15.72 ms
5	44.68 ms	15.91 ms
6	42.72 ms	11.92 ms
7	44.74 ms	15.04 ms
8	43.28 ms	13.66 ms
9	44.01 ms	14.59 ms
中位数	44.01 ms	14.66 ms

两个命令实际分别是：

Terminal window

1
grep -R -l -F 'needle-search-marker' bench/
2
rg -l -F 'needle-search-marker' bench/

因此，中位时间和相对值为：

工具	中位时间	相对值
`grep`	44.01 ms	3.00x
`rg`	14.66 ms	1.00x

这次 rg 大约快 3 倍。数字很具体，结论却必须克制：它只描述这台机器、这两个版本、热缓存、固定字符串和 4096 个文件。换成单个大文件、高匹配率、不同正则、机械硬盘或另一个 grep 实现，比例都可能变化。ripgrep 项目的官方 README 也明确提醒，单个 benchmark 永远不够。

我反而更在意前一个实验：在包含忽略文件和隐藏文件的目录中，默认输出从 3 行降到了 1 行。少掉的 2 行不是性能指标，而是我原本就不想看的噪声。这种默认行为每天都会影响搜索体验，44 ms 和 15 ms 则未必。

我现在怎么选#

我的规则最后变得很简单：

脚本要跨陌生的 Unix 环境运行：优先使用 POSIX grep 的核心选项。它普遍存在，而且契约有标准。
搜索单个文件或管道输出：grep 已经足够直接，尤其是系统上不一定安装 rg 时。
交互式搜索代码仓库：优先使用 rg。递归、ignore、隐藏文件过滤、glob 和文件类型都围绕这个场景设计。
搜索结果疑似被过滤：先试 rg -u、rg --hidden 或 rg --debug，不要立刻断言文件不存在。
需要理解代码结构：停止继续堆正则，换语言服务器、AST 搜索或 IDE 引用查找。

grep 没有因为 ripgrep 出现就过时。它更像 shell 世界里的基础协议，而 rg 是针对现代代码仓库重新安排过默认值的高性能客户端。我大概会继续在脚本里写 grep，在终端里敲 rg。至少下一次看到 grep -Eiv 时，我不再需要假装那是一串不可分割的魔法咒语了。

继续查阅#

从零学习 vcpkg: 用现代 CMake 做一个 HTTP CLI

Sun, 30 Aug 2026 12:00:00 GMT

我过去写的嵌入式项目主要使用 C，依赖通常是芯片厂商 SDK、几份直接放进仓库的源码，以及一些自己维护的驱动，所以我很少认真面对 C/C++ 包管理。Python 有 pip，JavaScript/TypeScript 有 npm 和 pnpm，Rust 有 Cargo；C++ 则把编译器、构建系统和包管理器拆成了三件事。于是我决定不再只背 vcpkg install，而是用 vcpkg、现代 CMake 和 3 个第三方库做一个真的能发出请求的 HTTP CLI，然后看看每一层到底负责什么。

这个小程序叫 vhttp。它支持 GET、POST、自定义 Header、超时和详细日志。CLI11 解析命令行，CPR 发送 HTTP 请求，spdlog 记录状态。3 个直接依赖最后展开成 10 个需要安装的 port，刚好足以看到包管理器开始工作，又没有膨胀成另一个 curl（我只是来学 vcpkg，不是来重写互联网的）。

先把 3 个角色分开#

C/C++ 依赖管理容易混乱，通常不是因为命令太多，而是因为几种工具同时出现在终端里：

编译器：GCC、Clang 或 MSVC，把源文件变成目标文件，并参与链接。
CMake：构建系统生成器，描述 target、源文件、编译选项和链接关系，再生成 Ninja、Makefile 或 Visual Studio 工程。
vcpkg：包管理器，解析依赖图，取得源码和 port 配方，按目标平台构建并安装库，再把它们交给 CMake 查找。

我把 vcpkg 想成仓库管理员，把 CMake 想成装配清单。仓库管理员负责把零件放到正确货架，装配清单负责说明 vhttp 需要哪些零件以及如何连接。二者会合作，但不是同一个东西。

vcpkg 也不等于一个只下载预编译二进制的商店。它的 registry 主要保存 port 的版本信息、补丁和构建配方，很多库会在本机按 triplet 编译。第一次安装 OpenSSL 或 Boost 时看到编译器忙起来，不是 vcpkg 突然兼职写代码，而是它正在按配方生产当前平台需要的产物。

安装 vcpkg#

官方的通用安装方式是克隆仓库并运行 bootstrap 脚本：

Terminal window

1
git clone https://github.com/microsoft/vcpkg.git
2
cd vcpkg
3
./bootstrap-vcpkg.sh -disableMetrics

Windows PowerShell 对应：

Terminal window

1
git clone https://github.com/microsoft/vcpkg.git
2
cd vcpkg
3
.\bootstrap-vcpkg.bat -disableMetrics

bootstrap 会准备 vcpkg 可执行文件。然后设置 VCPKG_ROOT，并把可执行文件加入 PATH。Linux 或 macOS 可以写入自己的 shell 配置：

Terminal window

1
export VCPKG_ROOT="$HOME/tools/vcpkg"
2
export PATH="$VCPKG_ROOT:$PATH"

PowerShell 当前会话可以这样设置：

Terminal window

1
$env:VCPKG_ROOT = "C:\tools\vcpkg"
2
$env:PATH = "$env:VCPKG_ROOT;$env:PATH"

最后检查实际入口，而不是假设 bootstrap 已经替我们处理了所有环境变量：

Terminal window

1
$ vcpkg version
2
vcpkg package management program version 2026-07-27-98d7cb0cf1f4686a3e43aa5672b6230c1d56bce8

版本会变化。这里真正重要的是命令可以运行，并且 VCPKG_ROOT 指向包含 scripts/buildsystems/vcpkg.cmake 的那份 vcpkg。

Classic mode 和 Manifest mode#

vcpkg 有两种工作模式：

模式	依赖声明	安装位置	适合场景
Classic mode	主要靠命令安装	`$VCPKG_ROOT/installed`	临时试用、旧项目
Manifest mode	项目提交 `vcpkg.json`	每个项目自己的安装树	正式项目、版本控制、CI

Classic mode 的体验接近系统级仓库：

Terminal window

1
vcpkg install fmt
2
vcpkg install fmt:x64-windows

这很适合快速试一个库，但依赖关系存在于开发者的机器里。换一台机器后，项目本身没有完整声明告诉我们该装什么。

Manifest mode 把直接依赖写进 vcpkg.json，并为每个项目维护独立安装树。它也支持 baseline、版本约束、override 和自定义 registry。对新项目，我会直接使用 Manifest mode。把依赖写进仓库，比把它们记在脑内某个没有备份的 YAML 文件里可靠得多。

建立 `vhttp`#

先创建目录并初始化应用清单：

Terminal window

1
mkdir vhttp
2
cd vhttp
3
vcpkg new --application
4
vcpkg add port cli11
5
vcpkg add port cpr
6
vcpkg add port spdlog

vcpkg new --application 会创建项目清单和 registry 配置，vcpkg add port 则把直接依赖写进清单。项目最终结构如下：

1
vhttp/
2
├── CMakeLists.txt
3
├── CMakePresets.json
4
├── src/
5
│   └── main.cpp
6
├── vcpkg-configuration.json
7
└── vcpkg.json

我还会忽略本机构建产物：

1
/build/
2
/vcpkg_installed/
3
CMakeUserPresets.json

vcpkg.json 很短：

1
{
2
  "name": "vhttp",
3
  "version-semver": "0.1.0",
4
  "dependencies": [
5
    "cli11",
6
    "cpr",
7
    "spdlog"
8
  ]
9
}

它只声明直接依赖。CPR 需要 curl，curl 的 HTTPS 支持需要 OpenSSL 和 zlib，spdlog 默认又需要 fmt；这些传递依赖由 vcpkg 解图，不应该为了复制一次安装输出就全部手写进 dependencies。

vcpkg-configuration.json 保存 registry 和 baseline：

1
{
2
  "default-registry": {
3
    "kind": "git",
4
    "baseline": "1390a3d90e08a7901a7781d31332a662102cd5cc",
5
    "repository": "https://github.com/microsoft/vcpkg"
6
  }
7
}

baseline 是 vcpkg registry 的一个 Git commit。它给整张依赖图一个确定的版本地板，让两台机器不要因为各自恰好在不同日期安装，就悄悄选到不同 port 版本。上面的 commit 是我这次实验实际使用的快照；新项目应该保留 vcpkg new 为自己生成的值，而不是机械复制它。

需要主动更新依赖视野时，可以运行：

Terminal window

1
vcpkg x-update-baseline

更新 baseline 是一个明确的依赖升级动作，应该连同构建结果一起审查和提交。它不是每次构建前都要念一遍的咒语。

Note

baseline 并不等于传统意义上的 lockfile。它确定 registry 快照；version>= 表达最低版本，overrides 可以强制精确版本。大多数应用先固定 baseline，只在确有需要时增加版本约束或 override，会比给每个传递依赖手工钉死版本更容易维护。

用 CMake Presets 接上 vcpkg#

vcpkg 通过一个 CMake toolchain 文件接入配置过程。关键点是：CMake 在执行第一次 project() 时就会确定工具链，所以 CMAKE_TOOLCHAIN_FILE 必须在那之前可见。

我不把本机的绝对路径写进 CMakeLists.txt，而是提交一份 CMakePresets.json：

1
{
2
  "version": 6,
3
  "configurePresets": [
4
    {
5
      "name": "dev",
6
      "displayName": "Development build with vcpkg",
7
      "generator": "Ninja",
8
      "binaryDir": "${sourceDir}/build/${presetName}",
9
      "cacheVariables": {
10
        "CMAKE_BUILD_TYPE": "Debug",
11
        "CMAKE_EXPORT_COMPILE_COMMANDS": true,
12
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
13
      }
14
    }
15
  ],
16
  "buildPresets": [
17
    {
18
      "name": "dev",
19
      "configurePreset": "dev"
20
    }
21
  ]
22
}

展开收起

Preset 固定了生成器、构建目录和共享配置，但通过环境变量取得每台机器自己的 vcpkg 路径。团队可以提交这份文件；如果某人不想全局设置 VCPKG_ROOT，也可以在不提交的 CMakeUserPresets.json 中继承 dev 并设置本机环境。

配置时，vcpkg toolchain 会发现项目根目录中的 manifest，并自动执行安装：

Terminal window

1
cmake --preset dev

我第一次配置时声明了 3 个直接依赖，vcpkg 实际列出了 10 个 port：

1
cli11
2
cpr
3
curl
4
fmt
5
openssl
6
spdlog
7
vcpkg-cmake
8
vcpkg-cmake-config
9
vcpkg-cmake-get-vars
10
zlib

从 3 个名字展开到 10 个构建节点，这就是手工下载压缩包、复制 include 路径和寻找 .a/.lib 文件开始变得不太可爱的地方。Manifest mode 会把这棵安装树放进当前构建目录的 vcpkg_installed，不会污染另一个项目。

现代 CMake 只围绕 target 工作#

根目录的 CMakeLists.txt 如下：

1
cmake_minimum_required(VERSION 3.25)
2

3
project(vhttp VERSION 0.1.0 LANGUAGES CXX)
4

5
find_package(CLI11 CONFIG REQUIRED)
6
find_package(cpr CONFIG REQUIRED)
7
find_package(spdlog CONFIG REQUIRED)
8

9
add_executable(vhttp)
10
target_sources(vhttp PRIVATE src/main.cpp)
11
target_compile_features(vhttp PRIVATE cxx_std_20)
12
target_link_libraries(vhttp
13
    PRIVATE
14
        CLI11::CLI11
15
        cpr::cpr
16
        spdlog::spdlog
17
)
18

19
target_compile_options(vhttp
20
    PRIVATE
21
        $<$<CXX_COMPILER_ID:MSVC>:/W4>
22
        $<$<CXX_COMPILER_ID:MSVC>:/permissive->
23
        $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall>
24
        $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wextra>
25
        $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wpedantic>
26
)

展开收起

这里没有全局 include_directories()，没有硬编码 lib 路径，也没有 link_directories()。find_package(... CONFIG REQUIRED) 找到库导出的 CMake package config，CLI11::CLI11、cpr::cpr 和 spdlog::spdlog 则是 imported target。

这些 target 自带 include 目录、编译定义和传递链接要求。vhttp 只需要声明”我以 PRIVATE 方式链接它们”。这就是现代 CMake 最重要的习惯：让 target 携带 usage requirements，而不是把一堆全局状态泼到整个目录上。

target_compile_features(vhttp PRIVATE cxx_std_20) 也比手工拼 -std=c++20 更可移植。警告选项确实因编译器而不同，所以我用 generator expression 在生成阶段选择 MSVC 或 GCC/Clang 的参数。

写一个真的 HTTP 客户端#

src/main.cpp 的完整实现如下：

1
#include <algorithm>
2
#include <cctype>
3
#include <iostream>
4
#include <stdexcept>
5
#include <string>
6
#include <vector>
7

8
#include <CLI/CLI.hpp>
9
#include <cpr/cpr.h>
10
#include <spdlog/spdlog.h>
11

12
namespace {
13

14
cpr::Header ParseHeaders(const std::vector<std::string>& raw_headers) {
15
  cpr::Header headers;
16
  for (const auto& raw : raw_headers) {
17
    const auto colon = raw.find(':');
18
    if (colon == std::string::npos || colon == 0) {
19
      throw std::runtime_error("invalid header, expected 'Name: Value': " +
20
                               raw);
21
    }
22

23
    auto value_start = colon + 1;
24
    while (value_start < raw.size() && raw[value_start] == ' ') {
25
      ++value_start;
26
    }
27
    headers.emplace(raw.substr(0, colon), raw.substr(value_start));
28
  }
29
  return headers;
30
}
31

32
std::string ToUpper(std::string value) {
33
  std::ranges::transform(value, value.begin(), [](unsigned char ch) {
34
    return static_cast<char>(std::toupper(ch));
35
  });
36
  return value;
37
}
38

39
}  // namespace
40

41
int main(int argc, char* argv[]) {
42
  CLI::App app{"A tiny HTTP client built with vcpkg"};
43

44
  std::string url;
45
  std::string method{"GET"};
46
  std::string body;
47
  std::vector<std::string> raw_headers;
48
  int timeout_ms{5000};
49
  bool verbose{false};
50

51
  app.add_option("url", url, "Request URL")->required();
52
  app.add_option("-X,--request", method, "HTTP method: GET or POST");
53
  app.add_option("-H,--header", raw_headers, "Request header, repeatable");
54
  app.add_option("-d,--data", body, "POST request body");
55
  app.add_option("--timeout", timeout_ms, "Timeout in milliseconds")
56
      ->check(CLI::PositiveNumber);
57
  app.add_flag("-v,--verbose", verbose, "Enable debug logs");
58

59
  CLI11_PARSE(app, argc, argv);
60

61
  method = ToUpper(method);
62
  if (method != "GET" && method != "POST") {
63
    spdlog::error("unsupported method: {}", method);
64
    return 1;
65
  }
66

67
  try {
68
    spdlog::set_level(verbose ? spdlog::level::debug : spdlog::level::info);
69
    spdlog::debug("{} {} (timeout={} ms)", method, url, timeout_ms);
70

71
    cpr::Session session;
72
    session.SetUrl(cpr::Url{url});
73
    session.SetHeader(ParseHeaders(raw_headers));
74
    session.SetTimeout(cpr::Timeout{timeout_ms});
75

76
    cpr::Response response;
77
    if (method == "POST") {
78
      session.SetBody(cpr::Body{body});
79
      response = session.Post();
80
    } else {
81
      response = session.Get();
82
    }
83

84
    if (response.error.code != cpr::ErrorCode::OK) {
85
      spdlog::error("request failed: {}", response.error.message);
86
      return 2;
87
    }
88

89
    spdlog::info("HTTP {} in {:.0f} ms, {} bytes", response.status_code,
90
                 response.elapsed * 1000.0, response.text.size());
91
    std::cout << response.text;
92
    if (!response.text.ends_with('\n')) {
93
      std::cout << '\n';
94
    }
95

96
    return response.status_code >= 400 ? 3 : 0;
97
  } catch (const std::exception& error) {
98
    spdlog::error("{}", error.what());
99
    return 1;
100
  }
101
}

展开收起

这里有一个刻意的接口设计：spdlog 把诊断信息写到标准错误，响应 body 写到标准输出。因此可以把 body 继续交给其他程序，而日志不会混进数据流：

Terminal window

1
vhttp https://example.com/api | jq .

jq 是一个处理 JSON 的命令行工具；管道符 | 会把 vhttp 写到标准输出的响应 body 交给 jq，最后的 . 表示读取并格式化整个 JSON 值。例如服务返回一行紧凑 JSON 时，jq . 会把它缩进为更容易阅读的多行结构。jq 不是 vhttp 的依赖，需要按操作系统单独安装；如果不需要格式化 JSON，直接运行 vhttp https://example.com/api 即可。

返回码也区分了几类失败：参数或 Header 错误返回 1，传输错误返回 2，HTTP 4xx/5xx 返回 3。HTTP 404 和 TCP 连接失败不是一回事，CLI 最好不要把它们都压成一个含糊的 false。

配置、构建和运行#

有了 configure preset 和 build preset，基本循环只有两条命令：

Terminal window

1
cmake --preset dev
2
cmake --build --preset dev

我的实际构建只有 2 个 Ninja step：编译 main.cpp，然后链接 vhttp。

Terminal window

1
[1/2] Building CXX object CMakeFiles/vhttp.dir/src/main.cpp.o
2
[2/2] Linking CXX executable vhttp

为了避免把外部网络状态混进验证，我使用 Python 3 标准库自带的 http.server 在本机启动了一个静态文件服务器。它不需要额外安装 Web 框架，只要系统中的 python3 命令可用即可。

我先在项目根目录创建测试目录和响应文件。printf 不会额外改写内容，因此这个文件恰好是 17 bytes：

Terminal window

1
mkdir -p http-fixture
2
printf 'hello from vhttp\n' > http-fixture/hello.txt

然后打开第一个终端，在项目根目录启动服务器：

Terminal window

1
$ python3 -m http.server 18080 \
2
    --bind 127.0.0.1 \
3
    --directory http-fixture
4
Serving HTTP on 127.0.0.1 port 18080 (http://127.0.0.1:18080/) ...

-m http.server 让 Python 运行标准库中的静态 HTTP server 模块。
18080 是监听端口。
--bind 127.0.0.1 只允许本机访问，避免把临时测试服务暴露到局域网。
--directory http-fixture 把刚才创建的目录作为网站根目录。

这条命令会占用当前终端并持续运行。验证结束后按 Ctrl + C 停止服务。Windows 如果安装了 Python Launcher，也可以把命令开头的 python3 换成 py。

接着打开第二个终端，仍然进入 vhttp 项目根目录，再运行客户端。URL 中的 /hello.txt 对应 http-fixture/hello.txt：

Terminal window

1
$ ./build/dev/vhttp -v http://127.0.0.1:18080/hello.txt
2
[debug] GET http://127.0.0.1:18080/hello.txt (timeout=5000 ms)
3
[info] HTTP 200 in 76 ms, 17 bytes
4
hello from vhttp

POST 和重复 Header 使用相同的可执行文件：

Terminal window

1
./build/dev/vhttp \
2
  -X POST \
3
  -H "Content-Type: application/json" \
4
  -H "Accept: application/json" \
5
  -d '{"message":"hello"}' \
6
  https://httpbin.org/post

这个外部 URL 只用于演示命令形式，服务可用性和响应时间不属于程序的确定性保证。

日常需要哪些 vcpkg 操作#

我最后留下的是一组很短的操作表：

Terminal window

1
# 搜索 registry 中的 port
2
vcpkg search cpr
3

4
# 向 manifest 添加直接依赖
5
vcpkg add port cpr
6

7
# 按当前 manifest 手动安装
8
vcpkg install
9

10
# 更新 registry baseline
11
vcpkg x-update-baseline
12

13
# 查看 triplet 帮助
14
vcpkg help triplet

在 Manifest mode 中，移除依赖的干净做法是从 vcpkg.json 的 dependencies 删除它，再重新配置或运行 vcpkg install，让声明成为唯一事实来源。不要一边保留 manifest 声明，一边手工删除安装树里的文件，那会把”当前状态”和”期望状态”重新拆开。

triplet 描述目标架构、操作系统、运行库和链接方式。常见默认值包括 x64-windows、x64-linux 和 x64-osx。如果需要 Windows 静态链接，可以在 preset 的 cacheVariables 中明确设置：

1
"VCPKG_TARGET_TRIPLET": "x64-windows-static"

改变 triplet、编译器或重要 vcpkg 配置后，我会使用新的 build 目录或删除旧 CMake cache 再配置。CMake cache 记住了第一次配置的工具链；试图在同一个目录里把整套 ABI 偷梁换柱，通常只会得到一段很有教育意义的错误日志。

vcpkg 默认还会使用 binary cache。第一次从源码构建后，它可以按 ABI hash 复用已构建包；CI 或团队也能通过 VCPKG_BINARY_SOURCES 配置共享文件、HTTP、NuGet 等后端。对这个小项目，本地默认 cache 已经够用。等构建 OpenSSL 的次数开始按团队人数相乘时，再配置共享 cache，收益会非常具体。

我实际踩到的坑#

find_package() 找不到库。 最常见原因不是库名拼错，而是配置阶段根本没有加载 vcpkg toolchain。检查 VCPKG_ROOT、preset 展开结果和 build 目录，不要靠全局 include_directories() 把错误暂时盖住。

下载失败不等于编译失败。 我第一次拉取 CPR 和 fmt 源码时遇到 curl error 56。重新下载后，vcpkg 继续使用已经完成的 port 和 binary cache，不需要从 0 重建全部 10 个节点。网络、port 构建和项目编译是 3 个阶段，先看失败发生在哪一层。

不要猜 CMake target 名。 port 安装完成后，vcpkg 会打印 usage，例如 find_package(cpr CONFIG REQUIRED) 和 target_link_libraries(... cpr::cpr)。包名、CMake package 名和 target 名不保证大小写或拼写完全一致，安装输出和 port 文档比直觉可靠。

不要把 toolchain 路径硬编码进项目。 本机的 C:\tools\vcpkg 对另一台机器没有意义。共享 preset 引用 $env{VCPKG_ROOT}，本机差异放环境变量或 CMakeUserPresets.json，边界会清楚很多。

再往前一步#

这次实验最有价值的产物其实不是 100 多行 C++，而是一条可以重复的链路：vcpkg.json 声明依赖，baseline 固定 registry 视图，triplet 描述目标 ABI，vcpkg toolchain 把安装树暴露给 CMake，imported target 再把 usage requirements 传给 vhttp。

我以后写桌面工具、网络服务或需要第三方库的嵌入式上位机时，大概率会继续沿用这套结构。项目变大后，可以增加自定义 triplet、manifest feature、overlay port 和共享 binary cache，但核心仍然是这 5 个文件和两条 CMake 命令。C++ 仍然没有突然长出一个随语言发行的 Cargo，不过现在至少依赖不再散落在下载目录和项目属性对话框里。很好，我可以继续写 C++ 了。

参考资料#

npm 与 pnpm 安装的到底是什么？从 JavaScript 包到原生模块

Fri, 28 Aug 2026 12:00:00 GMT

我一开始也以为 npm 和 pnpm 安装的就是 JavaScript 或 TypeScript 包，最多再附带几段配置文件。直到我见到的包越来越多，尤其是 sharp 这类会带上原生 .node 模块、预编译二进制和平台依赖的包，这个模型终于不够用了。于是我在 WSL2 里建了一个隔离项目，沿着 registry、tarball、lockfile、store 和 node_modules 一路观察：我们安装的到底是什么，最后又是谁把它变成了一个可以执行的命令。

本文以 WSL2 中的 Ubuntu 22.04 LTS 为例，命令行提示符统一使用虚构的 user@wsl。路径中的用户名、主机名、硬件、IP、Windows 路径和日志路径均已省略；示例版本和下载数量也会随时间变化，不要把它们当成自己的环境事实。

我会先建立一份隔离实验，再回头解释每个文件和命令为什么出现。这样比背安装咒语可靠得多：包管理器就像仓库管理员，lockfile 是出入库账本，node_modules 则是当前项目真正拿来工作的装配区。

npm、pnpm、Node.js 和 nvm 分别是什么#

Node.js 是 JavaScript 的运行时，负责执行 JavaScript 程序。
npm 是 Node.js 生态的包管理器，通常随 Node.js 一起安装。它负责下载依赖、维护 package.json 和 package-lock.json，也能执行项目脚本。
pnpm 是独立的 Node.js 包管理器。它与 npm 使用同一个 npm registry 生态，但命令、锁文件和 node_modules 的组织方式有所不同。
nvm 是 Node.js 版本管理器，用来安装和切换 Node.js 版本。它不是包管理器，也不负责安装项目依赖。
Corepack 是包管理器入口和版本准备工具。它可以根据项目声明准备指定版本的 pnpm 或 Yarn，但它不是 npm，也不负责安装项目依赖。

npm 和 pnpm 怎么选#

两者都能创建项目、安装依赖和执行脚本，但默认行为不同：

对比项	npm	pnpm
通常来源	随 Node.js 发行版提供	独立安装或由 Corepack 准备
锁文件	`package-lock.json`	`pnpm-lock.yaml`
默认依赖布局	直接组织在项目 `node_modules` 中	共享 store，加 virtual store 和链接
磁盘复用	依赖具体版本和配置	共享内容寻址 store，通常更节省空间
依赖声明约束	相对宽松	链接布局更容易暴露未声明依赖
添加依赖	`npm install <pkg>`	`pnpm add <pkg>`

推荐规则很简单：新项目优先考虑 pnpm，已有项目必须遵循项目声明。 如果项目已经提交了 package-lock.json，通常使用 npm；如果项目已经提交了 pnpm-lock.yaml，就使用 pnpm。不要在同一个项目里交替执行 npm install 和 pnpm install，这样会产生两套锁文件和难以解释的依赖变化。

pnpm 并不是所有场景的唯一答案。只想快速开始一个小项目，或者参与明确要求 npm 的项目时，npm 更直接。选择的关键不是“哪个命令更酷”，而是项目是否有明确的包管理器契约，以及团队是否统一使用它。

在 WSL2 中准备 Node.js#

进入 Ubuntu 后，可以先确认系统和 shell。以下输出只保留与教程有关的部分：

Terminal window

1
user@wsl:~$ uname -sr
2
Linux 6.x.x-microsoft-standard-WSL2
3
user@wsl:~$ bash --version | head -n 1
4
GNU bash, version 5.1.16

使用 nvm 安装 Node.js。安装远程脚本前应先阅读来源和内容，因为 curl | bash 会直接执行下载的脚本：

Terminal window

1
user@wsl:~$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh | bash
2
=> Downloading nvm from git to '$HOME/.nvm'
3
=> Appending nvm source string to '$HOME/.bashrc'

当前 shell 立即加载 nvm：

Terminal window

1
user@wsl:~$ . "$HOME/.nvm/nvm.sh"
2
user@wsl:~$ nvm install 24
3
Downloading and installing node v24.20.0...
4
Computing checksum with sha256sum
5
Checksums matched!
6
Now using node v24.20.0 (npm v11.19.0)
7
Creating default alias: default -> 24 (-> v24.20.0 *)
8
user@wsl:~$ node --version
9
v24.20.0
10
user@wsl:~$ npm --version
11
11.19.0

这里的 npm 已经随 Node.js 一起提供。此时可以使用 npm，但还没有因为安装 Node.js 就自动得到 pnpm。

Corepack 到底做什么#

Corepack 最容易被误解成“另一个包管理器”。更准确的分层是：

Node.js 执行 JavaScript。
npm 是一个包管理器，通常随 Node.js 分发。
pnpm 和 Yarn 是其他包管理器。
Corepack 是包管理器版本管理器，为 pnpm、Yarn 等准备版本并提供转发入口。

Corepack 解决的问题是：应该运行哪个版本的包管理器。它不解决：项目应该安装哪些依赖。后一个问题仍由 pnpm install、pnpm add、npm install 等命令负责。

这里有一个容易随 Node.js 版本变化的现实：不能假设每个 Node.js 发行版都内置 Corepack。检查命令是否存在；如果不存在，按项目文档安装 pnpm，或者使用 pnpm 官方提供的安装方式。无论采用哪种方式，最后都要检查实际运行的 pnpm --version，而不是只检查安装命令是否成功。

`corepack enable pnpm` 发生了什么#

在提供 Corepack 的 Node.js 环境中执行：

Terminal window

1
user@wsl:~$ corepack --version
2
0.35.0
3
user@wsl:~$ corepack enable pnpm
4
user@wsl:~$ type -a pnpm
5
pnpm is .../bin/pnpm

corepack enable pnpm 通常会创建或启用一个名为 pnpm 的 shim。shim 不是完整的 pnpm，它更像一个转接头：用户执行 pnpm 时，shim 把请求交给 Corepack；Corepack 再准备合适版本的 pnpm 并转发参数。

因此第一次执行 pnpm 时，可能看到下载确认：

Terminal window

1
user@wsl:~$ pnpm --version
2
! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.24.0.tgz
3
? Do you want to continue? [Y/n] y
4
11.24.0

这次下载的是 pnpm 自己，不是项目依赖。确认下载后，Corepack 保存或复用这个包，之后继续把 pnpm 命令交给它执行。

`packageManager` 和 Corepack 的关系#

项目可以在 package.json 中写：

1
"packageManager": "pnpm@11.22.0"

这个字段是项目声明，意思是“处理这个项目时使用 pnpm 11.22.0”。它不是依赖声明，也不会把 pnpm 写入项目的 dependencies。

如果项目的 .npmrc 还包含：

1
manage-package-manager-versions = true

那么 pnpm 可以根据 packageManager 字段参与包管理器版本管理。可以把两者理解为：

packageManager：项目声明应该使用什么工具和版本。
manage-package-manager-versions：pnpm 是否允许按这项声明管理工具版本。
Corepack shim：让命令能够进入版本准备和转发流程。
pnpm install：真正安装项目依赖。

这个配置键是 pnpm 的设置，不是 npm 的通用配置。若同一目录还会运行 npm，npm 可能提示 Unknown project config；这不是安装失败，但说明不应把 pnpm 专属选项当成跨工具协议。项目最好只保留实际使用的包管理器配置，并把团队约定写进项目文档或自动检查中。

检查四个版本时，命令和输出应分别理解：

Terminal window

1
user@wsl:~$ node --version
2
v24.20.0
3
user@wsl:~$ npm --version
4
11.19.0
5
user@wsl:~$ corepack --version
6
0.35.0
7
user@wsl:~$ pnpm --version
8
11.24.0

如果某个 Node.js 发行版没有提供 Corepack，corepack 命令可能不存在。这时应按照项目文档安装 pnpm，最后仍然用 pnpm --version 检查实际运行版本。全局安装 pnpm、Corepack 提供命令入口、pnpm add 安装项目依赖，是三个不同动作。

Warning

不要把 corepack enable、全局安装 pnpm 和 pnpm add 混成一个动作。前两者处理“命令从哪里来、运行哪个版本”，最后一个才修改当前项目的依赖。

用隔离项目观察安装过程#

不要为了学习包管理器直接修改重要项目。创建临时目录后，在其中安装几个形态不同的包：

Terminal window展开收起

1
user@wsl:~$ tmp_dir=$(mktemp -d)
2
user@wsl:~$ echo "$tmp_dir"
3
/tmp/tmp.xxxxxxxx
4
user@wsl:~$ cd "$tmp_dir"
5
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm init
6
Wrote to /tmp/tmp.xxxxxxxx/package.json
7
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm add lodash typescript sharp
8
Packages: +9
9
Progress: resolved 54, reused 0, downloaded 12, added 9, done
10

11
 dependencies:
12
+ lodash 4.18.1
13
+ sharp 0.35.4
14
+ typescript 7.0.2
15

16
Done in 6.5s using pnpm v11.24.0

展开收起

这里的版本和下载数量会变化。重要的是动作：pnpm init 创建 package.json，pnpm add 修改依赖声明、解析依赖并创建安装目录。

查看生成的声明：

Terminal window

1
user@wsl:/tmp/tmp.xxxxxxxx$ cat package.json
2
{
3
  "name": "tmp-project",
4
  "version": "1.0.0",
5
  "packageManager": "pnpm@11.24.0",
6
  "type": "module",
7
  "dependencies": {
8
    "lodash": "^4.18.1",
9
    "sharp": "^0.35.4",
10
    "typescript": "^7.0.2"
11
  }
12
}

pnpm init 在不同版本中生成的字段可能不同。不要把临时项目的名字、版本或格式当成固定模板。

用 npm 做一次对照#

我会再开一个目录，只安装一个开发工具。这样实验不会把 npm 和 pnpm 的文件混在一起：

Terminal window

1
user@wsl:~$ npm_dir=$(mktemp -d)
2
user@wsl:~$ cd "$npm_dir"
3
user@wsl:/tmp/tmp.yyyyyyyy$ npm init -y
4
Wrote to /tmp/tmp.yyyyyyyy/package.json
5
user@wsl:/tmp/tmp.yyyyyyyy$ npm install --save-dev typescript
6
added 1 package, and audited 2 packages in 1s
7
user@wsl:/tmp/tmp.yyyyyyyy$ npm exec tsc -- --version
8
Version 7.0.2

这个目录会得到 package-lock.json，而不是 pnpm-lock.yaml。npm exec 和 pnpm exec 都优先使用项目本地的 CLI，但两者不会共享锁文件格式，也不应该在同一个项目里轮流负责更新依赖。这个对照实验的价值不在于哪一个命令少敲两个字符，而在于把“同一个 registry 生态”和“不同的项目安装实现”分开观察。

包不是语言#

registry 发布的是带元数据的 tarball，而不是“一个 JavaScript 文件”。包中可以包含：

JavaScript 或 TypeScript 源码
WASM 文件
原生 .node 模块
预编译二进制
CLI 入口
其他包的运行时或平台依赖

实验中的三个包分别说明了不同情况：

lodash 主要作为可导入的 JavaScript API 使用。
typescript 提供 API，也通过 bin 字段提供 tsc 命令。
sharp 会根据操作系统和 CPU 解析平台相关实现，安装时可能出现 @img/* 等平台包。

查询 registry 元数据：

Terminal window

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm view lodash dist.tarball
2
https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz
3
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm view typescript bin --json
4
{
5
  "tsc": "bin/tsc"
6
}

bin 字段表示包声明了命令入口。安装后，包管理器会在项目中创建 node_modules/.bin/tsc 的链接或 shim：

Terminal window

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm exec tsc --version
2
Version 7.0.2

tsc 不是 shell 自带命令，也不是独立安装的系统程序。它来自 TypeScript 包的 bin 声明，最终由 Node.js 执行。判断一个包能做什么，应查看它的 exports、main、bin、平台依赖和安装脚本，而不是只看包名。

一次安装改变了哪些东西#

可以把项目依赖分成三层：

声明层：package.json 中的 dependencies 和 devDependencies。
解析层：lockfile 中的实际版本、间接依赖、peer dependency 和完整性信息。
落盘层：store、virtual store、node_modules 链接和 .bin 入口。

运行 pnpm add lodash 时，大致发生四步：

读取项目边界和 registry 配置。
查询包元数据，按照 semver 范围选择版本并写入 lockfile。
下载 tarball，校验后写入内容寻址 store。
在项目中创建依赖链接和命令入口。

用命令查看这些层：

Terminal window

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm root
2
/tmp/tmp.xxxxxxxx/node_modules
3
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm store path
4
<home-directory>/.local/share/pnpm/store/v11
5
user@wsl:/tmp/tmp.xxxxxxxx$ realpath node_modules/lodash
6
/tmp/tmp.xxxxxxxx/node_modules/.pnpm/lodash@4.18.1/node_modules/lodash
7
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm why sharp
8
sharp@0.35.4
9
└── tmp-project@1.0.0 (dependencies)

pnpm 的 store 像共享零件仓，node_modules/.pnpm 像当前项目的装配区，顶层 node_modules/lodash 是给 Node.js 看的入口。多个项目可以复用 store，但项目自己的 package.json、lockfile、链接和 peer 组合仍然独立。

npm 的目标相同，但默认的依赖布局不同。应用代码应依赖包公开的 exports 或 main，不要依赖某个包管理器偶然生成的内部路径。

^1.2.3 是版本范围，不是唯一版本。它允许一定范围内的更新；lockfile 则记录这次实际选择的版本。pnpm install --frozen-lockfile 会拒绝在安装时偷偷修改 lockfile，适合 CI 和新机器：

Terminal window

1
user@wsl:/path/to/project$ pnpm install --frozen-lockfile
2
Lockfile is up to date, resolution step is skipped
3
Already up to date

npm 项目通常使用 npm ci 达到类似的“按已有锁文件安装”效果。pnpm install 和 pnpm update 也不是一回事：前者按当前声明安装，后者主动寻找允许范围内的新版本。

命令为什么能运行#

普通 shell 通过 PATH 查找命令：

Terminal window

1
user@wsl:/tmp/tmp.xxxxxxxx$ command -v node
2
<node-installation>/bin/node
3
user@wsl:/tmp/tmp.xxxxxxxx$ type -a pnpm
4
pnpm is <node-installation>/bin/pnpm

执行项目脚本时，npm 和 pnpm 会临时把项目的 node_modules/.bin 放到脚本环境的 PATH 前面。因此，安装 TypeScript 后可以在 package.json 中定义：

1
"scripts": {
2
  "type-check": "tsc --version"
3
}

普通 shell 不会自动注入这层 PATH。可以通过以下两种入口明确执行同一个本地 tsc：

Terminal window

1
user@wsl:/path/to/project$ pnpm exec tsc --version
2
Version 7.0.2
3
user@wsl:/path/to/project$ node_modules/.bin/tsc --version
4
Version 7.0.2

四种常见入口可以这样区分：

node src/index.mjs：Node.js 直接运行文件。
pnpm exec tsc --version：从当前项目依赖中寻找并运行 tsc。
pnpm run dev：读取 package.json 的 scripts，并注入本地 .bin PATH。
脚本启动 Node.js、shell 或其他子进程：子进程继承脚本环境。

`npm run`、`pnpm run` 和直接执行#

npm run build 与 pnpm run build 都会读取 package.json 的 scripts 字段，并把项目的 node_modules/.bin 放到脚本环境的 PATH 前面。脚本因此可以直接调用本地安装的 tsc、astro 或 vite，不需要用户把它们全局安装一份。

我通常把入口分成三类：

node src/index.mjs：Node.js 直接运行文件，完全绕开包管理器脚本。
pnpm exec tsc --version：从当前项目依赖中寻找并运行本地 CLI。
pnpm run type-check：读取脚本定义，并注入 .bin PATH；npm 项目对应 npm run type-check。

pnpm dlx、npx 和 npm exec 适合一次性获取并执行 CLI。它们的便利之处也是风险所在：命令可能触发一次临时下载，且不会把工具记录为项目依赖。需要可复现的工具，应写入 devDependencies，再通过脚本或 pnpm exec 使用。

registry、换源和网络故障#

registry 是提供包元数据和 tarball 的 HTTP 服务。它可以是 npm 默认 registry、第三方镜像、公司私有 registry 或代理缓存。切换 registry 只改变查询和下载的来源，不改变项目依赖目录，也不会自动修复错误的版本范围。

我会先检查当前配置，而不是直接删除缓存：

Terminal window

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm config get registry
2
https://registry.npmjs.org/
3
user@wsl:/tmp/tmp.xxxxxxxx$ npm config get registry
4
https://registry.npmjs.org/

只验证一次时，使用命令行参数，不改变配置文件：

Terminal window

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm view lodash version --registry=https://registry.npmjs.org/
2
4.18.1

项目级 .npmrc 适合项目配置，用户级配置适合个人默认值。认证信息不要写死在仓库中：

1
//registry.example.invalid/:_authToken=${NPM_TOKEN}

遇到 ERR_PNPM_NO_MATCHING_VERSION，先检查包名、registry 和可用版本，再检查 semver、lockfile 和平台限制。遇到网络超时或证书错误，依次检查 registry、DNS、代理、系统时间和 CA。不要把清空整个缓存当成万能修复。

audit 与生命周期脚本#

audit 会把依赖树中的包名和版本与已知漏洞公告进行匹配。它不审查业务代码，也不能证明没有报告的包绝对安全：

Terminal window

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm audit
2
No known vulnerabilities found
3
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm audit --prod
4
No known vulnerabilities found

安装依赖本身也可能执行代码。preinstall、install、postinstall 和 prepare 可能编译 native addon、下载平台产物、生成代码，甚至执行任意脚本。安装前应审查包来源和生命周期脚本；在 CI 中可以评估 --ignore-scripts 是否适合项目，但不要把关闭安全检查当成第一步修复。

如果项目的 package.json 声明了 devEngines.packageManager，却使用了错误的包管理器，npm 可能报：

1
npm error code EBADDEVENGINES
2
npm error Invalid name "pnpm" does not match "npm"

这表示当前 npm 不符合项目要求，不是一次漏洞扫描结果。正确做法是切换到项目声明的 pnpm，而不是删除检查或绕过它。

从零建立可迁移环境#

新机器可以按以下顺序操作：

在 WSL2 中准备 Ubuntu 和 shell。
使用 nvm 安装满足项目 engines 的 Node.js，并确认 shell 启动文件已加载 nvm。
检查 node --version 和 npm --version。
启用或安装项目规定的 pnpm，并检查 corepack --version（若存在）和 pnpm --version。
进入项目根目录，先阅读 package.json 的 packageManager、engines 和 lockfile 类型。
执行项目规定的锁定安装：pnpm 项目使用 pnpm install --frozen-lockfile，npm 项目通常使用 npm ci。
按项目文档执行开发、检查、构建和预览命令。

如果项目位于 /mnt/c 或其他 Windows 挂载路径，安装和大量小文件访问可能明显慢于 Linux 文件系统中的 ~/projects。这是 I/O 边界的代价，不是 pnpm store 损坏；我通常把源码和 store 放在 WSL2 的 Linux 文件系统里，只通过编辑器或 Git 与 Windows 侧协作。

最小排错表：

症状	先查什么	最小修复	如何确认
`command not found`	`command -v pnpm`、`echo $PATH`	修正 PATH 或 Corepack 入口	`pnpm --version`
`ERR_PNPM_NO_MATCHING_VERSION`	包名、registry、可用版本	修正版本范围或 registry	`pnpm view <pkg> versions`
registry 超时或证书错误	registry、代理、系统时间	修正源、DNS、代理或 CA	单次 `pnpm view` 成功
lockfile 不同步	`git diff package.json pnpm-lock.yaml`	使用正确管理器更新锁文件	`pnpm install --frozen-lockfile`
Node 不满足 engines	`node --version`	切换 Node.js 版本	版本满足 `engines`
native 模块安装失败	`pnpm why <pkg>`、平台包和安装日志	修复平台依赖或编译链	实际导入模块
脚本找不到本地 CLI	`pnpm exec <cmd>`、脚本 PATH	使用项目脚本或 `pnpm exec`	`<cmd> --version`
`EBADDEVENGINES`	`packageManager`、当前包管理器	使用项目声明的管理器	`pnpm --version`

整条路径可以概括为：

Shell PATH

npm 或 pnpm

registry 元数据

tarball

pnpm store

virtual store

node_modules 链接

.bin shim

Node.js 进程

package.json scripts

Shell PATH

npm 或 pnpm

registry 元数据

tarball

pnpm store

virtual store

node_modules 链接

.bin shim

Node.js 进程

package.json scripts

真正值得记住的不是一串安装咒语，而是这条边界链：包从哪个 registry 来，版本解析记录在哪里，文件落在哪一层，命令由哪个入口转给哪个 Node.js。顺着这条链排查，npm 和 pnpm 的差异就会变成可以观察和验证的实现选择。未来包管理器大概还会继续把“下载一个包”包装成更多自动化，但 lockfile、脚本和运行时边界不会凭空消失；理解它们，至少能让下一次 command not found 变成一个可定位的实验，而不是一次祈祷。

参考资料#

Cudy TR3000 256 MB 刷入 ImmortalWrt：一次完整的图形化流程

Thu, 27 Aug 2026 01:00:00 GMT

刷机风险提示

以下风险提示来自 Cudy 官方京东自营店，具体情况请以官方最新说明为准：

刷机后遇到的相关问题，需您自主寻求解决方案，店铺不提供技术支持。
刷机后不支持退货退款，保修期内最多支持两次因刷机产生的售后。
保留权益：除刷机产生的售后外，其他质量问题在保修期内仍可享受正常售后。

本文只记录我这台 Cudy TR3000 256 MB V1 的实际操作。刷机有风险，请确认自己能接受设备无法启动、需要恢复固件，甚至失去部分售后支持的结果。官方政策和设备支持范围可能变化，购买和操作前请以 Cudy 官方说明为准。

我在 2025 年 9 月 1 日买过一台 Cudy TR3000 256 MB V1，刷入 ImmortalWrt 后用了接近一年，网络稳定性和日常体验都还不错。2026 年 8 月 24 日，机缘巧合之下，我又买了一台同型号设备，于是决定把这次从原厂系统到 ImmortalWrt，再到自定义镜像和官方恢复的完整过程记录下来。

这次我没有拆机，也没有进入 UART 或 U-Boot。真正做的事情基本都在浏览器里完成，唯一稍微像“网络工程”的部分是最后用 Tftpd64 通过 TFTP 把官方固件送回路由器。整个过程更像一条网页里的接力赛：原厂网页先交棒给中间固件，中间固件再交棒给 ImmortalWrt，最后我还让它跑了一圈自定义构建。

先确认：这是 256 MB 版本#

这台设备背面标签右上角明确写着 256 MB 闪存版，产品型号是 TR3000，管理地址是 192.168.10.1。

2026 年购买的 Cudy TR3000 256 MB V1 原始背面标签照片

这台设备的 SN 前缀是 S0001825。去年那台设备的 SN 前缀则是 TR3000。两台机器标签形式不同，但都明确标注了 256 MB 闪存版本。本文只记录这两台 256 MB V1 设备，不把其他批次的 SN 规则推广到本设备之外。

2025 年购买的 Cudy TR3000 256 MB V1 原始背面标签照片

Important

文章中的文件名、界面和分区选择只适用于明确标注为 Cudy TR3000 256 MB V1 的设备。不要只凭 SN 猜测硬件版本，应该先确认机身标签上的容量标识。

第一次开机：先把原厂网页走完#

我建议全程使用网线，把电脑连接到路由器的 LAN 口。开始前关闭电脑上的其他网络连接，避免电脑通过 Wi-Fi 或另一块网卡走错路由。刷写过程中保持 USB-C 供电稳定，不要碰电源线。

打开：

1
http://192.168.10.1

第一次登录时，原厂页面会要求创建管理员密码。我这里设置成了 00000000，只是为了演示方便；实际使用请设置一个强密码，并在发布截图前自行处理其中的敏感信息。

原厂首次登录时创建管理员密码的页面

设置密码后，系统会进入快速设置引导。我按下面的顺序一路点击“下一步”：

选择模式。
选择时区。
配置 WAN。
配置无线网络。
查看概要。
点击“保存&应用”。

原厂快速设置中的模式选择页面

原厂快速设置中的时区选择页面

原厂快速设置中的 WAN 配置页面

原厂快速设置中的无线配置页面

原厂快速设置的概要页面

完成设置后，进入原厂系统界面。页面底部的浅灰色文字包含版权信息、硬件版本、系统版本、Cudy 官网和售后邮件地址。再进入“系统”，可以看到更完整的系统信息，两处内容能够互相对应。

原厂系统主页，底部显示硬件版本和系统版本信息

原厂系统信息页面

第一步：刷入签名中间固件#

原厂升级入口会检查固件签名。直接把 ImmortalWrt 镜像上传到原厂网页，结果就是报错，这并不奇怪。Cudy 官方提供了一个签名中间固件，先用它绕过原厂网页这一层限制，再从中间系统安装我们真正想用的系统。

我使用的是 Cudy 官方 Google Drive 文件夹中的：

1
TR3000 256MB Flash V1 (not for TR3000 V1)

其中的文件名是：

1
cudy_tr3000-256mb-v1-sysupgrade.bin

官方入口：Cudy OpenWrt 软件和中间固件下载。页面底部提供了 Google Drive 中间固件文件夹，进入 TR3000 256MB Flash V1 (not for TR3000 V1) 文件夹后下载对应文件。下载后先把文件保存好，不要等到网页已经打开时才临时寻找。

如果直接上传未签名或不匹配的文件，原厂页面会显示错误。

原厂网页上传不匹配固件时的报错页面

进入“基本设置”，选择“固件升级”。

原厂基本设置中的固件升级入口

点击上传，选择 cudy_tr3000-256mb-v1-sysupgrade.bin。

原厂网页上传 256 MB 签名中间固件

点击“继续”后，页面会弹出刷写进度。此时不要关闭页面、拔掉网线或断开电源。

签名中间固件正在刷写

刷写完成后，路由器会自动重启。

签名中间固件刷写完成，路由器正在重启

这个过程中指示灯会变红。等到路由器完成重启，指示灯恢复白色，再继续下一步。

第二步：进入中间系统#

原厂系统的地址是 192.168.10.1，中间系统启动后地址变为：

1
http://192.168.1.1

中间系统第一次登录时默认没有密码，直接点击“登录”即可。

重启后进入中间固件的登录页面

登录后可以确认当前系统已经从 Cudy 原厂系统变成了 OpenWrt 中间固件。

中间固件的系统主页

这里是一个很容易误判的节点：现在还没有完成 ImmortalWrt 安装，只是完成了从原厂签名系统到 OpenWrt 中间系统的过渡。

第三步：刷入 ImmortalWrt 25.12.1#

我使用 ImmortalWrt Firmware Selector 的固定地址选择设备：

https://firmware-selector.immortalwrt.org/?version=25.12.1&target=mediatek%2Ffilogic&id=cudy_tr3000-256mb-v1

页面中的设备 profile 必须是：

1
cudy_tr3000-256mb-v1

ImmortalWrt Firmware Selector 中的 256 MB 设备 profile

在下载选项中选择 SYSUPGRADE，不要选择下面的 KERNEL。我下载到的文件名是：

1
immortalwrt-25.12.1-mediatek-filogic-cudy_tr3000-256mb-v1-squashfs-sysupgrade.bin

回到中间固件管理页面，进入“系统”，选择“备份与升级”。

中间固件中进入备份与升级的点击顺序

点击最下方的“刷写固件…”，上传刚才下载的 ImmortalWrt sysupgrade 文件。

上传 ImmortalWrt 25.12.1 sysupgrade 固件

上传后取消勾选“保留当前配置”，再点击“继续”。我选择清除旧配置，是因为中间固件和目标系统之间并不存在值得冒险保留的配置兼容性。

ImmortalWrt 固件正在刷写

刷写时指示灯会变红并闪烁。等到指示灯变白，路由器完成自动重启，就可以重新进入 ImmortalWrt。

重启后进入 ImmortalWrt 系统界面

首次配置和软件包#

ImmortalWrt 初次进入时，会询问是否开启“值守式系统升级”。它的含义是让系统自动检查并执行符合条件的系统升级，减少手动维护工作，但自动升级也意味着升级时机和配置变化不再完全由用户控制。

我在演示手动升级，所以选择“否，禁用检查”。如果这是长期运行的设备，请根据自己的备份习惯和风险接受程度决定，不要把“自动”两个字直接等同于“更安全”。

刚刷好的系统功能比较基础，但额外软件可以从 LuCI 图形界面安装。点击顶部“系统”，再进入“软件包”。

ImmortalWrt 系统菜单中的软件包入口

进入软件包页面后，先点击“更新列表…”，再在左侧“过滤器”中输入软件名，在结果列表中选择安装。

ImmortalWrt 软件包管理页面

这里有一个值得记住的细节：安装和卸载软件包不会直接修改只读系统镜像。系统会在原有镜像上叠加一个 overlay，配置和额外文件通常进入这一层。好处是系统镜像和运行时修改分离，代价是 overlay 空间不是无限的。

第四步：申请预装软件的自定义镜像#

直接在系统里安装软件已经够用，但我还想记录一次完整的自定义构建流程，于是回到同一个 Firmware Selector 页面，点击“自定义预安装软件包和/或首次启动脚本”。

页面里已经包含一组基础软件包。我保留这些基础包，只在后面追加自己需要的内容。我的校园网使用深澜认证，所以增加了 bitsrunlogin-go；为了改善界面，又增加了 Argon 主题：

1
bitsrunlogin-go luci-app-bitsrunlogin-go luci-i18n-bitsrunlogin-go-zh-cn
2
luci-theme-argon luci-i18n-argon-config-zh-cn luci-app-argon-config

完整的软件包配置如下：

1
apk-openssl autocore base-files block-mount bridger ca-bundle default-settings-chn dnsmasq-full dropbear firewall4 fitblk fstools kmod-crypto-hw-safexcel kmod-gpio-button-hotplug kmod-leds-gpio kmod-nf-nathelper kmod-nft-offload libc libgcc libustream-openssl logd luci mtd netifd nftables odhcp6c odhcpd-ipv6only ppp ppp-mod-pppoe procd-ujail uboot-envtools uci uclient-fetch urandom-seed urngd wpad-openssl kmod-usb3 kmod-mt7915e kmod-mt7981-firmware mt7981-wo-firmware automount bitsrunlogin-go luci-app-bitsrunlogin-go luci-i18n-bitsrunlogin-go-zh-cn luci-theme-argon luci-i18n-argon-config-zh-cn luci-app-argon-config

ImmortalWrt 自定义预安装软件和首次启动脚本页面

我没有自定义首次启动脚本的需求，所以脚本区域保持为空。配置完成后点击“请求构建”。页面会显示请求位于构建队列中。

ImmortalWrt 自定义镜像请求位于构建队列中

等待构建完成后，页面会出现下载入口。

ImmortalWrt 自定义镜像构建成功

我下载到的文件名类似：

1
immortalwrt-25.12.1-17179a901f8d-mediatek-filogic-cudy_tr3000-256mb-v1-squashfs-sysupgrade.bin

实际文件名应以页面当天生成的结果为准，不要手动猜测或改写中间的构建标识。

第五步：刷入自定义镜像#

自定义镜像下载完成后，再次进入 ImmortalWrt 的管理页面。系统一般可以通过下面两个地址访问：

1
http://192.168.1.1
2
http://immortalwrt.lan

先登录管理界面。

自定义 ImmortalWrt 镜像的登录界面

进入系统后确认当前仍然是 ImmortalWrt。

自定义镜像进入后的系统界面

按照前面相同的路径进入“系统 → 备份与升级”，上传自定义 sysupgrade 文件。

上传 ImmortalWrt 自定义 sysupgrade 镜像

同样取消勾选“保留设置并继续使用当前配置”，点击“继续”，等待路由器完成重启。这样做的目的仍然是避免把上一套镜像的配置直接带进新的软件包集合。

第六步：用 TFTP 恢复 Cudy 官方固件#

TFTP 可以理解成一个非常朴素的局域网文件传输方式：路由器启动时主动向电脑请求一个固定名字的文件。它不像网页上传那样由浏览器发起，而是由路由器的 bootloader 在恢复模式中发起请求。

这次恢复使用 Cudy 官方固件，不是把 ImmortalWrt 通过 TFTP 刷回去。根据 Cudy 官方恢复说明，我使用 Tftpd64 提供恢复文件。

准备官方恢复镜像#

从 Cudy TR3000 官方下载页面下载官方固件。本文操作时看到的最新版本是 2.5.21，文件名为：

1
m_upgrade_TR3000_256MB_Flash-R103-2.5.21-20260708-181324-sysupgrade_81571.zip

解压后找到 .bin 文件，将它重命名为：

1
recovery.bin

我把它放在：

1
E:\Documents\cudy_tr3000-256mb_v1\official

实际路径可以不同，但后面的 Tftpd64 根目录必须指向这个文件所在的目录。

配置电脑网卡和防火墙#

用网线连接路由器 LAN 口和电脑。在 Windows 网卡 IPv4 设置中手动填写：

项目	值
IP 地址	`192.168.1.88`
子网掩码	`255.255.255.0`
默认网关	留空
DNS	留空

Windows 网卡 IPv4 静态地址配置为 192.168.1.88

为了让 TFTP 请求不被 Windows 拦截，我临时关闭了专用网络和公用网络防火墙。这里只建议在恢复期间短暂关闭，恢复完成后立即重新开启。

Windows 安全中心中临时关闭专用网络防火墙

配置 Tftpd64#

Tftpd64 可以从 GitHub Releases 下载。如果使用 Scoop，也可以安装 extras 仓库里的 tftpd：

1
scoop install tftpd

打开 Tftpd64 后，设置正确的 Current Directory，也就是包含 recovery.bin 的目录，再选择电脑当前使用的 192.168.1.88 网卡。

Tftpd64 的根目录和网卡配置界面

点击“Show Dir”，确认目录列表中确实出现 recovery.bin。如果这里看不到文件，先修正目录，不要继续操作路由器。

Tftpd64 Show Dir 显示 recovery.bin

触发官方恢复#

关闭路由器电源。
按住路由器侧面的 RESET 键不松手。
插入 USB-C 电源。
等待 Tftpd64 界面出现文件传输。
确认开始传输后再松开 RESET 键。

Tftpd64 正在向路由器传输 recovery.bin

TFTP 传输完成不代表恢复已经完成。bootloader 还需要校验镜像，并把内容写入 Flash。传输结束后不要断电，等待路由器自动重启。我这次观察到通常在一分钟以内完成重启。

恢复完成后，指示灯常亮红色。把电脑网卡 IPv4 改回自动获取，并重新开启 Windows 专用网络和公用网络防火墙，然后访问：

1
http://192.168.10.1

恢复完成后进入 Cudy 官方固件页面，版本为 2.5.21

页面底部显示固件版本已经回到 2.5.21，这就是我判断官方固件恢复成功的依据。

我最后留下的检查点#

这次流程没有命令行，也没有改动 bootloader。我的检查点只有几个：

标签明确写着 256 MB 闪存版。
原厂系统地址是 192.168.10.1。
中间固件启动后地址变成 192.168.1.1。
中间固件使用 cudy_tr3000-256mb-v1-sysupgrade.bin。
ImmortalWrt Selector 使用 cudy_tr3000-256mb-v1。
目标镜像选择 SYSUPGRADE，不是 KERNEL。
刷写 ImmortalWrt 时取消保留旧配置。
TFTP 恢复使用官方 R103 固件，并重命名为 recovery.bin。
TFTP 传输完成后继续等待，不能立即断电。
恢复成功后，官方固件页面显示版本 2.5.21。

从 2025 年 9 月的第一台，到 2026 年 8 月的第二台，我对这个小路由器的结论没有变：硬件本身并不神秘，真正容易出错的是文件分支和等待时间。选错一次文件，或者在传输完成后过早拔电，都会把一个图形化流程变成维修流程。前者是判断题，后者是耐心题，路由器对此一视同仁。

参考资料#

Cudy 官方 OpenWrt 软件和中间固件下载说明，256 MB 中间固件下载入口。
Cudy TR3000 官方下载页面，官方固件和恢复镜像。
Cudy 官方从 OpenWrt 恢复官方固件说明，TFTP 恢复流程。
ImmortalWrt Firmware Selector，选择 cudy_tr3000-256mb-v1 和 SYSUPGRADE 镜像。
Tftpd64 Releases，Windows TFTP 服务端下载地址。
OpenWrt Wiki：Cudy TR3000，设备支持背景和原厂恢复风险说明。

从暂停到理解：GDB 调试完整实践

Tue, 25 Aug 2026 12:00:00 GMT

我一直觉得 GDB 很重要，但以前真正遇到崩溃时，第一反应还是加几行 std::cout。这多少有点像给发动机贴便利贴来寻找异响，所以我决定做一个小实验：写一个可以编译、可以运行、故意有两个错误的 C++ 程序，然后只用 GDB 观察它如何执行、在哪里偏离预期，以及它为什么最终崩溃。

这篇文章不是命令字典。我会从一个实际的 artifact 出发，边运行边解释 GDB 如何暂停、观察、改变并继续一个进程。我的环境是 GNU GDB 17.2 和 GCC 15.3.0；命令在 GDB 13/14 上大概率也成立，但线程、TUI、系统调用捕获和反向执行都可能受到平台限制。

先造一个可以被调试的程序#

我把下面的文件保存为 gdb_demo.cpp。它有四个刻意保留的观察点：动态 vector、递归求和、两个受互斥锁保护的线程，以及通过 --crash 参数触发的空指针解引用。

1
#include <iostream>
2
#include <mutex>
3
#include <thread>
4
#include <vector>
5

6
int recursive_sum(const std::vector<int>& values, std::size_t index) {
7
    if (index == values.size()) {
8
        return 0;
9
    }
10
    return values[index] + recursive_sum(values, index + 1);
11
}
12

13
void worker(int& counter, std::mutex& mutex) {
14
    for (int i = 0; i < 1000; ++i) {
15
        std::lock_guard<std::mutex> lock(mutex);
16
        ++counter;
17
    }
18
}
19

20
int main(int argc, char* argv[]) {
21
    const bool crash = argc > 1 && std::string(argv[1]) == "--crash";
22
    std::vector<int> values{3, 5, 7, 9};
23
    const int total = recursive_sum(values, 0);
24
    const double average = static_cast<double>(total) / (values.size() - 1);
25

26
    std::cout << "total=" << total << ", average=" << average
27
              << ", expected_average=6\n";
28

29
    int counter = 0;
30
    std::mutex mutex;
31
    std::thread first(worker, std::ref(counter), std::ref(mutex));
32
    std::thread second(worker, std::ref(counter), std::ref(mutex));
33
    first.join();
34
    second.join();
35
    std::cout << "counter=" << counter << "\n";
36

37
    if (crash) {
38
        int* pointer = nullptr;
39
        std::cout << "about to dereference a null pointer\n";
40
        std::cout << *pointer << "\n";
41
    }
42
}

展开收起

我先用可调试构建编译它：

Terminal window

1
g++ -std=c++20 -g3 -O0 -fno-omit-frame-pointer -Wall -Wextra \
2
    -o gdb_demo gdb_demo.cpp

-g3 把源码、变量和宏等调试信息写进可执行文件；-O0 关闭优化，让源码行和实际执行顺序尽量保持直觉；-fno-omit-frame-pointer 保留帧指针，便于调用栈和低层检查。这里的 -Wall -Wextra 是编译器警告，不是 GDB 功能，但我希望在程序进入调试器前先消灭显眼的问题。

正常运行得到：

1
total=24, average=8, expected_average=6
2
counter=2000

3 + 5 + 7 + 9 = 24，两个线程各自增加 1000 次，所以 counter=2000 是稳定结果。平均值却是 8，而我写在输出里的期望值是 6。错误就在 values.size() - 1，应该除以 values.size()。这是一种 GDB 很擅长处理的问题：程序没有崩溃，编译器也没有理由报警，但状态已经错了。

加上参数后，程序会进入另一条路径：

1
about to dereference a null pointer
2
Segmentation fault

第一次完整调试：暂停，观察，继续#

启动 GDB 的命令属于 Shell，不属于 GDB：

Terminal window

1
gdb ./gdb_demo

看到 (gdb) 之后，才进入 GDB 命令语言。程序自己的标准输入则是第三种东西，例如程序调用 std::cin 时，输入才会被程序读取，而不会自动变成 GDB 命令。这个边界一开始很容易混淆，我也混淆过（把 run 输入成程序参数，结果得到了一次相当安静的失败）。

我先走一遍最短路径：

1
(gdb) break main
2
(gdb) run
3
(gdb) next
4
(gdb) step
5
(gdb) print values
6
(gdb) continue
7
(gdb) backtrace
8
(gdb) quit

break main 在 main 入口设置断点，run 启动程序并停在那里，next 执行当前源码行但跳过被调用函数，step 则进入函数。print 读取当前上下文中的表达式，continue 继续运行到下一个断点或信号，backtrace 打印调用栈，quit 退出。

断点像给程序安装一个可控的闸门。进程跑到闸门前暂停，我可以查看货物，也可以决定放行、改变一件货物，甚至把它送回另一条轨道。类比到这里就够了，后面我会直接使用 GDB 的术语。

符号为什么重要#

编译器最终生成的是机器指令，CPU 并不知道 main 或 average 这些名字。-g3 让可执行文件额外携带符号表、源码文件、行号和变量位置，GDB 才能把某个指令地址映射回 gdb_demo.cpp:24。

没有调试信息时，GDB 仍然可以停在地址、查看寄存器和反汇编，但你会失去大部分源码级语义：

1
(gdb) file ./gdb_demo_without_debug_info
2
(gdb) break main
3
No symbol table is loaded.  Use the "file" command.

按调试任务使用断点#

我通常先问：程序应该在哪些位置停下来？

1
(gdb) break main
2
(gdb) break recursive_sum
3
(gdb) break gdb_demo.cpp:24
4
(gdb) break gdb_demo.cpp:24 if values.size() != 4
5
(gdb) rbreak worker.*
6
(gdb) tbreak gdb_demo.cpp:40
7
(gdb) info breakpoints
8
(gdb) disable 2
9
(gdb) enable 2
10
(gdb) clear gdb_demo.cpp:24
11
(gdb) delete 1

break 可以按函数、文件和行号设置，也可以附加条件。rbreak 接受正则表达式，tbreak 只命中一次。每个断点都有编号，info breakpoints 显示位置、启用状态和命中次数；这个实验中 recursive_sum 会递归进入 5 个栈帧，但条件断点只在满足条件的那一帧停下。

如果我在共享库加载前设置断点，GDB 可能显示：

1
Breakpoint 3 (some_library_function) pending.

这不是命中。它表示 GDB 暂时找不到符号，等目标共享库加载后再尝试解析。可以用 set breakpoint pending on 明确允许这种行为，再用 info sharedlibrary 检查库是否已加载。

clear 按源码位置清理，delete 按断点编号删除，disable 只暂时关闭。调试一个复杂程序时，我更常用 disable，因为保留编号和条件比重新设置更少出错。

控制执行：不要把程序当成黑盒#

这些命令的区别值得单独记住：

run 从头启动；可以写成 run --crash。
start 在 main 的第一行附近停下，适合快速检查参数。
starti 从第一条机器指令开始，适合研究启动代码。
continue 放行直到下一个断点、信号或退出。
next 执行当前源码行，不进入函数。
step 执行当前源码行，并进入函数。
finish 运行到当前函数返回，并显示返回值。
until 30 运行到当前函数中的指定行或更高层位置。
advance gdb_demo.cpp:35 运行到指定位置，不会倒退控制流。
jump gdb_demo.cpp:30 直接改变下一条源码位置，可能跳过初始化。
return 强制当前函数返回，可附加返回值。
signal SIGINT 把信号交给被调试程序。

jump 和 return 不是修复代码。它们是实验工具，用来回答如果跳过某个分支会发生什么；跳过构造函数、析构函数或锁操作很容易破坏程序状态。我只在已经知道风险的局部现场使用它们。

栈帧：递归时我到底在看谁#

程序每调用一个函数，通常就产生一个栈帧。递归调用 recursive_sum 时，4 个元素会产生 4 个非终止调用帧，再加上终止帧和 main，所以我可以观察到 6 层相关上下文。

1
(gdb) break recursive_sum
2
(gdb) run
3
(gdb) backtrace
4
(gdb) frame 2
5
(gdb) info frame
6
(gdb) info args
7
(gdb) info locals
8
(gdb) up
9
(gdb) down

backtrace 或 bt 从当前帧向调用者打印；frame 2 直接切换到编号为 2 的帧；up 和 down 在调用者与被调用者之间移动。关键点是：print index 读取的是当前 frame 的 index，不是我脑中刚才那个递归层级的 index。

崩溃路径的命令更加直接：

1
(gdb) set args --crash
2
(gdb) run
3
(gdb) bt
4
(gdb) bt full
5
(gdb) frame 0
6
(gdb) print pointer

本次崩溃稳定停在 gdb_demo.cpp:40，pointer 的值是 0x0。地址本身依赖运行环境，语义不依赖：当前线程在解引用空指针。

数据和表达式：让 GDB 替我问问题#

1
(gdb) print total
2
(gdb) p average
3
(gdb) display total
4
(gdb) display /x total
5
(gdb) undisplay 1
6
(gdb) ptype values
7
(gdb) whatis values
8
(gdb) set print pretty on
9
(gdb) set print elements 20
10
(gdb) print values[2]
11
(gdb) print values.data()
12
(gdb) print *values.data()

print 可以求 C++ 表达式。display 会在每次停下时自动打印，适合观察循环变量；ptype 展开类型定义，whatis 给出更短的类型名。对 vector、结构体和嵌套对象，set print pretty on 通常更容易阅读。

我在第 24 行设置断点后，可以确认 total 已经是 24，而 average 尚未完成初始化。此时打印未初始化的局部变量得到垃圾值不是 GDB 出错，而是程序还没有给它一个有效值。继续到下一行后再打印，才会看到 average=8。

表达式也可以带类型转换：

1
(gdb) print (long) counter
2
(gdb) print (double) total / values.size()

调用函数要谨慎。print some_function() 可能修改全局状态、推进迭代器、申请内存或拿锁。GDB 正在观察程序时替我调用函数，结果可能比原始执行更复杂，我优先读取变量和内存。

内存、寄存器和汇编#

x/nfu address 中，n 是数量，f 是格式，u 是单位。例如：

1
(gdb) x/4dw values.data()
2
(gdb) x/16xb values.data()
3
(gdb) x/s pointer
4
(gdb) x/i $pc
5
(gdb) info registers
6
(gdb) disassemble /m recursive_sum
7
(gdb) disassemble /r main

x/4dw 按十进制 word 查看 4 个单元，x/16xb 按十六进制 byte 查看 16 个字节，x/s 把地址解释为字符串，x/i $pc 查看程序计数器当前位置的指令。info registers 显示寄存器，$pc 是当前指令地址，$sp 指向当前栈顶，$fp 在保留帧指针的构建中帮助定位当前栈帧。

disassemble /m 尝试把源码行和机器指令混排，disassemble /r 附带原始机器字节。也可以使用：

1
(gdb) layout asm

这时我看到的不是 C++，而是编译器为 C++ 选择的实际指令。源码的第 24 行可能对应多条指令，单步时也可能在同一行内移动。GDB 是源码和 CPU 状态之间的显微镜，不是源码执行动画播放器。

改变状态：有时我需要一个反事实#

1
(gdb) set variable average = 6
2
(gdb) set variable counter = 0
3
(gdb) set $expected = 6
4
(gdb) print $expected
5
(gdb) set $pc = *some_address
6
(gdb) set $rax = 0

set variable 修改程序变量，$expected 是 GDB convenience variable，修改寄存器则直接影响后续机器指令。它们适合验证假设：如果平均值已经是 6，后续分支是否还会失败？某个寄存器清零后，崩溃位置是否变化？

这不是源代码修复。类型不匹配、越界写入、跳过锁和破坏对象不变量，都可能制造新的假象。实验结束后我会重新启动进程，而不是把被 GDB 改过的状态当成测试结果。

watchpoint：捕获变化，而不是猜行号#

1
(gdb) break worker
2
(gdb) run
3
(gdb) watch counter
4
(gdb) rwatch counter
5
(gdb) awatch counter
6
(gdb) info watchpoints

watch 在表达式写入后停下，rwatch 在读取后停下，awatch 在读取或写入后停下。对简单标量，GDB 大概率使用硬件 watchpoint；硬件寄存器数量有限，复杂表达式和大范围内存可能无法使用。

线程版本中 counter 最终从 0 变化到 2000。因为我用 std::mutex 保护了自增，结果稳定；普通断点只能说明某个线程停过，不能证明不存在数据竞争。要调查竞争，我会结合 info threads、thread apply all bt，再使用 ThreadSanitizer 等专门工具，而不是把 GDB 当成竞态检测器。

异常和系统事件也可以捕获，但能力依赖平台：

1
(gdb) catch throw
2
(gdb) catch signal SIGSEGV
3
(gdb) catch syscall write
4
(gdb) handle SIGPIPE nostop noprint pass

catch throw 对 C++ 异常很有用；catch syscall 只在目标架构和 GDB 支持的系统调用接口上可用。handle 控制信号到达时 GDB 是否暂停、打印以及是否传递给程序。不要把某个平台上的 catchpoint 行为写成所有 Linux、BSD 和嵌入式目标都相同。

参数、环境、线程与崩溃文件#

从命令行复现问题时，我会把参数显式放进调试会话：

1
(gdb) set args --crash
2
(gdb) show args
3
(gdb) set environment MODE debug
4
(gdb) show environment MODE
5
(gdb) run

也可以在 Shell 中使用重定向：

Terminal window

1
echo "input" > input.txt
2
gdb --args ./gdb_demo --crash
3
(gdb) run < input.txt

线程调试的最小工作流如下：

1
(gdb) info threads
2
(gdb) thread 2
3
(gdb) bt
4
(gdb) thread apply all bt
5
(gdb) break worker
6
(gdb) continue

断点可能停在任意命中断点的线程。先看 info threads，再用 thread 切换，最后用 frame、info locals 检查那个线程的上下文。线程 ID 是运行时生成的，不应写进教程的固定结论。

如果程序产生 core 文件，可以脱离原始运行现场：

Terminal window

1
gdb ./gdb_demo core

或者在 GDB 中：

1
(gdb) core-file core
2
(gdb) bt full
3
(gdb) info registers
4
(gdb) x/16gx $sp

可执行文件、core 和调试符号必须匹配。换过二进制后继续解释旧 core，得到的行号和变量很可能完全不可信。

子进程、共享库和远程目标#

调试共享库先确认加载状态：

1
(gdb) info sharedlibrary
2
(gdb) set breakpoint pending on
3
(gdb) break library_function

程序 fork 后，GDB 默认行为可以调整：

1
(gdb) set follow-fork-mode child
2
(gdb) set detach-on-fork off
3
(gdb) info inferiors
4
(gdb) inferior 2

follow-fork-mode 决定跟随父进程还是子进程，detach-on-fork off 保留两个 inferior，代价是调试状态更复杂。

远程调试需要目标端有 gdbserver、网络连通和权限允许。最小流程是：

Terminal window

1
# 目标机
2
gdbserver :1234 ./gdb_demo --crash
3

4
# 主机
5
gdb ./gdb_demo
6
(gdb) target remote TARGET_HOST:1234
7
(gdb) continue

远程 GDB 不是把本地文件复制过去；主机上的符号和目标机上的实际可执行文件、库、架构必须对应。端口、防火墙、路径映射和权限都是前置条件，我不会把这条命令伪装成离线环境中的必然成功路径。

优化构建为什么会和源码吵架#

确认逻辑后，我再编译优化版本：

Terminal window

1
g++ -std=c++20 -g3 -O2 -fno-omit-frame-pointer -Wall -Wextra \
2
    -o gdb_demo_O2 gdb_demo.cpp

-O2 可能内联 recursive_sum、合并变量、改变生命周期和重排指令。于是 GDB 可能显示：

1
(gdb) print some_local
2
$1 = <optimized out>

也可能出现源码行跳跃、多个变量共享一个寄存器，或者断点虽然设置成功却没有在我预期的行停下。这不是调试器随机失忆，而是编译器已经改变了程序的机器级形状。

我的流程是：先用 -O0 -g3 复现和定位，再用 -O2 -g3 确认优化环境中的行为。如果只在优化版本崩溃，优先保存 core、检查汇编和寄存器，不要为了让 GDB 显示漂亮变量而误称 -O0 的结果代表生产环境。

TUI、命令脚本和一点自动化#

终端界面可以把源码、汇编和寄存器放在同一屏：

1
(gdb) layout src
2
(gdb) layout split
3
(gdb) layout regs
4
(gdb) focus cmd
5
(gdb) refresh

窗口布局只改变显示，不改变被调试程序。退出 TUI 可以按 Ctrl-x Ctrl-a。

重复操作适合放进脚本，例如 debug.gdb：

1
set pagination off
2
set print pretty on
3
break main
4
commands
5
  silent
6
  printf "stopped in main, argc=%d\n", argc
7
  info locals
8
  continue
9
end
10
run

执行：

1
(gdb) source debug.gdb

我也可以在 ~/.gdbinit 中放通用设置，或定义一个小命令：

1
def btfull
2
  set pagination off
3
  thread apply all bt full
4
end

GDB 支持 Python API，可以访问 inferior、断点和事件对象。但我把它留在自动化边界内：先用 source 和 define 解决 80% 的重复操作，只有当重复逻辑确实需要状态管理时才写 Python。调试器已经够复杂了，没必要为了打印一行栈信息再造一个框架。

记录与反向执行#

在支持的本地目标上，我可以尝试：

1
(gdb) record full
2
(gdb) continue
3
(gdb) reverse-step
4
(gdb) reverse-continue
5
(gdb) record stop

它通过记录执行状态，让我在某个错误发生后反向回到之前的指令。代价是额外的时间、内存和记录存储；系统调用、设备访问、线程和某些架构并不都能被完整重放。它不是所有程序都适用的时间机器，尤其不是网络服务的万能撤销按钮。

一张按任务分组的功能地图#

任务	常用命令	最短用途
运行控制	`run`, `start`, `starti`	启动并选择初始停点
继续执行	`continue`, `next`, `step`	放行、越过或进入函数
改变流程	`finish`, `until`, `advance`	运行到返回或指定位置
实验跳转	`jump`, `return`, `signal`	改变下一步、强制返回、发送信号
断点	`break`, `rbreak`, `tbreak`	按函数、正则或位置暂停
断点管理	`info breakpoints`, `clear`, `delete`, `disable`, `enable`	查看和管理断点
数据	`print`, `display`, `ptype`, `whatis`	求表达式、自动显示、查看类型
栈	`bt`, `frame`, `up`, `down`, `info frame`	查看和切换调用上下文
局部状态	`info locals`, `info args`	查看当前帧变量和参数
内存	`x`, `find`	按格式查看或搜索内存
CPU	`info registers`, `disassemble`	检查寄存器和机器指令
改状态	`set variable`, `set $name`	修改变量或 GDB 便利变量
变化捕获	`watch`, `rwatch`, `awatch`	在读写发生时暂停
异常信号	`catch throw`, `catch signal`, `handle`	捕获异常和信号
系统调用	`catch syscall`	在支持的平台捕获系统调用
线程	`info threads`, `thread`, `thread apply all bt`	列出、切换和批量查看线程
进程	`set follow-fork-mode`, `set detach-on-fork`, `info inferiors`	控制 fork 后的跟随对象
共享库	`info sharedlibrary`, `set breakpoint pending on`	检查库和延迟断点
远程	`target remote`	连接 `gdbserver`
TUI	`layout src`, `layout split`, `layout regs`, `focus`	查看源码、汇编和寄存器
自动化	`source`, `define`, `commands`	加载脚本和定义命令
反向	`record full`, `reverse-step`, `reverse-continue`	在记录数据中回退执行

这张表把日常源码调试能力串起来，但不把架构专用命令、IDE 前端、Valgrind 或 AddressSanitizer 冒充成 GDB 功能。它们可以协作，边界仍然存在。

常见故障排查#

症状	大概率原因	先执行什么
`No symbol table is loaded`	没有 `-g`，或加载了错误文件	`file ./gdb_demo`
`Breakpoint pending`	共享库尚未加载或符号名不匹配	`info sharedlibrary`
`Cannot access memory`	地址无效、对象已释放或当前 frame 不对	`info registers`、`frame 0`
`<optimized out>`	优化消除了变量或改变了生命周期	用 `-O0 -g3` 重建
程序直接退出	没有断点，或断点位置不在实际路径	`start`、`break main`
断点不命中	行没有生成可执行代码、条件不成立或库未加载	`info breakpoints`
`print` 看起来不对	当前停在错误的栈帧或变量尚未初始化	`bt`、`frame`、`info locals`

我把“断点不命中”分成状态问题而不是玄学问题。先看断点编号、启用状态和命中次数，再确认控制流是否真的经过那里；不要一上来就重新编译十次，然后把所有的不确定性归咎于 GDB（虽然这样做有一种很强的仪式感）。

我把第 24 行改成下面这样，再重新编译，而不是在 GDB 里永久修改变量：

1
const double average = static_cast<double>(total) / values.size();

修正后的稳定输出是：

1
total=24, average=6, expected_average=6
2
counter=2000

这两个版本的线程计数相同，只有平均值从 8 变成 6。这正是我想要的调试闭环：GDB 帮我定位原因，源代码和编译器才负责产生修复后的程序。

我以后会怎样使用 GDB#

这次实验里，错误平均值从输出中的 8 追到了第 24 行，线程计数从 0 走到了稳定的 2000，崩溃则被定位到空指针解引用的第 40 行。真正改变我习惯的不是记住了多少命令，而是把调试变成一个循环：提出一个关于状态的猜测，设置最窄的停点，观察证据，再决定是否继续。

以后我会先保留一个带 -g3 -O0 的可调试构建，把 gdb ./program 当成和 ./program 一样自然的动作。等程序在优化、线程或远程机器上表现不同，我再逐层打开 info threads、寄存器、汇编和记录功能，而不是继续往代码里撒 printf。

再往前看，调试器大概不会消失。编译器会更激进，异步任务会更多，机器学习生成的代码也会让源码与机器指令之间的距离继续变长。能暂停一个进程只是起点，真正有价值的是保留一条从现象到状态、从状态到原因的证据链。好的调试工具会缩短这条链；好的调试习惯则让我在按下 run 之前，已经知道自己准备验证什么。

现在我可以删掉这个实验里的错误，重新编译，然后去吃点东西。GDB 不会替我修复 values.size() - 1，它只是非常耐心地证明我确实写错了。

LaTeX 项目结构与 latexmk 配置

Thu, 18 Jun 2026 03:20:00 GMT

目录结构#

Terminal window

1
C:.
2
│  .gitignore
3
│  .latexmkrc
4
│  LICENSE
5
│  main.tex
6
│  refs.bib
7
│
8
├─contents
9
├─docs
10
├─figs
11
└─settings
12
    format.tex
13
    packages.tex

main.tex：入口文件，只负责把各部分拼起来。
refs.bib：参考文献数据库。用 BibTeX 格式存储文献条目，正文里用 \cite{key} 引用。配合 biblatex 使用时，在 format.tex 里用 \addbibresource{refs.bib} 指定路径。
contents/：章节内容，按章（book/report 类）或按节（article 类）建子文件夹。
figs/：图片资源。配合 \graphicspath{{figs/}} 使用，正文里直接写文件名就行。
docs/：项目文档，比如编译好的 PDF、使用说明等。
settings/packages.tex：宏包导入。
settings/format.tex：格式配置（页面布局、标题样式、字体等）。
.latexmkrc：latexmk 的编译配置，后面会详细讲。
.gitignore：LaTeX 项目的忽略模板可以参考 github/gitignore/TeX.gitignore。注意官方模板里没有 build/ 目录，如果你像我一样把编译产物输出到 build/，记得手动加上。

packages.tex 和 format.tex 的最小示例：

1
% settings/packages.tex -- 只管导入，不管配置
2
\usepackage{fontspec}
3
\usepackage{xeCJK}
4
\usepackage{geometry}
5
\usepackage{fancyhdr}
6
\usepackage{amsmath}
7
\usepackage{amssymb}
8
\usepackage{amsfonts}
9
\usepackage{mathtools}
10
\usepackage{graphicx}
11
\usepackage{tabularray}
12
\usepackage{subcaption}
13
\usepackage{listings}
14
\usepackage{enumitem}
15
\usepackage{siunitx}
16
\usepackage[backend=biber, style=gb7714-2015]{biblatex}
17
\usepackage[colorlinks=true, linkcolor=blue, citecolor=blue, urlcolor=blue]{hyperref}
18
\usepackage[capitalise]{cleveref}

展开收起

1
% settings/format.tex -- 字体、布局、宏包的后续配置
2
\setmainfont{TeX Gyre Termes}
3
\setsansfont{TeX Gyre Heros}
4
\setmonofont{TeX Gyre Cursor}
5
\setCJKmainfont{Source Han Serif SC}
6
\setCJKsansfont{Source Han Sans SC}
7
\setCJKmonofont{Source Han Mono SC}
8

9
\geometry{a4paper, margin=2.5cm}
10

11
\pagestyle{fancy}
12
\fancyhf{}
13
\fancyhead[L]{\leftmark}
14
\fancyfoot[C]{\thepage}
15
\renewcommand{\headrulewidth}{0.4pt}
16

17
\UseTblrLibrary{booktabs, siunitx}
18

19
\graphicspath{{figs/}}
20
\sisetup{range-phrase=\ensuremath{\sim}, range-units=single}
21
\addbibresource{refs.bib}
22

23
% tabularray 常用全局设置
24
\SetTblrStyle{firsthead}{font=\bfseries}
25
\SetTblrStyle{firstfoot}{font=\small}
26
\SetTblrStyle{middlefoot}{font=\small}
27
\SetTblrStyle{lastfoot}{font=\small}

展开收起

实际使用时按需增减。宏包的加载顺序有讲究，后面”常用宏包”一节会说明。

`main.tex` 模板#

`book` 类#

1
\documentclass{book}
2

3
\input{settings/packages}
4
\input{settings/format}
5

6
\begin{document}
7

8
\maketitle
9
\frontmatter
10

11
\tableofcontents
12

13
\mainmatter
14

15
% \input{contents/chap_01}
16

17
\appendix
18
% \input{contents/appendix}
19

20
\backmatter
21

22
\end{document}

展开收起

`article` 类#

1
\documentclass{article}
2

3
\input{settings/packages}
4
\input{settings/format}
5

6
\begin{document}
7

8
\maketitle
9

10
\tableofcontents
11

12
% \input{contents/sec_01}
13

14
\appendix
15
% \input{contents/appendix}
16

17
\end{document}

展开收起

`report` 类#

1
\documentclass{report}
2

3
\input{settings/packages}
4
\input{settings/format}
5

6
\begin{document}
7

8
\maketitle
9

10
\tableofcontents
11

12
% \input{contents/chap_01}
13

14
\appendix
15
% \input{contents/appendix}
16

17
\end{document}

展开收起

三者差在哪#

	`article`	`report`	`book`
最高章节	`\section`	`\chapter`	`\chapter`
默认排版	单面	单面	双面
标题页	正文内	独立一页	独立一页
`\frontmatter` / `\backmatter`	无	无	有
典型用途	短文、笔记、报告	课程报告、毕业论文	书籍、学位论文

report 和 book 都有 \chapter，区别主要在排版方式和文档结构命令。book 多了 \frontmatter、\mainmatter、\backmatter，默认双面排版，适合正式出版物。report 默认单面，没有前言/正文/后记的划分，适合不需要装订的长文档。

article 没有 \chapter，从 \section 开始。写短文、笔记够用了。

三者的标题页也不同。book 和 report 的 \maketitle 都是独立一页，article 的只是在正文开头插一行。

工具简介#

在看 .latexmkrc 之前，先简单介绍一下涉及的几个工具。

XeLaTeX

LaTeX 的编译引擎之一。相比传统的 pdfLaTeX，XeLaTeX 原生支持 Unicode 和系统字体（通过 fontspec），处理中文要方便得多。如果你主要写中文文档，XeLaTeX（或 LuaLaTeX）基本是必选的。

latexmk

一个 Perl 写的自动化编译工具。LaTeX 的编译经常需要跑多遍（交叉引用、目录、参考文献），手动执行很烦。latexmk 会自动判断需要跑几遍、要不要调用 BibTeX/Biber，直到所有引用都稳定为止。配合 -pvc 参数还能监控文件变化，保存即编译。

BibTeX 和 Biber

两者都是处理参考文献的工具。BibTeX 是老方案，Biber 是配合 biblatex 宏包的新方案，功能更强（支持 Unicode、更灵活的样式定制）。latexmk 的 $bibtex_use = 2 会自动检测你用的是哪个，不用手动切换。

SyncTeX

在编辑器和 PDF 阅读器之间做双向跳转的数据格式。加了 -synctex=1 之后，你可以在编辑器里点一个位置，PDF 阅读器自动翻到对应页面，反过来也行。

`.latexmkrc`#

1
# 主文件
2
$root = 'main.tex';
3

4
# 输出目录
5
$out_dir = 'build';
6
$aux_dir = 'build';
7

8
# 编译引擎: XeLaTeX
9
$pdf_mode = 5;
10
$xelatex = 'xelatex -interaction=nonstopmode -file-line-error -synctex=1 %O %S';
11

12
# 自动运行 BibTeX 或 Biber
13
$bibtex_use = 2;
14

15
# 清理时保留 PDF
16
$clean_ext = 'aux bbl bcf blg fdb_latexmk fls log out run.xml synctex.gz toc';
17

18
# 跨平台 PDF 预览器
19
if ($^O eq 'MSWin32') {
20
    $pdf_previewer = 'start %S';
21
} elsif ($^O eq 'darwin') {
22
    $pdf_previewer = 'open %S';
23
} else {
24
    $pdf_previewer = 'xdg-open %S 2>/dev/null || evince %S';
25
}
26

27
# Windows 下清理时不删除被占用的文件
28
if ($^O eq 'MSWin32') {
29
    $cleanup_includes_generated = 0;
30
}
31

32
# 自定义依赖示例（取消注释即可用）
33
# add_cus_dep('glo', 'gls', 0, 'makeglos');
34
# sub makeglos {
35
#     system("makeindex -s $_[0].ist -t $_[0].glg -o $_[0].gls $_[0].glo");
36
# }

展开收起

逐项说明#

$root：主文件名。latexmk 从这里开始分析依赖。改成你的实际文件名就行。
$out_dir / $aux_dir：编译产物放哪。设成 build 能让根目录干净一些，PDF 会出现在 build/main.pdf。记得在 .gitignore 里加上 build/。
$pdf_mode：选择编译引擎。1 是 pdfLaTeX，4 是 LuaLaTeX，5 是 XeLaTeX。
$xelatex：XeLaTeX 的调用参数。-interaction=nonstopmode 让它遇到错误继续编译而不是停下来等你按回车；-file-line-error 让报错信息带上文件名和行号；-synctex=1 生成编辑器跳转用的数据。%O 和 %S 是 latexmk 的占位符，分别代表额外选项和源文件。
$bibtex_use：设为 2 就行，自动检测 BibTeX 还是 Biber。设为 0 关闭自动处理，1 只在 .bbl 已存在时才跑。
$clean_ext：latexmk -c 会删掉这些后缀的文件。PDF 不在里面，所以清理后 PDF 还在。注意区分 -c（清理中间文件，保留 PDF）和 -C（连 PDF 一起删），别手滑用了 -C。
跨平台预览器：Perl 的 $^O 变量存着操作系统类型：Windows 是 MSWin32，macOS 是 darwin，Linux 就是 linux。start、open、xdg-open 分别是三个平台打开文件的命令。%S 会被替换成 PDF 路径。配合 latexmk -pvc 使用，保存文件后自动编译并刷新 PDF 预览，不用手动跑命令。
$cleanup_includes_generated：Windows 上文件锁比较死板，latexmk 清理时可能删不掉正在被占用的文件。设为 0 可以避免这个问题。
自定义依赖：add_cus_dep 用来告诉 latexmk “如果某个 .glo 文件变了，要重新生成对应的 .gls”。示例里是术语表的场景，取消注释就能用。

常用宏包#

以下是写中文 LaTeX 文档时经常会用到的宏包，以及它们的典型配置。

加载顺序需要注意几点：fontspec 和 xeCJK 要在大多数宏包之前加载；amsmath 要在 mathtools 之前；tabularray 的 \UseTblrLibrary 要在 siunitx 之后（因为 siunitx 库需要 siunitx 已加载）；hyperref 几乎总是放在最后，唯一的例外是 cleveref，它必须在 hyperref 之后。上面 packages.tex 示例中的顺序可以直接用。

字体与编码#

fontspec

配合 XeLaTeX/LuaLaTeX 使用，用来设置系统字体。

1
\usepackage{fontspec}
2
\setmainfont{TeX Gyre Termes}          % 正文衬线字体
3
\setsansfont{TeX Gyre Heros}           % 无衬线字体
4
\setmonofont{TeX Gyre Cursor}          % 等宽字体

xeCJK

处理中文排版的核心宏包，自动处理中英文之间的间距、标点挤压等。

1
\usepackage{xeCJK}
2
\setCJKmainfont{Source Han Serif SC}   % 中文衬线（思源宋体）
3
\setCJKsansfont{Source Han Sans SC}    % 中文无衬线（思源黑体）
4
\setCJKmonofont{Source Han Mono SC}    % 中文等宽

页面布局#

geometry

控制页面尺寸和边距，比 LaTeX 默认的布局参数好用得多。

1
\usepackage[a4paper, margin=2.5cm]{geometry}
2
% 也可以精细控制
3
% \usepackage[a4paper, top=3cm, bottom=2.5cm, left=2.8cm, right=2.2cm]{geometry}

fancyhdr

自定义页眉页脚。

1
\usepackage{fancyhdr}
2
\pagestyle{fancy}
3
\fancyhf{}                             % 清空默认设置
4
\fancyhead[L]{\leftmark}               % 页眉左侧放章节名
5
\fancyfoot[C]{\thepage}                % 页脚中间放页码
6
\renewcommand{\headrulewidth}{0.4pt}   % 页眉横线粗细

数学与代码#

amsmath / amssymb / amsfonts

数学排版的基础三件套，基本上写公式就得用。

1
\usepackage{amsmath}
2
\usepackage{amssymb}
3
\usepackage{amsfonts}

mathtools

amsmath 的扩展包，修复了一些设计问题并增加了实用工具。

1
\usepackage{mathtools}
2
% 例如：可以给公式加编号标签
3
% \usetagform{default}

listings

排版代码块。支持语法高亮，可以指定语言和样式。

1
\usepackage{listings}
2
\lstset{
3
    basicstyle=\ttfamily\small,
4
    breaklines=true,
5
    frame=single,
6
    numbers=left,
7
    numberstyle=\tiny\color{gray},
8
    keywordstyle=\color{blue},
9
    commentstyle=\color{green!60!black},
10
    stringstyle=\color{red!70!black},
11
}

minted

基于 Pygments 的代码排版，高亮效果比 listings 好，但需要 Python 环境且编译时要加 -shell-escape。

1
\usepackage{minted}
2
% 使用示例：
3
% \begin{minted}{python}
4
% def hello():
5
%     print("world")
6
% \end{minted}

图表与浮动体#

graphicx

插入图片。

1
\usepackage{graphicx}
2
\graphicspath{{figs/}}                 % 指定图片搜索路径

tabularray

现代表格宏包，统一了表格的样式配置和内容分离。用 tblr 环境替代传统的 tabular，样式参数写在 \begin{tblr}{...} 的花括号里，正文和样式彻底分开。配合 booktabs 库可以使用 \toprule、\midrule、\bottomrule。

1
\usepackage{tabularray}
2
\UseTblrLibrary{booktabs, siunitx}
3
% \begin{table}
4
% \begin{tblr}{
5
%   colspec = {lrc},
6
%   row{1} = {font=\bfseries},
7
% }
8
%   \toprule
9
%   姓名 & 分数 & 等级 \\
10
%   \midrule
11
%   张三 & 95 & A \\
12
%   李四 & 82 & B \\
13
%   \bottomrule
14
% \end{tblr}
15
% \end{table}

展开收起

booktabs 库提供三线表的线条命令，siunitx 库让列可以用 S 类型对齐数字。tabularray 还支持 longtblr（跨页长表格）和 talltblr（不跨页但可加脚注的表格），基本覆盖了所有表格场景。

subcaption

在一个浮动体里放多张子图，每个子图独立编号和引用。

1
\usepackage{subcaption}
2
% \begin{figure}[htbp]
3
%   \begin{subfigure}{0.48\textwidth}
4
%     \includegraphics[width=\textwidth]{fig_a}
5
%     \caption{子图 A}
6
%   \end{subfigure}
7
%   \hfill
8
%   \begin{subfigure}{0.48\textwidth}
9
%     \includegraphics[width=\textwidth]{fig_b}
10
%     \caption{子图 B}
11
%   \end{subfigure}
12
%   \caption{总标题}
13
% \end{figure}

参考文献#

biblatex

现代的参考文献管理方案，配合 Biber 后端使用。比 BibTeX 灵活很多，支持多语言、多文献列表等。

1
\usepackage[backend=biber, style=gb7714-2015]{biblatex}
2
\addbibresource{refs.bib}              % 指定 .bib 文件
3
% 正文中用 \cite{key} 引用
4
% 文末用 \printbibliography 输出

style=gb7714-2015 是中文文献常用的国标样式，需要 biblatex-gb7714-2015 宏包。英文文档常用 style=ieee、style=apa 或 style=alphabetic。

hyperref

给交叉引用、目录、参考文献加上超链接。通常放在 \usepackage 的最后（少数例外，如 cleveref 要在 hyperref 之后）。

1
\usepackage[
2
    colorlinks=true,
3
    linkcolor=blue,
4
    citecolor=blue,
5
    urlcolor=blue,
6
]{hyperref}

其他实用工具#

ctex

如果不想手动配 xeCJK，直接用 ctex 宏包或 ctexart/ctexbook 文档类，一键搞定中文支持。

1
\usepackage[UTF8, heading=true]{ctex}
2
% 或者直接用 \documentclass{ctexart}

enumitem

定制列表环境（enumerate、itemize、description）的间距和标签样式。

1
\usepackage{enumitem}
2
\setlist{nosep}                        % 去掉列表的多余间距
3
% \begin{enumerate}[label=(\arabic*)]
4
%   \item 第一项
5
%   \item 第二项
6
% \end{enumerate}

tikz

画矢量图。学习曲线陡峭，但画出来的东西质量很高，跟 LaTeX 文档浑然一体。

1
\usepackage{tikz}
2
\usetikzlibrary{arrows.meta, positioning}
3
% 简单示例：画一个带箭头的直线
4
% \begin{tikzpicture}
5
%   \draw[->] (0,0) -- (2,1) node[right] {$y = x/2$};
6
% \end{tikzpicture}

siunitx

处理数值和单位的排版。数字的千分位、科学记数法、单位的正体和间距，它都能管。

1
\usepackage{siunitx}
2
\sisetup{
3
    range-phrase = \ensuremath{\sim},
4
    range-units = single,
5
}
6
% \qty{10}{\metre}           -> 10 m
7
% \qty{1.23e5}{\pascal}      -> 1.23 × 10⁵ Pa
8
% \qtyrange{1}{10}{\metre}   -> 1~10 m（单位只出现一次，用 ~ 连接）

range-units=single 让范围表达中单位只出现一次，而不是”1 m 到 10 m”。range-phrase 设成 \ensuremath{\sim} 把分隔符换成 ~（波浪号），\ensuremath 确保它在数学模式和文本模式下都能正确渲染。

cleveref

智能引用，自动加上”图""表""公式”等前缀，不用自己写 \ref{fig:xxx} 的图。注意要放在 hyperref 之后加载。

1
\usepackage[capitalise]{cleveref}
2
% 使用 \cref{fig:example} 会自动输出"图 1"
3
% \cref{eq:main,eq:sub} 会输出"公式 (1) 和 (2)"

设备树入门：从第一份 DTS 到 Linux 驱动匹配

Wed, 20 May 2026 03:15:00 GMT

我以前把设备树当成一堆需要背下来的属性名：compatible、reg、interrupts，还有几个看起来像预处理器产物的 #*-cells。后来我决定只做一件事：写一份足够小的 DTS，把它编译成 DTB，再从 Linux 看到它实际收到的内容。设备树一下从名词表变成了一条可以跑通的交接链路。

本文不绑定具体开发板。我们会用一个虚构但自洽的 SoC 和 UART 做实验，所以这份 DTB 不会神奇地让你的电脑多出一个串口（遗憾，但也算避免了一次售后事故）。

设备树到底解决什么问题？#

PCI 和 USB 这类总线可以通过协议探测设备。Linux 询问总线，设备回答自己的身份，操作系统再加载驱动。SoC 内部的 UART、GPIO、定时器和很多 I2C 设备通常没有这样的自发现协议。CPU 只知道某个地址范围可能连着寄存器，却不知道那里是什么设备，或者这根中断线接到了哪里。

设备树把这份外部知识交给启动链路。把它想成搬家时交接的一张机器清单：清单说明房间里有什么、门牌号是什么、钥匙交给谁；它不会替你操作洗衣机。对应到规范术语，boot program 可以是固件、bootloader 或 hypervisor，client program 可以是 Linux，也可以是另一个 bootloader。boot program 把 devicetree 放进内存，然后把它传给 client program。

因此职责边界很重要：

DTS/DTB 描述硬件的拓扑、资源和连接关系。
boot program 加载 DTB，并把它传给下一个程序。
Linux 驱动 根据描述找到资源，映射寄存器，申请中断，然后真正操作硬件。
binding 规定某类设备允许使用哪些 compatible 和属性，是接口约束，不是驱动实现。

设备树不是硬件扫描器，也不是驱动代码。往 reg 里写一个地址，不会自动生成对该地址执行读写的驱动。

Warning

注意：设备树不会替代驱动。 compatible 只负责匹配，reg 只描述资源。只有对应的 Linux 驱动成功匹配并执行 probe()，设备才可能被初始化。

先跑通一条 DTS 到 DTB 的链路#

我们先写一个只描述 UART 的最小例子。这里的地址 0x10000000 是实验数据，不属于任何真实芯片。

1
/dts-v1/;
2

3
/ {
4
    compatible = "example,hello-board";
5
    model = "Example Hello Board";
6

7
    #address-cells = <1>;
8
    #size-cells = <1>;
9

10
    soc {
11
        compatible = "simple-bus";
12
        #address-cells = <1>;
13
        #size-cells = <1>;
14
        ranges;
15

16
        uart0: serial@10000000 {
17
            compatible = "example,uart";
18
            reg = <0x10000000 0x100>;
19
            status = "okay";
20
        };
21
    };
22
};

展开收起

保存为 /tmp/devicetree-tutorial.dts 后，先确认工具是否存在：

Terminal window

1
dtc --version

dtc 是 Device Tree Compiler。它把 DTS 文本转换成 DTB，也能把 DTB 反编译回近似的 DTS。我的实验环境如果没有 dtc，这一步就应该明确停下来安装工具，而不是编造一段”成功输出”。在 Debian/Ubuntu 上通常由 device-tree-compiler 包提供，其他发行版请查自己的包管理器。

Caution

工具检查。 如果 dtc 不在 PATH 中，请先安装 Device Tree Compiler。后续编译、反编译和 magic 检查都依赖它们；不要把”命令没有执行”写成”实验成功”。

编译命令的输入是 DTS，输出是 DTB：

Terminal window

1
dtc -I dts -O dtb -o /tmp/devicetree-tutorial.dtb \
2
    /tmp/devicetree-tutorial.dts

随后反编译：

Terminal window

1
dtc -I dtb -O dts -o /tmp/devicetree-tutorial.roundtrip.dts \
2
    /tmp/devicetree-tutorial.dtb

反编译结果不是原文件的文本复制品。标签名、注释和部分源码排版可能消失，但根节点、compatible、reg 和 status 等设备树数据应该还在。若系统安装了 fdtdump，还可以查看底层结构；没有它时，至少可以观察 DTB 的头部：

Terminal window

1
hexdump -C -n 16 /tmp/devicetree-tutorial.dtb

合法 DTB 的前四个字节按大端解释为 magic 0xd00dfeed。这不是”文件前 40 字节永远是什么”的承诺，后面讲 FDT 结构时会看到，真正可靠的是头部字段里的偏移和长度。

这里的”大端”说的是多字节数值在内存或文件中的字节排列顺序。例如数值 0x12345678 由四个字节 12 34 56 78 组成：大端把高位字节 12 放在低地址一侧，小端则把低位字节 78 放在低地址一侧。设备树规范要求 DTB 中的 cell 按大端编码，所以用十六进制查看原始字节时，不能直接把字节序列当作当前 CPU 的本地整数来读。

Note

大小端提醒。 0xd00dfeed 是按大端解释出的 32 位 magic。看到原始字节时，先确认协议规定的字节序，再解释数值；否则很容易把同一组字节读成另一个整数。

这份小树逐行在说什么？

/dts-v1/; 声明 DTS source format version 1。/ { ... }; 是根节点，根节点没有 @unit-address。model 面向人，compatible 面向软件匹配；根节点的 compatible 也必须来自对应平台的约定，实验值只是实验值。

soc 是一个总线节点。ranges; 是空属性，在常见的 simple-bus 写法里表示子总线地址空间与父地址空间相同。uart0: 是源码标签，只服务于 DTS 内部引用，标签本身不会作为标签字符串写入 DTB。

serial@10000000 由两部分构成：通用节点名 serial 和 unit-address 10000000。因为节点有 reg，unit-address 必须与 reg 中的第一个地址相匹配。节点名应使用 1 到 31 个合法字符，并以字母开头；具体总线 binding 还可能增加额外要求。

DTS 语法的最小心智模型#

节点是树，属性是节点里的键值对。属性要写在子节点之前，子节点再继续向下展开。下面把常用值类型放在一处：

1
empty-property;
2

3
one-cell = <42>;
4
two-cells = <0x00000001 0x00000000>;
5

6
one-string = "hello";
7
string-list = "example,device", "example,bus";
8

9
bytes = [00 11 22 aa];

尖括号里的每个 cell 是 32 位无符号整数。一个 64 位值由两个 cell 表示，高位在前。方括号表示 bytestring。多个逗号分隔的组件会拼接成同一个属性值。DTS 还支持 C 风格的算术、位运算和逻辑表达式，例如 reg = <(0x1000 + 0x200) 0x100>;。

reg 不是一种到处一样的”地址加长度”语法。它的 cell 布局由父节点的 #address-cells 和 #size-cells 决定：

1
mmio-bus {
2
    #address-cells = <1>;
3
    #size-cells = <1>;
4

5
    device@2000 {
6
        reg = <0x2000 0x100>;
7
    };
8
};
9

10
i2c-bus {
11
    #address-cells = <1>;
12
    #size-cells = <0>;
13

14
    eeprom@50 {
15
        reg = <0x50>;
16
    };
17
};

展开收起

在第一个例子里，每个条目是一个地址 cell 加一个长度 cell。第二个例子里，I2C 子设备的 reg 是从设备地址，父总线把 #size-cells 设为 0，所以没有长度 cell。不要从某块板子的数值推导普适规则；先看父节点，再看该总线和设备的 binding。

Important

reg 的关键规则。 永远先看父节点的 #address-cells 和 #size-cells，再按照对应 bus binding 解释 reg。I2C 从设备地址、MMIO 地址和 PCI 地址不是同一种语义。

ranges 描述子总线地址空间到父总线地址空间的翻译。它不是 reg 的别名。dma-ranges 则描述 DMA 地址视角下的范围，是否需要它取决于平台的 DMA 地址转换。实际填写时必须查 binding 和平台 DTS。

标签和引用让设备树可以把物理层级与逻辑连接分开：

1
intc: interrupt-controller {
2
    compatible = "example,intc";
3
    interrupt-controller;
4
    #interrupt-cells = <2>;
5
};
6

7
serial@10000000 {
8
    interrupt-parent = <&intc>;
9
    interrupts = <5 4>;
10
};

&intc 最终会被编码为 phandle 相关信息。&node { ... }; 是对已经定义节点的覆盖，板级 .dts 经常用它启用 SoC .dtsi 中默认禁用的外设：

1
&uart0 {
2
    status = "okay";
3
};

共享定义通常放进 .dtsi，再通过 /include/ "soc.dtsi" 引入。源码标签只存在于 DTS 语言；DTB 里保存的是供运行时解析的结构和 phandle 值。

描述一个真实设备需要回答的问题#

我写设备节点时会按下面的顺序检查，而不是看到属性名就往里塞：

设备是谁？ 用 binding 规定的 compatible。列表通常从特化到通用，但只有当内核确实存在对应匹配项时，回退字符串才有意义。
资源在哪里？ 用该总线语义下的 reg、ranges、内存区域和时钟资源。
设备怎么连？ 用 phandle 引用表达时钟、reset、GPIO、DMA 和中断控制器。
现在是否使用？ 通常通过 binding 允许的 status 值表达，常见值是 okay 和 disabled。

一个稍微完整的 SoC 节点可能长这样：

1
soc {
2
    compatible = "simple-bus";
3
    #address-cells = <1>;
4
    #size-cells = <1>;
5
    ranges;
6

7
    uart0: serial@10000000 {
8
        compatible = "example,uart-v2", "example,uart";
9
        reg = <0x10000000 0x100>;
10
        interrupts-extended = <&intc 5 4>;
11
        clocks = <&clk 3>;
12
        resets = <&reset 7>;
13
        pinctrl-names = "default";
14
        pinctrl-0 = <&uart0_pins>;
15
        dmas = <&dma 2>;
16
        status = "okay";
17
    };
18
};

展开收起

这段代码只是展示属性之间的关系，不是某个可直接提交的 Linux binding。interrupts-extended 的 cell 数量由被引用的中断控制器定义，clocks、resets 和 dmas 的参数也分别由 provider 的 #*-cells 和对应 binding 定义。设备树不是”把所有可能的属性都填上”竞赛。

compatible 列表的顺序有意义：更特化的字符串在前，更通用的字符串在后。它不是承诺任意平台都存在一个通用回退驱动。正确流程是先查 Linux 内核 Documentation/devicetree/bindings/ 下的 YAML，再决定字符串和必需属性。make dtbs_check 会用这些 schema 检查编译后的设备树，但 schema 检查通过也不等于硬件接线正确。

Warning

不要凭感觉填写属性。 compatible、中断 specifier、clock/reset/DMA 参数都由 binding 规定。make dtbs_check 通过，只说明描述符合 schema，不证明芯片接线、时钟或电源真的正确。

I2C 设备和中断：两棵逻辑树#

I2C 触摸控制器在设备树的物理拓扑中是 I2C 控制器的子节点，但它的中断线可能接到 GPIO 控制器，再由 GPIO 控制器连接到 GIC。于是”设备在哪”和”中断怎么走”是两种不同的关系。

1
&i2c0 {
2
    #address-cells = <1>;
3
    #size-cells = <0>;
4

5
    touch@38 {
6
        compatible = "example,touch";
7
        reg = <0x38>;
8
        interrupt-parent = <&gpio0>;
9
        interrupts = <12 8>;
10
    };
11
};
12

13
gpio0: gpio-controller {
14
    compatible = "example,gpio";
15
    gpio-controller;
16
    #gpio-cells = <2>;
17
    interrupt-controller;
18
    #interrupt-cells = <2>;
19
    interrupt-parent = <&gic>;
20
};

展开收起

interrupt-controller; 是空属性，表示该节点提供中断域。#interrupt-cells 告诉消费者一个 interrupt specifier 有几个 cell，但具体每个 cell 的含义不能猜。ARM GIC、GPIO 控制器和其他中断域的数量可能不同。

简单设备通常写 interrupt-parent 和 interrupts。如果设备连接多个中断控制器，可以使用 interrupts-extended，它把每个中断控制器的 phandle 和对应 specifier 放在一起。复杂的 PCI host bridge 等 nexus 节点还会使用 interrupt-map 做域间翻译；入门阶段只需要记住：中断引用可以跨越设备树的物理父子关系，详细格式必须回到 binding。

GPIO、clock、reset、DMA 的写法也是同一类 phandle 思路：消费者引用 provider，provider 通过 #gpio-cells 等属性声明 specifier 的宽度。真正的 flags 和参数解释来自各自 binding，不来自属性名字的直觉。

Linux 收到 DTB 后发生什么？#

bootloader 把 DTB 地址交给内核后，Linux 解析扁平化设备树，建立自己的 device model。对于 simple-bus 下的 platform 设备，内核会根据节点创建设备对象；驱动注册时提供 of_match_table，其中的 compatible 与节点属性进行匹配。

匹配成功以后，驱动才会读取资源。常见的 platform driver 代码大致是：

1
static const struct of_device_id example_uart_of_match[] = {
2
    { .compatible = "example,uart-v2" },
3
    { .compatible = "example,uart" },
4
    { }
5
};
6

7
static int example_uart_probe(struct platform_device *pdev)
8
{
9
    struct resource *mem;
10
    void __iomem *base;
11
    int irq;
12

13
    mem = platform_get_resource(pdev, IORESOURCE_MEM, 0);
14
    base = devm_ioremap_resource(&pdev->dev, mem);
15
    if (IS_ERR(base))
16
        return PTR_ERR(base);
17

18
    irq = platform_get_irq(pdev, 0);
19
    if (irq < 0)
20
        return irq;
21

22
    return devm_request_irq(&pdev->dev, irq, example_uart_irq,
23
                            0, dev_name(&pdev->dev), pdev);
24
}

展开收起

这里的关键不是背 API，而是看清边界：设备树提供资源描述，驱动通过 Linux API 取得并使用资源。devm_ioremap_resource() 不会验证地址背后真的焊了一块 UART；它只负责在内核资源模型允许的前提下建立映射。devm_request_irq() 也不替你修复接错的中断线。

Note

排错边界。 设备树描述”有什么”和”资源在哪里”，驱动决定”怎么操作”。匹配失败、资源获取失败和硬件本身不工作，应分别从 compatible、资源属性以及时钟/复位/pinmux/接线排查。

因此排错时要区分三类失败：

compatible 不匹配：设备可能根本没有进入目标驱动的 probe()。
reg、clock、reset 或中断描述错误：驱动进入 probe()，但获取资源失败。
DTS 和 binding 都正确，硬件仍不工作：继续检查时钟、复位、pinmux、电源和真实接线。

系统节点：不要把惯例写成绝对规则#

完整系统描述通常还会出现这些节点：

1
/ {
2
    chosen {
3
        stdout-path = &uart0;
4
    };
5

6
    aliases {
7
        serial0 = &uart0;
8
    };
9

10
    cpus {
11
        #address-cells = <1>;
12
        #size-cells = <0>;
13

14
        cpu@0 {
15
            device_type = "cpu";
16
            reg = <0>;
17
        };
18
    };
19

20
    memory@80000000 {
21
        device_type = "memory";
22
        reg = <0x80000000 0x40000000>;
23
    };
24
};

展开收起

/chosen 是 boot program 向 client program 传递运行时选择的地方，例如 bootargs 和 stdout-path。/aliases 为长路径提供短名字。/cpus 描述 CPU 集合，/memory 描述可用 RAM。某种架构和启动方式可能要求这些节点，但不能脱离上下文说所有设备树在任何场景都必须有完全相同的节点。

/reserved-memory 节点和 FDT 的 memory reservation block 也不是同一个东西。前者是设备树结构里的内存区域描述，常用于 CMA、framebuffer 或固件共享内存；后者是 DTB 二进制中的底层保留表，boot program 可以用它避免 client program 覆写仍在使用的区域。两者都和”这段内存不能随便拿来用”有关，但出现的阶段和表达层次不同。

从 Linux 现场反查设备树#

拿到一台正在运行的 Linux 后，我会按这个顺序排查，而不是先盯着驱动源码：

查看内核实际展开的设备树：
Terminal window
```
1
ls /sys/firmware/devicetree/base
2
ls /proc/device-tree
```
两个路径通常指向内核提供的设备树视图，具体挂载方式取决于系统配置。

查看某个节点的属性。字符串属性以 NUL 结尾，不能总用普通文本工具直读：

Terminal window

1
tr -d '\0' < /sys/firmware/devicetree/base/model
2
printf '\n'
3
xxd /sys/firmware/devicetree/base/soc/serial@10000000/reg

查看驱动和设备的启动日志：
Terminal window
```
1
dmesg | grep -i -E 'of|firmware|uart|probe'
```
如果手里只有 DTB，先反编译，再把结果和板级 .dts、SoC .dtsi 以及对应 YAML binding 对照。
在 Linux 内核源码树中运行 schema 检查：
Terminal window
```
1
make dtbs_check
```

dtbs_check 主要检查设备树是否符合 binding schema。它不能替代 dtc 的语法检查，也不能替代示波器、逻辑分析仪或一双确认过连接器的眼睛。

Tip

验证顺序。 先看 Linux 实际展开的设备树，再看 dmesg，然后对照 DTB、板级 DTS 和 binding。dtbs_check 是约束检查，不是硬件功能测试。

DTB 为什么可以被搬到别的地址？#

DTS 是源码，DTB 是给 client program 消费的紧凑二进制表示。FDT 的设计目标之一是让 boot program 能把它放入内存并传递给下一个程序，因此结构内部使用偏移和长度，而不是依赖加载地址的 C 裸指针。

DTB 头部包含 magic、总大小，以及 memory reservation block、structure block 和 strings block 的偏移与大小等字段。字段按规范使用大端编码。解析器应该读取这些字段，而不是假设某个区块永远位于固定位置。

structure block 把树线性化为 token 序列，常见 token 包括：

FDT_BEGIN_NODE：进入节点，后面跟节点名。
FDT_END_NODE：离开节点。
FDT_PROP：属性，包含长度、属性名在 strings block 中的偏移和属性值。
FDT_NOP：保留的空操作 token。
FDT_END：structure block 结束。

属性名集中存放在 strings block，FDT_PROP 用偏移引用它们。节点和属性数据按 4 字节边界对齐；memory reservation entry 使用 64 位地址和大小。这里的数字和布局规则来自 FDT 结构规范及其头部定义，不应该简化成”固定 40 字节所以永远如此”。

我第一次看到这套布局时，感觉它像一个没有指针的压缩内存快照：解析器带着 offset 在几个区块之间走，遇到 begin/end token 用栈恢复树。这个设计牺牲了一点随机访问的舒服感，却换来了可复制、可重定位和早期启动阶段可解析的格式，算是很合理的嵌入式取舍。

下一次动手做什么#

如果你已经能读懂上面的最小例子，下一步不要继续收藏属性清单。找一块真实开发板，按下面的路径走一遍：

找到它的板级 .dts 和 SoC .dtsi。
沿着节点路径确认父节点的 #address-cells、#size-cells 和 ranges。
在内核 Documentation/devicetree/bindings/ 中找到设备对应的 YAML。
只修改一个 status 或一个资源属性，重新编译 DTB。
用 dtc 反编译产物，确认修改确实进入 DTB。
启动 Linux，从 /sys/firmware/devicetree/base 和 dmesg 确认内核实际拿到的内容。

未来同一份硬件描述继续被不同 client program 使用并不奇怪，但这不意味着设备树自动带来跨平台兼容。真正可移植的是清晰的描述接口；地址、时钟、中断和 binding 仍然属于具体硬件。至于我自己，下一步大概会挑一个真实 GPIO binding 做实验。先把一盏灯点亮，再考虑宇宙级抽象，yolo。

参考资料#

BibTeX 与 BibLaTeX 入门：.bib 文件结构、引用与编译流程

Tue, 19 May 2026 14:00:00 GMT

最近恰逢本科阶段的倒数第二个课程设计，初步估计又得三四十页，并且老师不发模板只发排版要求，美其名曰让我们提前适应毕业论文写作（但是我记得毕业论文也是有 Word 模板的吧😂）。

我并非是某一方的狂热爱好者，在我看来两者都是工具，只要能解决我的问题，那就是好工具。显然这种比较专业的排版需求还是使用 LaTeX 比较合适，而我发现我对 LaTeX 的引用数据库还是不太了解，就大概学习了一并下整理了这篇博客，不一定足够专业，但是应该能够应付我的课程设计了。

1. `.bib` 文件的基本结构#

.bib 文件可以理解成一个文献数据库，由多条文献条目组成。每条条目一般是下面这种形式：

1
@entrytype{citekey,
2
  field1 = {value1},
3
  field2 = {value2},
4
  ...
5
}

@entrytype：文献类型，例如 @article、@book、@inproceedings。
citekey：引用键（citation key），在正文中通过 \cite{citekey} 调用。
field = {value}：字段和值，如 author、title、year。

1.1 常见条目类型与常用字段#

条目类型	说明	常用字段
`@article`	期刊论文	`author`, `title`, `journal`, `year`, `volume`, `number`, `pages`, `doi`
`@inproceedings`	会议论文	`author`, `title`, `booktitle`, `year`, `pages`, `organization`
`@book`	书籍	`author` 或 `editor`, `title`, `publisher`, `year`
`@phdthesis` / `@mastersthesis`	学位论文	`author`, `title`, `school`, `year`
`@misc` / `@online`（BibLaTeX）	网页、预印本	`author`, `title`, `year`, `howpublished` 或 `url`, `note`

Note

不同条目在 BibTeX 与 BibLaTeX 中的必填字段会有差异，建议以所用样式文档为准。可以通过 texdoc biblatex 或 texdoc bibtex 查看官方说明。

2. 一个最小可用的 `.bib` 示例#

假设你新建一个文件 references.bib，内容如下：

1
@article{einstein1905,
2
  author  = {Albert Einstein},
3
  title   = {On the Electrodynamics of Moving Bodies},
4
  journal = {Annalen der Physik},
5
  year    = {1905},
6
  volume  = {17},
7
  pages   = {891--921},
8
}
9

10
@book{knuth1984,
11
  author    = {Donald E. Knuth},
12
  title     = {The {TeX}book},
13
  publisher = {Addison-Wesley},
14
  year      = {1984},
15
}
16

17
@inproceedings{he2016resnet,
18
  author    = {Kaiming He and Xiangyu Zhang and Shaoqing Ren and Jian Sun},
19
  title     = {Deep Residual Learning for Image Recognition},
20
  booktitle = {Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
21
  year      = {2016},
22
  pages     = {770--778},
23
}

展开收起

几个常用写法：

多个作者用 and 分隔（BibTeX/BibLaTeX 会自动识别作者列表）：

1
author = {First Author and Second Author and Third Author},

页码用 -- 而不是 -：

1
pages = {770--778},

大小写保护：专有名词或缩写（如 TeX、CNN）可用 {} 包起来，避免被样式改写：

1
title = {Deep Residual Learning for {CNN} Image Recognition},

3. 在 LaTeX 里如何使用 .bib（两种主流工作流）#

传统路线：LaTeX + BibTeX
现代路线：LaTeX + BibLaTeX + biber

3.1 传统：LaTeX + BibTeX 工作流#

文档示例（main.tex）：

1
\documentclass{article}
2
\usepackage[utf8]{inputenc} % 使用 XeLaTeX/LuaLaTeX 时通常不需要
3

4
\begin{document}
5

6
这是正文中的一条引用 \cite{einstein1905}，再来一条 \cite{knuth1984}。
7

8
\bibliographystyle{ieeetr}   % 选择参考文献样式，如 plain, unsrt, alpha, ieeetr 等
9
\bibliography{references}    % 不写 .bib 后缀
10

11
\end{document}

编译顺序（非常关键）：

pdflatex main
bibtex main
pdflatex main
pdflatex main

很多编辑器可以自动完成这些步骤，但底层顺序仍然是这 4 步。

特点：

优点：历史悠久、兼容性好，很多旧模板和投稿模板仍要求 BibTeX。
缺点：对 UTF-8、多语种姓名支持相对有限；.bst 样式定制门槛较高；对 URL、DOI、在线资源的处理不如 BibLaTeX 灵活。

3.2 现代：BibLaTeX + biber 工作流#

文档示例（main.tex）：

1
\documentclass{article}
2
\usepackage[utf8]{inputenc} % 使用 XeLaTeX/LuaLaTeX 时可省略
3
\usepackage[backend=biber,style=authoryear,sorting=nyt]{biblatex}
4

5
\addbibresource{references.bib} % 指定 .bib 文件
6

7
\begin{document}
8

9
这是正文中的一条引用 \parencite{einstein1905}，
10
以及一条行文引用 \textcite{knuth1984}。
11

12
\printbibliography
13

14
\end{document}

**backend=biber：**指定后端为 biber（而不是 bibtex）。
**style=authoryear：**作者-年份格式（如 “Einstein 1905”），也可改为 numeric、ieee 等。
**sorting=nyt：**按 name-year-title 排序。

编译顺序：

pdflatex main
biber main
pdflatex main
pdflatex main

如果你用的是 XeLaTeX/LuaLaTeX，则把 pdflatex 换成 xelatex 或 lualatex 即可。

特点：

优点：对 UTF-8 与多语言支持更好；字段更丰富（如 @online、url、doi、eprint）；样式可通过 LaTeX 宏定制，可维护性更高；支持按章节、按类型分组等高级功能。
缺点：某些期刊/会议模板仍明确要求 BibTeX。

4. 该如何选择？#

Important

如果模板没有明确限制，通常可以优先考虑 XeLaTeX/LuaLaTeX + BibLaTeX + biber。

5. 写 `.bib` 时的一些实用小技巧#

优先从数据库导出 BibTeX：例如 Google Scholar、arXiv、ACM、IEEE、Springer，可减少手写错误。
统一命名规则（citekey）：

比如 authorYearShortTitle：

1
vaswani2017attention
2
he2016resnet
3
knuth1984texbook

中文文献的处理：在 BibLaTeX + biber + UTF-8 工作流中，可直接使用中文 title、author；若投稿要求英文参考文献，可将英文信息写入主要字段，中文信息放在 note 或 language。
注意特殊字符转义：&, %, _, # 等应转义为 \&, \%, \_, \#。

6. 完整示例（BibLaTeX + biber）#

下面给出一套可直接实验的最小流程。

6.1 新建 `references.bib`#

1
@article{vaswani2017attention,
2
  author  = {Ashish Vaswani and Noam Shazeer and Niki Parmar and Jakob Uszkoreit
3
             and Llion Jones and Aidan N. Gomez and Lukasz Kaiser and Illia Polosukhin},
4
  title   = {Attention Is All You Need},
5
  journal = {Advances in Neural Information Processing Systems},
6
  volume  = {30},
7
  year    = {2017},
8
}
9

10
@book{knuth1984texbook,
11
  author    = {Donald E. Knuth},
12
  title     = {The {TeX}book},
13
  publisher = {Addison-Wesley},
14
  year      = {1984},
15
}

展开收起

6.2 新建 `main.tex`#

1
\documentclass{article}
2
\usepackage[utf8]{inputenc}
3
\usepackage[backend=biber,style=authoryear,sorting=nyt]{biblatex}
4

5
\addbibresource{references.bib}
6

7
\begin{document}
8

9
这是对 Transformer 的引用 \parencite{vaswani2017attention}，
10
这是对 \textcite{knuth1984texbook} 的引用。
11

12
\printbibliography
13

14
\end{document}

6.3 编译顺序#

pdflatex main
biber main
pdflatex main
pdflatex main

如果你用的是 XeLaTeX，就把 pdflatex 换成 xelatex。

Tmux 使用笔记

Sat, 25 Apr 2026 13:55:00 GMT

为什么我们需要 tmux？#

1. 终端的物理与逻辑基础#

在计算机世界里，我们通过 “终端（Terminal）” 与 “Shell（如 bash, zsh）” 进行交互。

当你打开一个终端窗口，或者通过 SSH 连接到远程服务器时，操作系统为你分配了一个 TTY（伪终端），并在这个 TTY 上启动了一个 Shell 进程。你在终端里运行的所有程序（跑脚本、开服务器、编辑代码），都是这个 Shell 的子进程。

2. 致命的耦合（痛点所在）#

这就产生了一个致命的 “生命周期耦合” 问题：

规则：当你的终端窗口关闭，或者由于网络波动导致 SSH 连接断开时，系统会向该 TTY 上的 Shell 发送一个 SIGHUP（挂断信号）。
结果：Shell 收到信号后会立即终止，并带着它所有的子进程一起退出。
痛点：如果你正在服务器上训练一个需要跑 3 天的深度学习模型，或者正在编译一个巨大的项目，只要你的网络断开一秒钟，或者你不小心关掉了窗口，前功尽弃。

3. 需求推演#

为了解决这个问题，我们需要在 “显示界面（你的屏幕/SSH连接）” 和 “后台进程（Shell 及你的任务）” 之间，插入一个中间层。

这个中间层需要具备两个核心能力：

进程解耦（持久化）：它可以接管所有的 Shell 进程，并且无视网络断开和窗口关闭，永远在后台运行。
多路复用（分屏）：既然它接管了终端，那它最好能把一个屏幕切分成多个区域，让我们可以同时看代码、看日志、跑服务，而不需要开一堆 SSH 连接。

这就是 tmux 诞生的原因。

tmux 是什么？（核心架构）#

tmux (Terminal Multiplexer，终端复用器) 就是我们刚刚推导出的那个“中间层”。

它的底层本质是一个 C/S 架构（Client-Server）：

Server（服务端）：当你第一次运行 tmux 时，它会在后台默默启动一个 Server。这个 Server 负责管理你所有的运行环境。只要服务器不重启，它就一直活着。
Client（客户端）：当你在终端敲下 tmux 时，你实际上是启动了一个 Client，连接到了后台的 Server。把 Client 关掉，只是断开了 “显示器”，后台的 Server 和进程依旧在运转。

tmux 的层级逻辑（非常重要）#

为了方便管理，tmux 将你的工作区抽象为三个层级：

Session（会话）：最大的单位。一个 Session 通常代表一个 “项目”。比如你可以建一个名叫 work 的 Session，里面跑你的代码；再建一个名叫 download 的 Session，里面专门用来挂机下载。
Window（窗口）：Session 里面的 “标签页”。类似于浏览器的 Tab，一个屏幕只能显示一个 Window。
Pane（窗格）：Window 里的 “分屏”。你可以把一个 Window 切分成左边看代码、右边看日志。

🖥️ Tmux Server

(后台进程，永不宕机)

📁 Session: work

(项目 1)

📁 Session: download

(项目 2)

📑 Window 1

(编辑代码)

📑 Window 2

(运行测试)

📑 Window 3

(下载管理)

🖼️ Pane 1.1

🖼️ Pane 1.2

🖼️ Pane 1.3

🖼️ Pane 2.1

🖥️ Tmux Server

(后台进程，永不宕机)

📁 Session: work

(项目 1)

📁 Session: download

(项目 2)

📑 Window 1

(编辑代码)

📑 Window 2

(运行测试)

📑 Window 3

(下载管理)

🖼️ Pane 1.1

🖼️ Pane 1.2

🖼️ Pane 1.3

🖼️ Pane 2.1

tmux 的使用方法#

理解了上面的逻辑，使用 tmux 就只是死记硬背几个命令而已了。

1. 前置概念：Prefix Key（前缀键）#

在 tmux 中，所有的快捷键都必须配合一个前缀键使用，默认是 Ctrl + b。

操作逻辑： 先同时按下 Ctrl 和 b，松开双手，然后再按下一个键。

Note

(下文中我将 Ctrl + b 简称为 Prefix)

2. Session 管理（在普通的 Linux 终端打字）#

这是你和 Server 交互的命令：

新建会话：tmux new -s myproject （新建一个名为 myproject 的会话并进入）
脱离会话（后台运行）： Prefix 然后按 d (detach)。你的界面会退回普通终端，但里面的程序还在跑！
查看现有会话：tmux ls
重新连接会话：tmux attach -t myproject (attach)
彻底杀死会话：tmux kill-session -t myproject

3. Window 管理（在 tmux 内部使用快捷键）#

新建窗口：Prefix 然后按 c (create)
切换窗口：Prefix 然后按 n (next，下一个)
- Prefix 然后按 p (previous，上一个)
- Prefix 然后按 数字键 (直接跳转到指定窗口)
关闭当前窗口：Prefix 然后按 & (会弹出确认提示)

4. Pane 管理（在 tmux 内部使用快捷键）#

这是日常写代码最常用的分屏功能：

左右分屏：Prefix 然后按 %
上下分屏：Prefix 然后按 " (双引号)
在分屏间移动光标：Prefix 然后按 方向键 (上下左右)
全屏/取消全屏当前分屏：Prefix 然后按 z (zoom，非常实用，看长报错信息时按一下放大，看完再按一下缩小)
关闭当前分屏：Prefix 然后按 x 或者直接输入 exit

进阶：让 tmux 变得更好用#

可以参考开源项目 gpakosz/.tmux，这里仅列举出开源项目中使用的快捷键绑定。

格式说明#

<prefix> 表示需要按下 Ctrl + a 或者 Ctrl + b。
<prefix> c 表示需要按下 Ctrl + a 或者 Ctrl + b 加上 c。
<prefix> C-c 表示需要按下 Ctrl + a 或者 Ctrl + b 加上 Ctrl + c。

快捷键分类说明#

下表按使用频率和优先级分组，建议按顺序学习：

📌 必学：日常工作最核心的 5 个操作，学会了就能满足基本需求
⭐ 常用：提升工作效率的 15 个快捷键，逐步熟悉即可
🔧 进阶：高级功能和特殊场景，按需学习

快捷键速查表#

📌 会话与窗口基础#

快捷键	功能
`tmux new -s myproject`	新建会话 myproject 并进入（普通终端执行）
`tmux ls`	列出所有会话（普通终端执行）
`tmux attach -t myproject`	重新连接会话（普通终端执行）
`<prefix> d`	脱离会话，回到普通终端，后台保持运行
`<prefix> c`	新建窗口
`<prefix> n`	切换到下一个窗口
`<prefix> p`	切换到上一个窗口
`<prefix> 数字`	直接切换到指定窗口

📌 分屏基础#

快捷键	功能
`<prefix> %`	左右分屏
`<prefix> "`	上下分屏（双引号）
`<prefix> 方向键`	在分屏间移动光标
`<prefix> z`	放大/缩小当前分屏
`<prefix> x`	关闭当前分屏

⭐ 常用操作#

快捷键	功能
`<prefix> e`	打开 .local 配置文件（使用 VISUAL或VISUAL 或 VISUAL或EDITOR 变量定义的编辑器，默认 vim）
`<prefix> r`	重新加载配置
`<prefix> C-c`	新建会话
`<prefix> C-f`	按名称切换会话

⭐ 窗口与分屏导航#

快捷键	功能
`C-l`	清空屏幕和 tmux 历史记录

快捷键	功能
`<prefix> C-h`	导航到上一个窗口
`<prefix> C-l`	导航到下一个窗口
`<prefix> Tab`	切换到最后活跃的窗口

快捷键	功能
`<prefix> -`	垂直分屏
`<prefix> _`	水平分屏
`<prefix> h`	向左导航窗格（Vim 风格）
`<prefix> j`	向下导航窗格（Vim 风格）
`<prefix> k`	向上导航窗格（Vim 风格）
`<prefix> l`	向右导航窗格（Vim 风格）

🔧 进阶操作 - 窗格调整与交换#

快捷键	功能
`<prefix> H`	向左调整窗格大小
`<prefix> J`	向下调整窗格大小
`<prefix> K`	向上调整窗格大小
`<prefix> L`	向右调整窗格大小
`<prefix> <`	与左边的窗格交换
`<prefix> >`	与右边的窗格交换
`<prefix> +`	最大化当前窗格到新窗口

🔧 进阶操作 - 鼠标与复制粘贴#

快捷键	功能
`<prefix> m`	切换鼠标模式（开启/关闭）
`<prefix> Enter`	进入复制模式
`<prefix> b`	查看粘贴缓冲区列表
`<prefix> p`	从顶部粘贴缓冲区粘贴
`<prefix> P`	选择粘贴缓冲区进行粘贴

🔧 进阶操作 - 工具集成#

快捷键	功能
`<prefix> U`	启动 Urlscan（如果可用）或 Urlview
`<prefix> F`	启动 Facebook PathPicker（如果可用）

🔧 进阶操作 - Copy-mode-vi 绑定#

配置文件中的 copy-mode-vi 设定与 Vim 配置相匹配，以下为复制模式下的快捷键：

快捷键	功能
`v`	开始选择 / 可视模式
`C-v`	在块状可视模式和可视模式之间切换
`H`	跳转到行首
`L`	跳转到行尾
`y`	复制选择内容到顶部粘贴缓冲区
`Escape`	取消当前操作

Note

提示：你也可以通过在 .local 自定义配置文件中设置 tmux_conf_preserve_stock_bindings 变量为 true，来保留 tmux 的原始按键绑定。

总结#

掌握 tmux 的关键不在于背熟所有的快捷键，而是在脑海中建立起 Server -> Session -> Window -> Pane 的空间模型，以及理解它将显示与进程解耦的核心价值。习惯它之后，你会发现它是服务器端开发的终极神器。

别再死记 Linux 目录：从 FHS 到运行时文件系统

Tue, 21 Apr 2026 07:00:00 GMT

我以前理解 Linux 目录的方法，基本等价于背一张巨大的单词表：/etc 放配置，/var 放变化的数据，/usr 放程序，背到 /sys、/proc 和 /run 时，大脑就开始悄悄交换它们的位置。问题不在记忆力，而在模型错了。这次我换一种办法：先把目录树拆成几类性质完全不同的对象，再用几条命令观察一台正在运行的 Linux。

FHS 3.0 发布于 2015 年 3 月 19 日。到 2026 年，它已经 11 岁了。它仍然是理解 Linux 文件布局的好起点，但它不是现代 Linux 根目录的完整地图，更不是内核接口、容器存储和桌面应用数据的总规范。

先建立一个能用的模型#

根目录 / 看起来是一棵树，树枝却不一定来自同一块磁盘。它更像一张总配线架：Ext4、Btrfs、tmpfs、procfs、sysfs 和设备节点都接入同一个路径空间，我们恰好可以用普通的路径去访问它们。

我把这棵树分成三层：

持久文件的放置约定：FHS 主要回答软件、配置、日志和用户数据应该放在哪里。
内核与运行时接口：/proc、/sys、/dev、/run 往往由内核或早期用户空间在启动时提供。
进程看到的文件系统视图：挂载命名空间和容器可以让两个进程看到不同的 /，即使它们共享同一个内核。

把这三层混在一起，就会得到一篇目录百科；每一项似乎都对，合起来却没有因果关系。下面逐层拆。

FHS 到底解决什么问题？#

FHS 不是为了让根目录看起来整齐。它要让软件、发行版、管理员和脚本能够预测文件的位置。标准用两条彼此独立的轴来组织数据：

静态 (static) / 可变 (variable)：文件是否会在没有管理员干预时变化。
可共享 (shareable) / 不可共享 (unshareable)：同一份文件能否被多台主机使用。

FHS 3.0 自己给出的例子很干净：

	可共享	不可共享
静态	`/usr`、`/opt`	`/etc`、`/boot`
可变	`/var/mail`、`/var/spool/news`	`/var/run`、`/var/lock`

这张 2 x 2 表是设计原则，不是把每个目录硬塞进一个格子的分类游戏。例如 /home 是否跨主机共享取决于部署方式，/srv 的内容也由站点自己组织。模型负责解释边界，不负责替现实假装整齐。

静态和可变数据分开后，系统资源可以只读挂载，日志和队列可以采用不同的备份策略；可共享和本机专属数据分开后，多台机器可以复用同一份程序而保留各自配置。这才是目录划分真正带来的工程收益。

根目录下的持久世界#

FHS 3.0 要求根目录包含 14 个目录或指向它们的符号链接，并在对应子系统存在时再提供 3 个可选目录。没必要逐字背诵，我更愿意沿着文件的生命周期来理解它们。

`/usr`：发行版提供的静态系统资源#

/usr 是主要的只读、可共享层。发行版或包管理器提供的大部分程序和静态资源都放在这里。

/usr 到底是什么缩写？

网上经常把 /usr 解释为 “Universal System Resources”，但这不是 FHS 给出的官方全称，而是后来流传开的一种解释。FHS 3.0 并没有规定 /usr 应该展开成哪几个英文单词，它只定义这个目录的用途。因此，与其记忆一个有争议的全称，不如直接记住它的目录语义：/usr 主要保存通常可以只读挂载和跨主机共享的系统资源。

/usr/bin：适合从命令行调用的程序。
/usr/lib：库、包的私有数据，以及不打算让用户直接执行的内部程序。
/usr/include：面向用户空间开发的头文件。
/usr/share：与 CPU 架构无关的数据，例如手册、时区和 locale 数据。
/usr/local：系统管理员在本机安装的软件层，避免与发行版管理的 /usr 文件发生冲突。

这里有一个容易踩的坑：/usr/include/linux 是提供给用户空间使用的 UAPI 头文件，不应该随手链接到任意内核源码树。编译外部内核模块时，常见入口是 /lib/modules/$(uname -r)/build；它通常再指向发行版为当前内核准备的构建目录。用户空间 ABI 和内核模块构建环境是两件事。

`/etc`：本机配置，而不是程序仓库#

/etc 保存 host-specific system configuration，也就是本机系统配置。主机名、服务配置、账号数据库和网络策略通常落在这里。

FHS 明确要求 /etc 不放二进制程序。现代系统还经常把发行版默认值放在 /usr，只把管理员覆盖的配置放在 /etc。于是配置的含义变得很清楚：/usr 是供应方给出的默认状态，/etc 是这台机器做出的决定。

`/var`：需要跨重启保留的变化#

/var 保存运行中会变化、而且通常要持久化的数据：

/var/log：日志。
/var/lib：应用持久状态，例如数据库、包管理器状态和 cloud-init 实例数据。
/var/cache：可以重新生成的缓存。
/var/spool：等待处理的队列，例如邮件和打印任务。
/var/tmp：预期可以跨重启保留的临时文件。

“会变大” 不是判断 /var 的充分条件。配置文件也会变化，但它属于 /etc；用户文档也会变化，但它属于用户数据。关键问题是：这是不是系统或服务在运行中产生并需要保留的状态？

`/run`：只服务于本次启动#

/run 保存从本次启动开始才有意义的运行时数据，例如 PID 文件、Unix socket、锁和服务的瞬时状态。现代系统通常把它挂载为 tmpfs，所以重启后自然消失。早期放在 /var/run 和 /var/lock 的内容，如今通常通过兼容链接指向 /run。

/run 与 /var 的分界不是 “内存对磁盘”，而是生命周期：

重启后仍有意义，放 /var。
只描述当前这次启动，放 /run。

这条规则比死记 “PID 文件放哪里” 有用得多。

用户、临时文件与服务数据#

/home：普通用户的主目录。程序应通过 $HOME 或用户数据库查找它，不要假定一定是 /home/<name>。
/root：root 的主目录放在 /home 外，使 /home 尚未挂载时管理员仍可能登录修复。
/tmp：短生命周期临时文件，可能在启动时或定期清理。多用户环境中必须用 mkstemp(3)、mkdtemp(3) 等安全接口创建文件。
/srv：本机对外提供的服务数据，例如管理员维护的网站内容。
/opt：附加软件包的独立目录。它仍在 FHS 中，但现代发行版是否使用它取决于打包策略。
/boot：内核、initramfs 和引导加载器需要的静态文件。EFI 系统分区可能挂载在 /boot、/boot/efi 或 /efi，这是发行版和引导方案的选择，不是所有 Linux 都固定为 /boot/efi。

根目录下的运行时接口#

现在转向另一类东西。/dev、/proc 和 /sys 看起来也是目录，但它们主要不是用来 “存放普通文件” 的。

`/dev`：设备访问入口#

/dev 中的条目是设备节点。它们把文件描述符这套统一接口连接到内核驱动，但 “一切皆文件” 只是一条有用的近似，不是说设备节点等价于磁盘上的普通文件。

例如，读写块设备、终端和随机数设备的语义完全不同。有些设备主要通过 read、write 工作，有些依赖 ioctl，还有些根本不允许普通用户访问。现代发行版通常由 devtmpfs 和 udev 动态维护这里的内容。

`/proc`：进程视图与历史形成的内核接口#

procfs 最初围绕进程信息设计，因此 /proc/<pid> 暴露进程的状态、文件描述符、内存映射和命名空间。后来许多全局内核接口也进入 /proc，例如 /proc/cpuinfo、/proc/meminfo 和 /proc/sys。

它不是 “硬盘里恰好有很多零字节文件”。读取这些路径时，内核动态生成内容；写入某些路径时，内核把数据解释为控制请求。

`/sys`：按内核对象组织的设备模型#

sysfs 导出内核对象、属性以及对象之间的关系。设备、驱动、总线、类和固件信息因此有了比 /proc 更结构化的位置。

几个常见入口：

/sys/class：按设备类别组织的视图，例如网络接口、LED 和 hwmon。
/sys/bus：按总线组织设备与驱动。
/sys/devices：设备拓扑。
/sys/firmware/devicetree/base：设备树系统上，内核展开后的设备树视图。
/sys/fs：cgroup、BPF、pstore 等文件系统或内核子系统的挂载入口。

sysfs 属性通常是稳定 ABI 的一部分，但并不意味着所有子目录都适合应用程序随意写入。例如旧的 sysfs GPIO 用户接口已经被内核文档标为废弃，新程序应优先使用 GPIO 字符设备接口。能 echo 1 不代表应该永远 echo 1，这是 Shell 最容易制造的乐观主义。

用 5 条命令观察真实系统#

到这里，目录名已经不再是一组定义。我们可以直接问正在运行的系统。

1. 这个路径来自什么文件系统？#

Terminal window

1
findmnt -T /
2
findmnt -T /proc
3
findmnt -T /sys
4
findmnt -T /run

关注 SOURCE、FSTYPE 和 OPTIONS。一台常见系统可能分别显示磁盘文件系统、proc、sysfs 和 tmpfs，但容器或不可变发行版会给出不同答案。findmnt 的输出比凭目录名猜测可靠。

2. `/bin` 还是真目录吗？#

Terminal window

1
readlink -f /bin
2
readlink -f /sbin
3
readlink -f /lib

这种布局称为 usr-merge（/usr 合并）：原本分散在根目录和 /usr 下的同类目录被合并到一起，文件统一放进 /usr/bin、/usr/sbin、/usr/lib，再让 /bin、/sbin、/lib 成为指向它们的符号链接。旧程序仍然可以访问 /bin/ls，系统实际执行的却与 /usr/bin/ls 是同一个文件。

早期系统把 /bin 和 /usr/bin 分开，是为了在 /usr 分区尚未挂载时，仍能依靠根分区里的少量工具启动和修复系统。现代 Linux 通常先进入 initramfs，由它准备存储设备并挂载真正的根文件系统，旧边界的实际价值已经很小。usr-merge 因此不是删除兼容路径，而是用符号链接保留旧接口，同时让发行版只维护一套系统文件。

运行上面的 readlink 命令，就能判断当前系统是否采用了这种布局。传统系统中的这些路径仍可能是彼此独立的目录。

3. 一个程序实际加载了哪些库？#

Terminal window

1
ldd /usr/bin/ls

输出会暴露动态加载器与架构相关库目录。在 Debian 的 Multiarch 系统上，你可能看到 /lib/x86_64-linux-gnu；采用 multilib 的系统则常见 /lib64。这是发行版 ABI 布局，不应该被简化成 “64 位系统一律使用 /lib64”。

Note

不要对不可信的可执行文件运行 ldd。部分实现可能执行目标程序。分析未知文件时应使用发行版推荐的静态检查工具。

4. 当前进程属于哪些命名空间？#

Terminal window

1
readlink /proc/self/ns/mnt
2
readlink /proc/self/ns/net
3
readlink /proc/self/ns/pid

输出类似 mnt:[4026531832]。两个进程对应条目的设备号和 inode 相同，才说明它们处在同一个该类型命名空间。方括号里的数字是 namespace inode，不是所谓的 “物理隔离宇宙哈希值”。

5. cgroup v2 怎样表达资源边界？#

Terminal window

1
findmnt -T /sys/fs/cgroup
2
cat /proc/self/cgroup

现代 cgroup v2 通常呈现一棵统一层级。控制器通过 cpu.max、memory.max 等接口设置限制，进程通过 cgroup.procs 加入 cgroup。Docker 和 Kubernetes 会使用这些内核机制，但 /sys/fs/cgroup 本身不属于 FHS 的文件放置规则。

开发程序时，文件应该落在哪里？#

如果我在写一个系统服务，比背目录更实用的是按所有者和生命周期做决定。

FHS 主要安排系统级文件，但桌面和命令行程序还需要保存每个用户自己的配置、数据、缓存和运行状态。过去很多程序直接在 $HOME 下创建 .vim、.mozilla、.cache-of-something 等隐藏目录，久而久之，用户主目录就变成了应用程序各自圈地的现场。

XDG Base Directory 规范解决的就是这个问题。XDG 是 freedesktop.org 规范体系沿用的历史名称；这里真正需要记住的是 Base Directory：它不强迫所有程序使用几个写死的路径，而是通过一组环境变量，为不同生命周期的数据指定基础目录。程序优先读取环境变量，变量未设置时再使用规范给出的默认值。

例如，主题偏好属于配置，应放进 $XDG_CONFIG_HOME；下载后可以重新生成的缩略图属于缓存，应放进 $XDG_CACHE_HOME；Unix socket 只在当前登录会话中有效，应放进 $XDG_RUNTIME_DIR。这样备份配置时不必带上缓存，退出登录时也不必保留 socket。目录分类最终对应的是数据生命周期，而不是单纯为了让 $HOME 看起来漂亮。

内容	系统级位置	用户级默认位置
可执行程序	发行版包用 `/usr/bin`，本机安装常用 `/usr/local/bin`	`~/.local/bin`
静态数据	`/usr/share/<app>` 或 `/usr/local/share/<app>`	`$XDG_DATA_HOME/<app>`，默认 `~/.local/share/<app>`
管理员配置	`/etc/<app>`	`$XDG_CONFIG_HOME/<app>`，默认 `~/.config/<app>`
持久状态	`/var/lib/<app>`	`$XDG_STATE_HOME/<app>`，默认 `~/.local/state/<app>`
可重建缓存	`/var/cache/<app>`	`$XDG_CACHE_HOME/<app>`，默认 `~/.cache/<app>`
本次启动的 socket、PID	`/run/<app>`	`$XDG_RUNTIME_DIR/<app>`，常见于 `/run/user/<uid>`
日志	`/var/log/<app>` 或日志服务	用户状态目录或日志服务

XDG Base Directory 规范定义的不是三个固定隐藏目录，而是一组环境变量和回退值。尤其容易漏掉的是 $XDG_STATE_HOME 和 $XDG_RUNTIME_DIR：前者保存跨重启但不值得当用户数据同步的状态，后者只在登录会话期间有效，权限必须是 0700。

如果程序支持命令行参数或环境变量覆盖路径，优先级也应明确。目录规范解决的是默认位置，不应该剥夺管理员部署软件的能力。

容器为什么能看到另一棵 `/`？#

容器没有发明一套新的 FHS。它组合了几种内核机制：

Mount namespace 给进程一张独立的挂载表。
OverlayFS 把只读 lower layer 和可写 upper layer 合并成一个视图。
PID、network、UTS、IPC、user 等 namespace 隔离其他全局资源。
cgroup 统计并限制一组进程的资源。

因此，容器里的 /etc 仍然表达该容器视图中的配置，/var 仍然表达该视图中的可变状态。变化的是目录树背后的挂载来源和可见范围，不是路径语义凭空消失了。

/proc/<pid>/ns 只是命名空间对象的句柄。命名空间由 clone(2)、unshare(2) 或 setns(2) 等系统调用创建或加入，不是 Docker “创建了一套文件链接”。文件系统在这里提供观察与引用对象的接口，而不是机制本身。

嵌入式系统为什么看起来不太一样？#

资源受限设备通常保留 FHS 的大致语义，却会改变底层存储方式。OpenWrt 常见的根文件系统就是一个好例子：只读 SquashFS 作为 lower layer，可写 JFFS2 或 UBIFS 作为 upper layer，再通过 overlay 组合成可写的 /。

这解释了两个看似矛盾的现象：用户可以修改 /etc/config，恢复出厂设置又能回到固件中的初始状态。修改通常进入可写层，而不是改写只读固件镜像。

原始 NAND 或 NOR Flash 则由 MTD 子系统暴露。/dev/mtdX 是字符设备接口，/dev/mtdblockX 提供受限的块设备视图。后者并不会凭空提供完整的磨损均衡；需要处理坏块和磨损时，应使用适合原始 Flash 的 UBI/UBIFS 等层。把 mtdblock 当成 “内核替我把 Flash 变成普通硬盘”，大概是数据最不希望听到的一句话。

设备树、MTD、OverlayFS 都是 Linux 机制，不属于 FHS。它们出现在同一棵目录树里，是因为 VFS 允许不同文件系统和内核对象共享统一的路径空间。

最后保留这张判断表#

遇到陌生目录时，我现在依次问 5 个问题：

它是普通持久文件，还是一个挂载出来的运行时接口？
谁拥有它：发行版、管理员、服务、用户，还是内核？
内容是静态资源、配置、持久状态、缓存，还是瞬时状态？
它是否需要跨重启、跨用户或跨主机存在？
当前进程看到的路径，是否受 mount namespace 或 overlay 影响？

这 5 个问题足以推导大多数目录的意义。FHS 提供第一层坐标，XDG 把同样的思想延伸到用户目录，内核伪文件系统暴露运行状态，namespace 和 VFS 再决定某个进程最终看见哪棵树。

再往下走，就不再是 “文件应该放哪里” 的问题了，而是 dentry、inode、mount、superblock 和内核对象如何把不同世界接到同一个 / 上。到这里目录表终于变成了一套系统模型，而不是 30 个待背单词。很好，我的大脑可以下班了。

参考资料#

Filesystem Hierarchy Standard 3.0，FHS 的正式规范与二维分类定义。
UAPI.9 Linux File System Hierarchy，面向现代 Linux 的目录布局说明，目前标记为 work in progress。
Linux manual page: hier(7)，典型 Linux 目录层次的手册页。
systemd: The Case for the /usr Merge，usr-merge 的布局、兼容性和历史背景。
XDG Base Directory Specification，用户配置、数据、状态、缓存与运行时目录规范。
Linux Kernel Documentation: The /proc Filesystem，procfs 的内核文档。
Linux Kernel Documentation: sysfs，sysfs 与内核对象模型。
Linux Kernel Documentation: Control Group v2，cgroup v2 层级、控制器与接口文件。
Linux manual page: namespaces(7)，Linux namespace 类型、系统调用与 /proc/<pid>/ns 接口。
Linux Kernel Documentation: Overlay Filesystem，OverlayFS 的 lower、upper、work 与 merged 视图。
Linux Kernel Documentation: Memory Technology Device，MTD 子系统与原始 Flash 设备接口。

英语语法综述

Mon, 06 Apr 2026 09:00:00 GMT

我们为什么学语法？

Note

当然是为了考高分啊😂

其实，所有的英语语法都只有一个目的：造句。

英语和中文一样，我们说话写文章有的时候用短句子，有的时候用长句子。不同的短句子又可以组合成新的长句。但这里说的是句子的长度，并不适合语法讨论。

我们只有把句子拆开来，直到拆到不能再继续拆了，否则句意会不完整的 “基本句”，才好研究语法。因为如果 “基本句” 研究透了，长句子就是它们的组合。

1. 简单句（Simple Sentence）#

我们把这样的不能再拆的 “基本句” 称作简单句（Simple Sentence）。而这样的简单句，除去那些感叹句（“嗯”，“哦”，“啊”等）、省略句、（向整句提问的）问句，几乎全部都是在说：

Note

什么 + 怎么样

绝大多数句子粗略地分一共就只有这两个部分，而这个 “什么” 和 “怎么样” 分别对应了两个最基本的句子成分：

“什么”：主语（Subject）。
“怎么样”：谓语（Predicate）。

换句话说，几乎所有的英语句子结构都是：

Note

主语 + 谓语

这里的主语一般是人或物，不管是抽象还是具体。而这里的谓语则是指一个广义的动作或发生的事情。

Warning

这个 “动作” 不是我们平时狭义说的要动起来的 “动作”，而这个广义的 “动作” 也就是我们语法上说的动词（Verb）。

2. 谓语动词#

序号	动词类型	解释
1	不及物动词	可以独立完成的动作
2	单及物动词	有一个动作的承受者
3	双及物动词	有两个动作承受者
4	复杂及物动词	只有一个动作承受者
5	系动词	非 “动作”

2.1 不及物动词（Intransitive Verb）#

不及物动词（Intransitive Verb）就是指可以独立完成的动作，例如：

Papa Rabbit sleeps.
兔老爹睡觉。

类似 “sleeps” 这样的没有承受者的动词就是不及物动词（Intransitive Verb）。

不及物动词所对应的基本句子结构就是：

Tip

主语 + 不及物动词

2.2 单及物动词（Monotransitive Verb）#

Papa Rabbit likes you.
兔老爹喜欢你。

如果这里只说 “兔老爹喜欢”，你肯定觉得意思不完整，因为像 “喜欢” 这样的动词没有承受者就没有什么实际意义，这样的动词就属于及物动词（Transitive Verb），而这个动作承受者就是宾语（Object）。

具体而言，对于只有一个宾语及物动词，我们称为单及物动词（Monotransitive Verb）。

单及物动词对应的基本句子结构就是：

Tip

主语 + 单及物动词 + 宾语

2.3 双及物动词（Ditransitive Verbs）#

Papa Rabbit teaches you English.
兔老爹教你英语。

这里的核心动词是 “teach”（教），但是教授的知识是 “英语”，而知识的接收对象是 “你”。在语法上，我们把这样的动词的两个承受者分别称为直接宾语（Direct Object）和间接宾语（Indirect Object）。

如果只说 “兔老爹教英语”，其实语义已经完整了，所以 “English” 这里就是直接宾语，而如果只说 “兔老爹教你”，而又没有上下文的话，你肯定觉得还缺了什么，所以 “you” 在这里是间接宾语。

这样的往往既有直接宾语又有间接宾语的动词，也是及物动词的一种，更具体地说，它属于双及物动词（Ditransitive Verbs）。

双及物动词对应的基本句子结构就是：

Tip

主语 + 双及物动词 + 间接宾语 + 直接宾语

2.4 复杂及物动词（Complex-transitive Verb）#

Papa Rabbit considers you smart.
兔老爹认为你聪明。

这里虽然只有一个动作的承受者 “you”，但如果只说 “兔老爹认为你”，你肯定会觉得话没有说完，但是宾语 “you” 后面的 “smart” 却也不像双及物动词那样是另一个动作承受者。

这样的动词，必须要有个补充承受者的信息才意义完整，而这个补充的信息，我们在语法上称为补足语或补语（Complement）。更明确也可以说是宾语补语（Object Complement）。

这样的需要补语的动词，我们称之为复杂及物动词（Complex-transitive Verb）

复杂及物动词对应的基本句子结构就是：

Tip

主语 + 复杂及物动词 + 宾语 + （宾语）补语

2.5 系动词（Linking Verb）#

这种动作所表示的含义与狭义上的 “动作” 不太一样：

Papa Rabbit is tall.
兔老爹是高的。

这里的 “is” 在中文里经常翻译成 “是”，但它实际上的作用很简单：

Caution

就是把这个动词之后的信息赋予前面的主语。

这里的 “is” 说白了就是把 “Papa Rabbit” 和 “tall” 连在一起，划上等号而已。或者说，把后者信息赋予前者。如果把 “tall” 换成 “in the room”：

Papa Rabbit is in the room.
兔老爹在房间里。

其实也是把 “in the room” 这个状态性质赋予 “Papa Rabbit” 而已。

Papa Rabbit looks tall.
兔老爹看起来高。

这个 “look” 通常意义是 “看”，但是这里到底是谁在看？其实不是 “Papa Rabbit” 在看，“Papa Rabbit” 在这里是被看。这里的 “looks” 其实也是把后面的 “tall” 赋予前面的主语 “Papa Rabbit” 而已，也算是划等号，只不过这个划等号比之前的 “is” 多了个 “看上去”。

Papa Rabbit smells nice.
兔老爹闻上去香。

这里的 “smells” 还是把 “Papa Rabbit” 和 “nice” 划等号，只不过还有 “闻上去” 这层意思。

像这样的赋予主语某种性质状态的 “划等号” 的动词，我们称之为连系动词（Linking Verb），也称为系动词。

系动词后面的补充信息自然就是补足语或补语，更精确地说是主语补语，而主语补语在中国的英语教学中又被称为表语（Predicative）。

系动词对应的基本句子结构就是：

Tip

主语 + 系动词 + （主语）补语/表语

3. 五大基本句型#

序号	句型
1	主语 + 不及物动词
2	主语 + 单及物动词 + 宾语
3	主语 + 双及物动词 + 间接宾语 + 直接宾语
4	主语 + 复杂及物动词 + 宾语 + 宾语补语
5	主语 + 系动词 + 主语补语/表语

Note

还有一种 “八大句型” 的分类，即在 “五大句型” 基础上增加：

there be 句型，如：There is a rabbit. 可理解为第 5 种句型 “主语 + 系动词 + 主语补语/表语” 的倒装。
主语 + 谓语 + 状语，如：I live in China. 可理解为第 1 种句型 “主语 + 不及物动词” 的延伸（虽然这里的状语很重要）。
主语 + 谓语动词 + 宾语 + 状语，如：I put the carrot on the table. 可理解为第 4 种句型 “主语 + 复杂及物动词 + 宾语 + 宾语补语” 的延伸。

Warning

严格说来，谓语和谓语动词是有区别的。句子主语后面余下的部分就是谓语，谓语动词只是谓语的一部分。

但是在平时，通俗地，为了方便，很多人会直接称呼谓语动词为谓语，而把 “主语 + 谓语动词 + 宾语” 这样的句子结构直接称呼为 “主语 + 谓语 + 宾语”（或 “主谓宾”），这也不是什么大问题。

4. 句子基本成分#

序号	成分	英文名	解释	例句
1	主语	Subject	动作的发出者或被讨论的对象	Papa Rabbit eats carrots.
2	谓语动词	Predicate Verb	表示具体的动作或状态	Papa Rabbit eats carrots.
3	宾语	Object	动作的承受者	Papa Rabbit eats carrots.
4	宾语补语	Object Complement	补充说明宾语的状态或特征	Papa Rabbit considers you smart.
5	主语补语	Subject Complement	补充说明主语的性质状态（即表语）	Papa Rabbit is tall.
6	定语	Attributive	修饰主语或宾语	The little white rabbit ate a large carrot.
7	状语	Adverbial	修饰谓语动词	The rabbit ate quickly.
8	同位语	Appositive		Papa Rabbit, an English teacher, eats carrots.

Note

你可能听过 “插入语”，如：This carrot, I think(插入语), is very tasty. 但是插入语是独立的，不作句子成分。

5. 复杂句#

直到现在所说的都是简单句（Simple Sentence），说白了就是没法再拆成更多句子了。但是我们说话写文章可不全是简单句，而是经常会把这些简单句互相组合形成所谓复合句（Compound Sentence）和复杂句（Complex Sentence）。

复合句说白了就是句子简单的叠加，句子和句子之间是并列关系，因此也被称为并列句。

复杂句则是把一个句子套在另一个句子里，允许不断嵌套，是从属关系。

一个句子套另一个句子，在英语语法上分别叫做主句（Main Clause）和从句（Subordinate Clause）。

从句说白了就是把简单句修改一下来充当另一个句子的句子成分。

主句

Main Clause

从句

Subordinate Clause

主句

Main Clause

从句

Subordinate Clause

5.1 从句类型#

序号	从句	作用	补充	例句
1	主语从句	作主语	名词性从句	What Papa Rabbit ate is a carrot.
2	宾语从句	作宾语	名词性从句	I know that Papa Rabbit likes carrots.
3	表语从句	作表语	名词性从句	The truth is that he likes you.
4	同位语从句	作同位语	名词性从句	The fact that he ate the carrot is obvious.
5	定语从句	作定语		The rabbit who ate the carrot is my papa.
6	状语从句	作状语		I will leave when Papa Rabbit comes.

6. 词性#

但是现在问题来了，两个句子也许句子组成的方式相同，比如都是 “主语 + 谓语动词 + 宾语”，可是句中包含的词的类型并不一定相同，比如：

The rabbit ate a carrot.
He saw something over there.

很显然，这两句话 “句型” 相同，但是包含的词却不太一样。也就是说，同一类句子成分里可能有不同的词类（或词类），这个概念中文中也有。

序号	词性	英文名	解释	例句
1	动词	verb	表示动作或状态	Papa Rabbit eats a carrot.
2	名词	noun	表示人或物	Papa Rabbit is a rabbit.
3	冠词	article	用于说明人和事物	Papa Rabbit is a rabbit.
4	代词	pronoun	替代人和物	I am a rabbit.
5	形容词	adjective	形容人和物	I am a smart rabbit.
6	数词	numeral	表数量	I ate two carrots.
7	副词	adverb	修饰动作或形容词	I ate two carrots quickly.
8	介词	preposition	表示和其他词关系的词	I ate two carrots with chopsticks.
9	叹词	interjection	表感叹	Ah, the carrot is tasty!
10	连词	conjunction	连接词和句	I ate two carrots and a potato, because I was hungry.

Caution

句子成分（Clause Element）和句子中的词类（Parts of Speech）是完全不同的概念。

前文所述的每一种句子成分，除了谓语动词只能是动词，其他成分都可能包含不同的词类。

7. 谓语动词的 “三大本领”#

英语中的谓语动词有很多厉害的本领，而这些本领，中文中的动词都没有，是英语语法的难点之一：

动作时间
动作状态
动作假设，情感等

Warning

所谓 “中文动词没有这些本领” 是说中文动词本身没有 “时、体、气” 的概念，但是中文当然有相同或相似意思的表达。

7.1 时态#

英语的时态就是时间 + 状态合在一起，而并非只有时间。

	现在	过去	将来	过去将来
一般	一般现在	一般过去	一般将来	一般过去将来
完成	现在完成	过去完成	将来完成	过去将来完成
进行	现在进行	过去进行	将来进行	过去将来进行
完成进行	现在完成进行	过去完成进行	将来完成进行	过去将来完成进行

Note

时态是时间的排列组合，并不是一个线性的列表，更不是只和时间有关。

7.2 语气#

序号	语气	解释	例句
1	虚拟语气	用来表示意愿，与事实相反的假设等	If I were a rabbit…
2	陈述语气		I ate a carrot and…
3	祈使语气		Eat this carrot and…

7.3 助动词（Auxiliary Verb）#

英语的谓语动词本身往往是不能够独立完成刚才说的上述的这些本领，而且谓语动词也无法完成比如表示否定、可能性、必须性等意思。

想让谓语动词充分发挥，我们必须用到另一类经常和动词一起用的词，来帮助完成任务，它们就是助动词（Auxiliary Verb）

例如对于动词 eat：

协助	助动词	组合
表示 “吃过了（完成）”	have	have eaten
表示 “正在吃（进行）”	be	is eating
表示 “被吃”	be	is eaten
表示 “有能力吃”	can	can eat
表示 “有可能吃”	might	might eat
表示 “有义务吃”	must	must eat
表示 “不吃（否定）”	do	do not eat

Note

以上的 can, might, must 也被称作 “情态动词”，可归类在 “助动词” 里，但是也有些语法体系把情态动词单独归类，这是分类的不同，不影响理解。

Caution

有些动词，既可以是助动词（无实义），也可以做实义动词，比如 have 也可以表示 “拥有”。千万不要把助动词和它的其他身份（作实义动词时）弄混淆。

8. 非谓语动词#

之所以需要把动词叫做谓语动词，是因为还有所谓非谓语动词，这听起来似乎是一句废话。

不过，之所以这么叫，是因为动词除了充当句子中的谓语动词，还有可能充当：主语、宾语、宾语补语、主语补语、定语等，只不过需要变成非谓语动词。

不仅如此，非谓语动词几乎可以取代所有的从句，从而简化句子。只不过非谓语动词就不再具有表示动作时间、状态、语态、语气的功能，也就是它们丧失了时态、语气、语态这些本领了。

非谓语动词以不同的形式出现在句中，包括：

动词不定式：常表将来或具体的单次行为。如作主语：To eat a carrot is Papa Rabbit’s dream.
现在分词：常表主动或正在进行。如作定语：The rabbit eating a carrot is my papa.
动名词：将动词名词化，常表抽象概念或习惯。如作宾语：Papa Rabbit enjoys eating carrots.
过去分词：常表被动或已经完成。如作宾语补语：Papa Rabbit wants the carrot eaten.

9. 总结#

上述这么多一直在讲动词，这是因为：

Caution

英语语法的核心就是动词，动词几乎可以串联起所有英语语法的核心概念。

英语语法体系

以上就是英语语法体系的主体框架，绝大多数的语法规则，都逃不出这个框架。而无数的规则和特例也不过就是让这个核心体系更加丰富而已。

10. 参考资料#

GNU 汇编（GAS）通用语法与伪指令指南

Sun, 05 Apr 2026 08:35:00 GMT

由于机器指令及助记符高度依赖于芯片的具体架构，本文不讨论特定指令集的全部细节，而是聚焦于 GAS（GNU Assembler）通用的伪指令系统及其基本语法规则。

1. 汇编器的本质与工作流#

GNU Assembler（简称 as）的核心工作流可以用以下公式概括：

源代码 (.s)→汇编器 (as)可重定位目标文件 (.o)\text{源代码 (.s)} \xrightarrow{\text{汇编器 (as)}} \text{可重定位目标文件 (.o)}源代码 (.s)汇编器 (as)可重定位目标文件 (.o)

生成的 .o 文件主要由 Section（段）和 Symbol Table（符号表）组成。我们常用的 GAS 伪指令（Directives/Pseudo-ops），其根本目的就是为了控制这两个核心要素的生成。

从本质上来说，GNU Assembler 的核心职能并非简单的 “代码翻译”，而是内存空间的规划与符号地址的解析。

汇编器内部维护着一个至关重要的变量：地址计数器（Location Counter，通常记为 .）。当汇编器读取源代码时，它实际上是在执行一个状态机循环：

解析伪指令：根据指令调整地址计数器的位置（例如跳转到新的段、预留空白空间）或修改符号的属性（如设置为全局可见）。
发射字节流：将翻译好的机器指令或定义的静态数据 “填充” 到地址计数器当前指向的内存单元，随后让计数器自增，指向下一个空闲位置。
构建符号表：记录所有标号（Label）对应的最终物理地址或相对于段的偏移量。

因此，当我们编写汇编代码时，实际上是在做两件事：

填充内存：明确告诉汇编器，在当前的内存地址上应当放置什么数据（注意：机器指令在内存中本质上也是数据）。
标记位置：给特定的内存地址起一个人类可读的名字（Label/Symbol），以便后续进行跳转或读写操作。

2. 指令语法#

GAS 语法的核心难点在于不同架构下对操作数方向的处理，以及如何消除符号的歧义。

2.1 注释风格#

不同的 CPU 架构在 GAS 中通常使用不同的单行注释符号。这里仅列举常见架构的规范，更详细的列表可查阅 Binutils Docs: Machine Dependent Features。

Note

推荐直接查阅 “Machine Dependent Features” 文档，官方通用的 “Comments” 文档包含大量历史遗留信息，较为混乱。

多行注释在所有架构中是通用的，沿用了 C 语言风格：

1
/*
2
 The only way to include a newline ('\n') in a comment
3
 is to use this sort of comment.
4
 */
5

6
/* This sort of comment does not nest. */

单行注释则因架构而异：

2.1.1 x86-64#

根据 Binutils Docs: i386_002dChars 的说明：

The presence of a # appearing anywhere on a line indicates the start of a comment that extends to the end of that line.
If a # appears as the first character of a line then the whole line is treated as a comment, but in this case the line can also be a logical line number directive…
If the —divide command line option has not been specified then the `/’ character appearing anywhere on a line also introduces a line comment.
The ; character can be used to separate statements on the same line.

核心解读：

首选注释符：使用 #。只要行内出现 #，其后内容均为注释。
特殊情况：如果 # 出现在行首，汇编器会优先检查它是否为预处理命令（如 #include）或逻辑行号。
避坑指南：虽然默认情况下 / 也可以作为注释开始，但这极易产生歧义。例如在指令 movq $(10/2), %rax 中，汇编器可能会把 /2 误判为注释。除非指定了 --divide 选项，否则严禁使用 / 写注释。
语句分隔：分号 ; 用于在同一行写多条指令，类似 C 语言。

2.1.2 ARM (32-bit)#

根据 Binutils Docs: ARM_002dChars 的说明：

The presence of a @ anywhere on a line indicates the start of a comment that extends to the end of that line.
If a # appears as the first character of a line then the whole line is treated as a comment…
The ; character can be used instead of a newline to separate statements.
Either # or $ can be used to indicate immediate operands.

核心解读：

首选注释符：使用 @。这是最安全的方式。
分号的作用：在 GNU ARM 汇编中，; 是语句分隔符（注意：这与 ARM 官方汇编器如 Keil/armasm 不同，后者用 ; 做注释）。
# 的双重身份：
- 如果在行首，它是注释。
- 如果在指令中，它表示立即数（例如 MOV R0, #10）。
- 警告：切勿在指令行尾使用 # 做注释，汇编器会将其误认为是非法的立即数格式。
立即数：虽然支持 x86 风格的 $，但为了代码移植性，强烈建议使用 # 表示立即数。

2.1.3 AArch64 (ARM64)#

GNU 对 32 位 ARM 和 64 位 AArch64 做了严格区分，语法有所不同。

Binutils Docs: AArch64_002dChars 说明如下：

The presence of a // on a line indicates the start of a comment that extends to the end of the current line.
If a # appears as the first character of a line, the whole line is treated as a comment.
The # can be optionally used to indicate immediate operands.

核心解读：

首选注释符：使用 //（C++ 风格）。
立即数：# 是可选的，但在阅读习惯上保留它更为清晰。

2.1.4 RISC-V#

RISC-V 的 GAS 实现较为现代，通常兼容性较好：

支持行首 # 注释。
通常支持 // 或 # 作为行尾注释（具体取决于工具链版本，建议测试确认）。

Warning

建议以 # 为主，不建议使用 // 作为通用写法。

2.2 最大的分歧：数据流向（Direction）#

阅读 GAS 代码的第一道门槛是源操作数与目的操作数的顺序。GAS 历史上继承了 AT&T 语法（源自 Unix），而芯片厂商文档通常使用 Intel/Native 语法。

2.2.1 x86 环境下的 GAS（AT&T 风格）#

x86 GAS 遵循 “源在前，目的在后” 的原则。读代码时请默念“把左边的值给右边”。

1
operation source, destination

例如：

1
movl %eax, %ebx  # 含义：EBX = EAX (将 EAX 的值搬运到 EBX)

2.2.2 ARM/RISC-V 环境下的 GAS（官方风格）#

为了减少混乱，GNU 针对 ARM 和 RISC-V 做了妥协，采用了更符合官方文档的 “目的在前，源在后” 顺序：

1
operation destination, source

例如：

1
mov r0, r1       # 含义：r0 = r1 (将 r1 的值搬运到 r0)

2.3 消除歧义：前缀与修饰符#

汇编器必须通过“前缀”来区分一个数字到底是数值、地址还是寄存器。

2.3.1 寄存器#

x86 (AT&T)：必须加 %，例如 %eax, %esp。
ARM/RISC-V：通常不加前缀，直接写 r0, sp, pc。为了避免与 C 语言变量名冲突，偶尔可见 %r0 写法，但不常见。

2.3.2 立即数#

汇编器如何知道 10 是指“内存地址 10”还是“数字 10”？

x86 (AT&T)：数字前必须加 $。
ARM：官方推荐加 #。
RISC-V：极其精简，通常不加前缀，依靠指令名（如 li, addi）的上下文自动推断。

对比示例：

1
# x86 (AT&T)
2
movl $10, %eax   # EAX = 10 (立即数)
3
movl 10, %eax    # EAX = *(int*)(0x0A) (读取内存地址 10 的内容)
4

5
# ARM
6
MOV R0, #10      @ R0 = 10
7

8
# RISC-V
9
li a0, 10        # Load Immediate: a0 = 10

2.4 内存寻址模式#

在 64 位系统中，内存地址空间高达 2642^{64}264，需要 8 字节才能完整表达。然而，一条机器指令通常只有 4 字节（RISC）或变长（x86）。如何在有限的指令长度内精确指向遥远的内存地址？这是寻址模式设计的核心挑战。

2.4.1 x86 (AT&T)#

x86 是 CISC（复杂指令集），其最大特点是允许运算指令直接操作内存。硬件内建了强大的 SIB（Scale-Index-Base）寻址单元，将地址计算视为一个多项式：

通用格式：

1
offset(base, index, scale)

计算公式：

Address=base+(index×scale)+offset\text{Address} = \text{base} + (\text{index} \times \text{scale}) + \text{offset}Address=base+(index×scale)+offset

应用场景：这非常适合访问数组。例如 array[i]，其中 base 是数组首地址，index 是变量 i，scale 是元素大小（如 int 为 4）。

1
movl 4(%ebp), %eax    # 取地址 (ebp + 4) 处的数据 -> eax
2
movl array(,%edi,4), %eax # 取地址 (array + edi * 4) 处的数据 -> eax

2.4.2 ARM#

ARM 是 RISC 且为 Load/Store 架构。这意味着不能直接对内存里的数进行 add 等运算，必须先 ldr（Load）到寄存器，运算后再 str（Store）回去。

ARM 的特色在于 Address Write-back（地址回写）。为了方便遍历数组，它允许在读写内存的同时，自动更新基址寄存器的值。

GAS 中使用中括号 [] 表示内存引用：

常规偏移：[Base, Offset]
寄存器偏移：[Base, Register]，甚至支持移位 [Base, Reg, lsl #3]。
前索引（Pre-indexed）：[r1, #8]! —— 访问前先加 8，且修改 x1 的值（x1 += 8）。
后索引（Post-indexed）：[r1], #8 —— 访问后再加 8，且修改 x1 的值。

2.4.3 RISC-V#

RISC-V 追求极致的硬件精简。它不支持 ARM 那种复杂的自动回写，也不支持 x86 的复杂比例因子。

RISC-V 的基础指令多为 32 bit（但启用压缩扩展后也有 16 bit 指令），除去操作码和寄存器位，留给立即数偏移的空间只有 12 位（即 ±2KB\pm 2\text{KB}±2KB）。

通用格式：

1
offset(base)

计算公式：

Address=base+offset\text{Address} = \text{base} + \text{offset}Address=base+offset

如何访问大范围地址？

由于 12 位无法容纳 32/64 位地址，必须将大地址拆分为“高位”和“低位”两条指令处理：

1
# 小范围寻址 (Offset < 2048)
2
lw a0, 8(sp)        # 从 sp + 8 处加载一个 word
3
sw a0, 0(t1)        # 存入 t1 + 0 处
4

5
# 大范围/全局变量寻址 (Hi/Lo 拆分)
6
lui t0, %hi(VAL)      # 加载 VAL 地址的高 20 位到 t0
7
lw  a0, %lo(VAL)(t0)  # 加载 VAL 地址的低 12 位，作为偏移加到 t0 上读取

2.5 指令后缀：操作数宽度 (Size Suffixes)#

在机器层面，CPU 处理数据时必须明确一个核心参数：位宽 (Width)。硬件需要知道它是应该只驱动数据总线上的 8 根线，还是激活全部 64 根线？是将数据放入寄存器的低 8 位（如 AL），还是覆盖整个 64 位（如 RAX）？

GAS 通过在指令助记符后添加后缀来显式控制这一行为。

2.5.1 GAS 通用命名规则#

GAS 使用一套单字母后缀来表示数据宽度。需要特别警惕的是，不同架构对 “Word” 的定义存在历史分歧。

后缀	全称	大小 (Bits)	字节数	说明
b	Byte	8-bit	1	通用。
w	Word	16-bit	2	注意！在 x86 语境下，Word 是 16 位（源于 8086）。但在 ARM/RISC-V 文档中，Word 通常指 32 位。GAS 的 `w` 后缀专指 16 位。
l	Long	32-bit	4	x86 的标准 32 位后缀。
q	Quad	64-bit	8	四字（4 x 16-bit），即 64 位。

2.5.2 x86 架构：显式后缀 (Explicit Suffixes)#

x86 是变长指令集，且寄存器存在嵌套关系（RAX 包含 EAX 包含 AX 包含 AL）。为了消除歧义，GAS 强烈推荐在所有操作码后加上后缀。

虽然现代汇编器有时能根据寄存器名字（如 %eax）推断出你是想操作 32 位，但在涉及内存操作数（无法看出大小）或立即数时，不写后缀极易报错。

1
movb $0xFF, %al        # 移动 1 个字节 (8-bit)
2
movw $0xFFFF, %ax      # 移动 1 个字   (16-bit)
3
movl $0xFFFFFFFF, %eax  # 移动 1 个长字 (32-bit)
4
movq $1, %rax          # 移动 1 个四字 (64-bit)
5

6
# 歧义示例：
7
# mov $0, (%rbx)     # 错误！汇编器不知道你想把 rb 指向的内存清零 1 个字节还是 8 个字节。
8
movq $0, (%rbx)      # 正确：清零 8 个字节

2.5.3 ARM / RISC-V 架构：助记符内含宽度#

与 x86 不同，ARM 和 RISC-V 等 RISC 架构通常将数据宽度直接编码在指令助记符本身中，而不是依赖 GAS 的通用后缀。

在这些架构中，你通常不会看到 movl 这种写法，而是通过不同的指令变体来实现：

RISC-V:
- lb (Load Byte): 加载 8 位
- lh (Load Half-word): 加载 16 位
- lw (Load Word): 加载 32 位 (注意：这里 Word 是 32 位)
- ld (Load Double-word): 加载 64 位
ARM:
- LDRB (Byte): 加载 8 位
- LDRH (Half-word): 加载 16 位
- LDR (Word): 加载 32 位

Warning

“Word” 的陷阱

这是一个跨架构开发时最容易混淆的概念：

在 x86 汇编中，Word = 16 bits。
在 ARM / RISC-V 汇编中，Word = 32 bits。

当你使用 GAS 的 .word 伪指令定义数据时，它在所有架构上通常都表示 32 位（或 16 位，取决于具体配置，但在现代环境下多为 32 位）。务必查阅具体目标架构的文档确认 .word 的确切长度，或者直接使用 .2byte / .4byte 这种无歧义的写法。

3. 伪指令系统 (Directives)#

伪指令以 . 开头，它们不对应具体的 CPU 机器码，而是指挥汇编器如何组织二进制结构。

3.1 数据定义：如何填充字节#

这些指令直接在当前地址计数器位置“发射”数据，常用于定义查找表或初始化变量。

.byte / .hword / .word / .long / .quad：

在当前地址写入特定宽度的整数。注意**字节序（Endianness）**取决于目标架构（x86 为小端，ARM/RISC-V 默认为小端，但可配置）。

代码段
```
1
.byte 0x12, 0x34    # 写入两个字节
2
.word 0xAABBCCDD    # 写入 4 字节。小端模式下内存为：DD CC BB AA
```
.ascii vs .asciz / .string：
- .ascii "Hello"：仅填入字符 ASCII 码，无结尾 \0。
- .asciz "Hello" 或 .string：自动在末尾补 0x00（C 语言标准字符串）。

.fill / .skip / .space / .zero：

用于预留空间或清零，常用于定义栈（Stack）或 BSS 段。

代码段

1
stack_top:
2
.skip 1024, 0      # 预留 1024 字节，全部填 0
3
stack_bottom:      # 栈底标号（假设栈向下生长，SP 初始指向此处）

3.2 内存控制：如何管理地址#

.section：

告诉汇编器：“接下来的数据/指令，请分类归档到哪个‘抽屉’里”。
- .section .text：代码段（只读，可执行）。
- .section .data：已初始化的全局变量（可读写）。
- .section .bss：未初始化变量（不占磁盘空间，程序启动时自动清零）。
- 自定义段：例如 .section .isr_vector，配合链接脚本（Linker Script），可以将中断向量表精确固定在 Flash 的 0 地址处。
.align vs .balign：
- .align：行为不统一！在 x86 下 .align 4 表示 4 字节对齐；但在 ARM 下可能表示 24=162^4=1624=16 字节对齐。
- .balign（Byte Align）：推荐使用。.balign 4, 0 明确表示保证地址能被 4 整除，如果需要填充，则填 0。
.org：

强制修改当前的地址计数器。
- 示例：编写 MBR 引导扇区时，需要在第 510 字节写结束标志 0x55AA，会用到 .org 510。

3.3 符号管理：与 C 语言的交互接口#

这是 C 和汇编混合编程的桥梁。

.global（或 .globl）：

将符号标记为全局可见。如果不加此标记，符号仅在当前文件内部可见（类似 C 的 static），链接器无法找到它。
- 场景：Startup 文件（启动文件）必须声明 .global Reset_Handler，否则硬件复位后找不到入口。
.extern：

声明符号在外部定义。虽然 GAS 通常能自动推断，但显式声明能提高代码可读性。
.equ / .set：

常量定义，相当于 C 的 #define。它们只存在于汇编阶段，不占用运行时的内存空间。

代码段
```
1
.equ STACK_SIZE, 0x400
```
.type：

明确告诉链接器符号的类型（是函数还是数据）。
- 重要性：在 ARM Thumb-2 指令集中，如果链接器知道某符号是 %function，它会在计算跳转地址时自动将最低位置 1（Thumb 状态标志）。若省略此指令，可能导致切换状态失败而进入 HardFault。
.weak：

弱符号定义。
- 机制：如果在其他地方定义了同名的强符号（普通的 .global），链接器优先使用那个；如果没有，则使用这里的默认定义。
- 应用：STM32 启动文件中的中断处理函数通常用 .weak 定义为死循环。这允许用户在 C 代码中重写同名函数（如 SysTick_Handler）来覆盖默认行为，而无需修改启动代码。

4. GAS 的特色功能 (Syntactic Sugar)#

4.1 局部数值标签 (Local Numeric Labels)#

为了避免给简单的循环绞尽脑汁起名字（如 loop1, loop_start），GAS 允许使用数字作为临时标号。

定义：<num>:
引用：<num>f (forward, 向前/向下找)，<num>b (backward, 向后/向上找)。

示例：

代码段

1
1:          # 定义标号 1
2
    wfi     # Wait for interrupt
3
    j 1b    # 向后跳转到最近的标号 1 (相当于 while(1);)

4.2 宏 (Macros)#

用于封装重复代码片段：

代码段

1
.macro 宏名称 参数1, 参数2
2
    // 宏体内容，可使用 \参数1 引用
3
.endm

4.3 `.` (Current Location)#

符号 . 代表当前地址计数器的值。

常见用法：b . 等同于 while (1);（跳转到当前地址，死循环）。

ARMv7-A 指令体系全解：数据处理、访存、分支与同步

Sun, 05 Apr 2026 08:20:00 GMT

I.MX6ULL 的核心是 ARM Cortex-A7，它基于 ARMv7-A 架构。

要真正理解指令集，就不能只是背诵汇编手册，而是要回答一个核心问题：如果不看代码，只看电路，CPU 在做什么？

本质上，每一条指令都是对 CPU 内部寄存器状态或外部总线（内存/外设）的一次原子操作。

Note

总线（Bus）通俗理解就是主板上的 “高速公路”。它的硬件本质则是一组并排的导线，通过这组导线，连接 CPU 内部各部分或连接 CPU 和外设。

总线分为数据总线（传数据）、地址总线（告诉内存我要读哪一个单元）和控制总线（读还是写）。

Note

原子操作（Atomic Operation）通俗理解就是，要么做完，要么完全不做，中间绝不允许被打断的操作。

在 ARM 中，单条读写指令通常是原子的，但 “读-改-写” 三步操作默认不是原子的，需要特殊指令（ldrex / strex）保证。

1. 物理本质#

在 ARM 状态下（Cortex-A7 上电默认状态），每一条指令都是严格的 32 位（4 字节）二进制码。

与 x86（变长指令）不同，ARM 的定长指令让译码器设计更加简洁高效。一条典型的 ARM 指令在物理电路上被切割为以下结构：

Terminal window

1
Instruction = [Codition Code (4 bits)] + [OpCode & Flags] + [Operands (Registers/Immediates)]

1.1 核心差异：条件执行（Conditional Execution）#

这是 ARM 架构最吸引人的设计之一。几乎每一条指令的高 4 位（Bits 31-28）都是条件码。这意味着：任何指令都可以是条件跳转指令的变体。

条件后缀	标志位要求（CPSR）	解释	汇编举例	C 语言映射
eq	`Z == 1`	Equal（相等）	`addeq r0, r1, r2` （如果相等，则相加）	`if (a == b)`
ne	`Z == 0`	Not Equal（不想等）	`movne r0, #1` （如果不等，则赋值）	`if (a != b)`
al	Ignored	Always（默认）	`add r0, r1, r2` （指令不写后缀默认就是 AL）	（无条件执行）
gt/lt		大于 / 小于	`subgt ...`	`>` 或 `<`

2. 寄存器模型#

在执行指令前，必须知道指令操作的对象。I.MX6ULL 是 Load/Store 架构。

原则：ALU（算术逻辑单元）只能处理通用寄存器中的数据。
即不能对内存里的变量做运算，必须：搬运到寄存器 →\rightarrow→ 计算 →\rightarrow→ 搬回内存。

I.MX6ULL 有 16 个核心寄存器（R0-R15）：

R0-R12：通用寄存器。
R13（SP）：栈指针（当前的内存栈顶）。
R14（LR）：链接寄存器（保存函数调用的返回地址）。
R15（PC）：程序计数器（指向当前正在取指的地址）。修改 PC 就是跳转。

在 ARM 开发中，寄存器最重要的属性是它的 AAPCS 角色（ARM Architecture Procedure Call Standard）。这决定了编译器如何使用它们。

寄存器	别名	硬件功能	AAPCS	谁负责保存？
R0	a1	通用	参数 1 / 返回值	调用者（Caller）
R1	a2	通用	参数 2 / 返回值（64 位时）	调用者（Caller）
R2	a3	通用	参数 3	调用者（Caller）
R3	a4	通用	参数 4	调用者（Caller）
R4	v1	通用	局部变量	被调用者（Callee）
R5	v2	通用	局部变量	被调用者（Callee）
R6	v3	通用	局部变量	被调用者（Callee）
R7	v4	通用	局部变量（在 Thumb 模式下常用做栈帧指针）	被调用者（Callee）
R8	v5	通用	局部变量	被调用者（Callee）
R9	v6/SB	通用	局部变量（静态基址，平台相关）	被调用者（Callee）
R10	v7	通用	局部变量	被调用者（Callee）
R11	v8/FP	通用	帧指针（Frame Pointer）	被调用者（Callee）
R12	IP	通用	过程调用中间寄存器（Intra-Procedure-call scratch）	调用者（Caller）
R13	SP	栈指针	指向当前栈顶（Stach Pointer）	-
R14	LR	链接寄存器	保存函数返回地址（Link Register）	-
R15	PC	程序计数器	指向取指地址（Program Counter）	-

除此之外还有两个非常重要的特殊状态寄存器 CPSR 和 SPSR。

寄存器	全称	解释	关键位域
CPSR	Current Program Status Register	当前程序状态寄存器	N, Z, C, V（条件标志位） I, F（中断屏蔽位） Mode（运行模式位：User, SVC, IRQ 等）
SPSR	Saved Program Status Register	备份程序状态寄存器	仅在异常模式下存在当中断发生时，硬件自动把 CPSR 里的值拷贝到 SPSR 当中断返回时，再从 SPSR 恢复到 CPSR

ARMv7-A 实际上不止上述的 18 个寄存器，还有影子寄存器（Banked Registers）。

2.1 为什么要区分调用者保存和被调用者保存？#

简单来说，这是 ARM 官方制定的规范，叫做 AAPCS（Procedure Call Standard for the ARM Architecture，ARM 架构过程调用标准）。ARM 公司不仅设计 CPU 硬件架构，还定义了软件应如何与这些硬件交互的 ABI（Application Binary Interface，应用程序二进制接口）。

制定这一规范的核心目的在于统一标准。它确保了二进制层面的兼容性——无论代码是使用 GCC 还是 ARM Compiler 编译的，只要遵循 AAPCS，它们就能无缝协作。你无需担心不同编译器在参数传递或堆栈管理上的差异，从而可以放心地调用第三方提供的预编译库。

当 Caller 调用 Callee 时，参数通过 R0-R3 传递。调用结束后，返回值通常保存在 R0 或 R0-R1 中。这就带来了一个问题：Callee 执行时不可避免地会使用寄存器，Caller 如何确保自己的数据不被覆盖？

AAPCS 为此制定了明确的规范：

易失性寄存器（Volatile Registers, R0-R3, R12）：AAPCS 规定 Callee 可以随意修改它们。因此，如果 Caller 在 R0-R3 中存放了重要数据且在调用后仍需要使用，Caller 必须自己负责在调用前将它们压栈保存（Caller-saved）。
非易失性寄存器（Non-volatile Registers, R4-R11）：AAPCS 规定 Callee 必须保证函数返回时，这些寄存器的值与进入函数时完全一致。如果 Callee 内部需要使用 R4-R11，Callee 必须负责先将其压栈保存，并在返回前恢复（Callee-saved）。这样 Caller 就可以放心地将关键数据放在这里，无需担心被篡改。

上述规则解决了函数间的协作问题，但中断（Interrupt）打破了这种默契。中断是异步突发的，主程序（Caller）根本不知道何时会被打断，因此无法预先保存 R0-R3 等易失性寄存器。

为了解决这个问题，ARM Cortex-M 架构引入了硬件压栈（Hardware Stacking）机制。当 CPU 响应中断时，硬件会自动将 Caller 上下文（包括 R0-R3、R12、LR、PC 和 xPSR）。这一过程无需软件干预。

因此，进入中断服务函数（ISR）后，寄存器已经被硬件保护好了。ISR 此时只需像普通函数一样，遵守 AAPCS 规则处理 R4-R11（即如果用到则保存）即可。这种硬件机制极大降低了中断延迟，也简化了软件设计。

2.2 R12（IP）是干什么的？#

它是一个被很多人容易忽略的寄存器，主要用于链接器（Linker）插入的代码。当你的程序非常大，bl target 跳转的目标太远（超过 ±32MB\pm 32\text{MB}±32MB）时，bl 指令够不着。此时，链接器会自动插入一段小代码（Veneer/Trampoline），先跳转到 R12 指向的中转站，再由 R12 赋值给 PC 进行长跳转。

2.3 R15（PC）为什么有 +8 现象？#

在 ARM 状态（32 位指令）下，读取 PC 的值，通常是当前指令地址 + 8。这则是因为 CPU 的流水线（Pipeline）设计，当 CPU 执行当前指令时，取指单元已经在取下下条指令了（当前指令地址 +8 地址处）。

3. 指令集讲解#

3.1 数据处理指令（Data Processing）#

Note

核心逻辑：ALU 运算，结果写回寄存器，并可选更新 CPSR（如果指令后加 s，如 adds）

3.1.1 算术类#

指令	解释	汇编举例	C 语言映射
`add` (Add)	加法。	`add r0, r1, r2` (`R0 = R1 + R2`)	`a = b + c;`
`sub` (Subtract)	减法。	`sub r0, r1, #1` (`R0 = R1 - 1`)	`a = b - 1;`
`rsb` (Reverse Substract)	逆向减法。用于 R0 = 常数 - Rx 的场景。	`rsb r0, r1, #0` (`R0 = 0 - R1`)	`a = -b;`
`adc` (Add with Carry)	带进位加法。用于实现 64 位加法的高 32 位运算。	`adc r0, r1, r2` (`R0 = R1 + R2 + Carry`)	`(long long )a + (long long)b` 的高位部分
`sbc` (Subtract with Carry)	带借位减法。用于 64 位减法。	`sbc r0, r1, r2` (`R0 = R1 - R2 - !Carry`)	64 位减法的高位部分
`mul` (Multiply)	32 位乘法（结果取低 32 位）	`mul r0, r1, r2` (`R0 = R1 * R2`)	`int a = b * c;`
`mla` (Multiply Accumulate)	乘法运算。 DSP 算法核心指令。	`mul r0, r1, r2, r3` (`R0 = R1 * R2 + R3`)	`a = (b * c) + d;`
`udiv` (Unsigned Divide)	无符号除法。	`udiv r0, r1, r2`	`unsigned a = b / c;`
`sdiv` (Signed Divided)	有符号除法。	`sdiv r0, r1, r2`	`int a = b / c;`

3.1.2 逻辑类#

指令	解释	汇编举例	C 语言映射
`and` (Logical AND)	按位与。常用于提取某几位。	`and r0, r1, #0xff`	`a = b & 0xff;`
`orr` (Logical OR)	按位或。常用于置位（设为 1）。	`orr r0, r0, #(1<<3)`	`r0
`eor` (Exclusive OR)	按位异或。常用于翻转某几位。	`eor r0, r0, #1`	`a = b ^ 1;`
`bic` (Bit Clear)	位清除。 `and` 的反向操作：`dest = op1 and (not op2)`	`bic r0, r0, #(1<<3)`	`r0 &= ~(1 << 3);`

3.1.3 数据搬运#

指令	解释	汇编举例	C 语言映射
`mov` (Move)	寄存器间传值，或立即数赋值。	`mov r0, r1`	`a = b;`
`mvn` (Move Not)	按位取反后传送。	`mvn r0, #0` (`r0 = 0xffffffff`)	`a = ~0;`

Warning

ARM 指令是定长 32 位的。除去操作码和条件码，留给立即数的空间只有 12 位。并且这 12 位还不是直接存数字，而是被拆分位 8 位常数 + 4 位循环右移。

这就意味着在向寄存器写入某些立即数时，例如 mov r0, #0x12345678 是会失败的，因为 0x12345678 这个立即数太乱了，无法通过 8 位常数 + 4 位循环右移凑出来。

解决办法是使用 ldr r0, =0x12345678。此时，汇编器会悄悄在代码段的末尾（Literal Pool）找个地方放 0x12345678，然后把这条指令翻译成去那个地址读数据。

3.1.4 比较指令#

Note

不保存运算结果，只更新 CPSR 的标志位（N, Z, C, V），为后面的条件执行做铺垫。

指令	解释	汇编举例	C 语言映射
`cmp` (Compare)	本质是 `sub`。比较大小。	`cmp r0, #5` (`r0 - 5`，更新 Z 标志位)	`if (a >= 5)`
`tst` (Test)	本质是 `and`。测试某位是否为 1。	`tst r0, #(1<<3)` (`r0 & 0x8`，更新 Z 标志位)	`if (a & (1<<3))`
`teq` (Test Equivalence)	本质是 `eor`。测试两个数是否相等（不影响进位标志）。	`teq r0, r1`	常用于汇编手写检查

3.1.5 桶形移位器（Barrel Shifter）#

在 ARM 中，移位操作不是独立指令，而是数据进入 ALU 之前的预处理。它是免费的。指令 add r0, r1, r2, lsl #2 的物理含义是：

R0=R1+(R2≪2)\text{R0} = \text{R1} + (\text{R2} \ll 2)R0=R1+(R2≪2)

这在单周期内完成，这就是为什么 ARM 处理数组索引（地址 = 基址 + 索引 ×\times× 4）特别快。

模式	物理动作	C 标志位更新	数学含义	C 语言映射	典型应用场景
`lsl` (Logical Shift Left)	左移。低位补 0，高位移出	最后移出的位	×2n\times 2^n×2n	`x << n`	乘法优化、位字段对齐、生成掩码
`lsr` (Logical Shift Right)	右移。高位补 0，低位移出	最后移出的位	/2n/2^n/2n （无符号）	`(unsigned)x >> n`	无符号数除法、读取特定位段
`asr` (Arithmetic Shift Right)	算术右移。高位补符号位，低位移出	最后移出的位	/2n/2^n/2n （有符号）	`(signed)x >> n`	有符号数除法
`ror` (Rotate Right)	循环右移。低位移出后，填补到高位	最后移出的位	-	`(x >> n)	(x << (32-n))`
`rrx` (Rotate Right with Extend)	带扩展循环右移。 33 位循环（32 位寄存器 + 1 位 Carry）	寄存器移出的 LSB	-	无	大数运算、多精度算术

3.2 内存访问指令（Memory Access）#

这是 CPU 与外部世界（DDR 内存、GPIO 控制器等）交互的唯一桥梁。

3.2.1 单寄存器#

指令	解释	汇编举例	C 语言映射
`ldr` (Load Register)	从内存读 4 字节到寄存器。	`ldr r0, [r1]`	`r0 = *r1;`
`str` (Store Register)	把寄存器的值写入内存 4 字节。	`str r0, [r1]`	`*r1 = r0;`
`ldrb` (8 bit) (Load Byte)	读 1 字节，高 24 位补零。	`ldrb r0, [r1]`	`r0 = (unsigned char)*r1;`
`ldrh` (16 bit) (Load Halfword)	读 2 字节，高 16 位补零。	`ldrh r0, [r1]`	`r0 = (unsigned short)*r1;`
`ldrsb` (Load Signed Byte)	读 1 字节，高 24 位补符号位。	`ldrsb r0, [r1]`	`r0 = (char)*r1;`
`ldrsh` (Load Signed Halfword)	读 2 字节，高 16 位补符号位。	`ldrsh r0, [r1]`	`r0 = (short)*r1;`

3.2.2 寻址模式#

寻址模式	汇编举例	C 语言映射	状态
立即数偏移（Offset）	`ldr r0, [r1, #4]`	`r0 = *(r1 + 1);`	`r1` 保持不变
前索引（Pre-indexed）	`ldr r0, [r1, #4]!`	`r0 = *(++ptr);`	`r1` 在访问内存前更新为 `r1 + 4`
后索引（Post-indexed）	`ldr r0, [r1], #4`	`r0 = *(ptr++);`	访问内存后，`r1` 更新为 `r1 + 4`

3.2.3 多寄存器#

Note

这是 ARM 实现栈（Stack）和上下文切换（Context Switch）的基石。

指令	解释	汇编举例	场景
`ldm` (Load Multiple)	内存 →\rightarrow→ 多个寄存器。	`ldm r0, {r4-r6, pc}`	恢复现场并返回
`stm` (Store Multiple)	多个寄存器 →\rightarrow→ 内存。	`stm r0, {r4-r6, lr}`	保存现场

说明：

ldm r0, {r4-r6, pc}：从以 r0 为基址的内存地址开始，依次加载数据到寄存器 r4、r5、r6 和 pc。
stm r0, {r4-r6, lr}：从寄存器 r4、r5、r6 和 lr 中，依次将数据存储到以 r0 为基址的内存地址。

后缀模式#

虽然有 ia、ib、da 和 db 四种，但 ARM 官方推荐在操作栈时使用别名，方便记忆：

stmfd (Full Descending) = stmdb (Decrement Before)：入栈（压栈）。
ldmfd (Full Descending) = ldmia (Increment After)：出栈。
push {reglist} 等价于 stmdb sp!, {reglist}。
pop {reglist} 等价于 ldmia sp!, {reglist}。

3.3 分支与控制流（Branch & Control）#

打破顺序执行，实现 if、for、function call。

指令	解释	汇编举例	C 语言映射
`b` (Branch)	相对跳转（范围 ±32MB\pm 32\text{MB}±32MB）	`b label`	`goto label;`
`bl` (Branch with Link)	带连接跳转。保存下一条指令地址到 `lr`。	`bl func`	`func();`
`bx` (Branch Exchange)	跳转并根据目标地址最低位切换状态（ARM →\rightarrow→ Thumb）。	`bx lr`	`return;`（函数返回）
`blx` (Branch Link Exchange)	`bl` + `bx` 的结合。调用不同指令集的函数。	`blx r0`	函数指针调用

Note

还可以直接修改 PC 寄存器实现跳转，例如 mov pc, lr，这是函数返回的底层实现。

3.4 系统与状态指令（System & Status）#

这部分在使用上层语言实现业务逻辑时几乎看不到，但是对于操作系统而言至关重要。

3.4.1 状态寄存器访问#

指令	解释	汇编举例	场景
`mrs` (Move Register from Status)	读取 CPSR/SPSR 到通用寄存器。	`mrs r0, cpsr`	读取当前中断状态
`msr` (Move Status from Register)	将通用寄存器写会 CPSR/SPSR。	`msr cpsr_c, r0`	开/关中断

3.4.2 异常与中断生成#

指令	解释	场景
`svc` (Supervisor Call)	软中断。 CPU 进入 SVC 模式。 Linux 中用于从用户态（User）陷入内核态（Kernel）。	系统调用（`open`，`read` 等）。
`bkpt` (Breakpoint)	断点指令。执行到此时 CPU 暂停并通知调试器。	JTAG/GDB 调试。

3.4.3 协处理器指令#

I.MX6ULL 中，CP15 协处理器控制着 MMU、Cache 和中断向量表基地址。

指令	解释	助记法
`mcr` (Move to Coprocessor from Register)	CPU →\rightarrow→ CP15 （写配置）	R（Register）在最后，表示源
`mrc` (Move to Register from Coprocessor)	CP15 →\rightarrow→ CPU （读状态）	C（Coprocessor）在最后，表示源

例如：mcr p15, 0, r0, c1, c0, 0（开启 MMU）。

Note

协处理器（Coprocessor）时依附于 CPU 主核的独立电路单元。ARM 主核（ALU）只管算逻辑和搬砖，像 MMU（内存映射管理）、Cache 配置这些脏活累活，都丢给 CP15 协处理器；浮点运算丢给 CP10/CP11。

3.4.4 内存屏障（Memory Barriers）#

指令	解释	场景
`dmb` (Data Memory Barrier)	确保指令前的内存访问在指令后的内存访问之前完成。	操作 DMA 描述符时
`dsb` (Data Synchronization Barrier)	比 DMB 更强。确保前面的访存全部完成，CPU 才会执行下一条指令。	修改页表后
`isb` (Instruction Synchronization Barrier)	冲刷流水线。确保重新取指。	修改了代码段或中断向量表后

3.5 同步与原子操作（Synchronization）#

对于多任务操作系统，需要处理竞态条件。

指令	解释	C 语言映射
`ldrex` (Load Register Exclusive)	读取并设置独占监视器	`atomic_load` (C11)
`strex` (Store Register Exclusive)	如果监视状态未被破坏，则写入。返回 0 成功，1 失败。	`atomic_compare_exchange` (C11)
`clrex` (Clear Exclusive)	清除监视器状态。	上下文切换时清理残余状态

Note

ARM 没有 x86 的 lock 总线锁，它使用 “独占监视器” 硬件。

ldrex 读取数据的同时标记该地址为 “被我监视”。
strex 尝试写入。如果期间没有其他核心 / DMA 修改过该地址，写入成功；否则写入失败。

这会实现 mutex（互斥锁）和 semaphore（信号量）的基石。

Note

互斥锁（Mutex）& 信号量（Semaphore）：

互斥锁（厕所钥匙）：只有一个资源（厕所）。你拿了钥匙进去锁门，别惹只能在门口排队（阻塞），直到你出来还钥匙。用户保护临界区。
信号量（餐厅叫号）：有 NNN 个资源（空桌子）。来一个人 N−1N-1N−1，走一个人 N+1N+1N+1。当 N=0N=0N=0 时，新来的人必须等到。

这两个都是软件概念，但底层必须由原子指令支持。

如何将 WSL2 镜像无损迁移至非系统盘

Sat, 14 Mar 2026 05:16:00 GMT

1 引言#

随着开发环境的日益庞大，默认安装在 C:\ 盘的 WSL2 (Windows Subsystem for Linux) 镜像体积也会不断膨胀。本文将分享如何通过命令行操作，将 WSL 迁移至 E:\ 盘乃至其他盘符，彻底释放系统盘空间。

1.1 笔者环境#

名称	版本
Windows 11 Pro	25H2 26200.8037
PWSH	7.5.5
WSL	2.6.3.0
Ubuntu	22.04 LTS
Ubuntu	24.04 LTS

Note

注意：这里的 PWSH 并不是指 Windows 系统内置的经典 PowerShell，而是跨平台的开源项目 PowerShell Core。下文中使用 PowerShell 指代系统默认版本，PWSH 指代开源版本。

2 准备工作#

2.1 确认当前安装状态#

如果你还没有安装镜像，或想查看当前支持的发行版，可以使用以下命令：

Terminal window

1
# 查看支持的在线发行版
2
wsl --list --online
3

4
# 安装 Ubuntu 镜像
5
wsl --install Ubuntu-22.04
6
wsl --install Ubuntu-24.04

在终端输入以下命令，查看当前已安装的发行版：

Terminal window

1
wsl -l -v

2.1 确定原镜像及目标路径#

WSL2 的虚拟磁盘文件通常为 ext4.vhdx。你可以使用强大的文件搜索工具 Everything 来定位它们。不同版本的 Ubuntu 默认安装路径可能略有不同。

镜像	原始路径
Ubuntu 22.04 LTS	`C:\Users\<your_windows_username>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu22.04LTS_...\LocalState`
Ubuntu 24.04 LTS	`C:\Users\<your_windows_username>\AppData\wsl\{UUID}`

可以看到这里两者的路径有着细微差别，Ubuntu 22.04 LTS 安装在 Local\Packages 下，而 Ubuntu 24.04 LTS 却安装在 Local 同级的 wsl 下。

具体原因犹未可知，笔者暂时没有时间去查阅官方文档，但是并不影响后续步骤以及日常使用。

2.2 建立新的位置#

在上一步中已经获取到了原始的位置，根据笔者的风格，迁移之后的镜像路径应该尽可能维持原来的目录结构，但是笔者还是做了一点细微的修改，迁移路径具体如下：

镜像	迁移路径
Ubuntu 22.04 LTS	`E:\Users\<your_windows_username>\AppData\wsl\ubuntu2204`
Ubuntu 24.04 LTS	`E:\Users\<your_windows_username>\AppData\wsl\ubuntu2404`

Warning

请在后续的命令行中将 <your_windows_username> 替换为你的实际 Windows 用户名。

在新版的 PWSH 中可以直接使用以下命令创建目录：

Terminal window

1
mkdir -p E:\Users\<your_windows_username>\AppData\wsl\ubuntu2204\
2
mkdir -p E:\Users\<your_windows_username>\AppData\wsl\ubuntu2404\

或者以下命令（支持在 PowerShell 中使用）：

Terminal window

1
New-Item -Path E:\Users\<your_windows_username>\AppData\wsl\ubuntu2204\ -ItemType Directory
2
New-Item -Path E:\Users\<your_windows_username>\AppData\wsl\ubuntu2404\ -ItemType Directory

3 迁移镜像#

3.1 导出原 WSL 分发#

在进行导出操作前，强烈建议先停止 WSL2 中的所有工作并彻底关闭所有正在运行的 WSL 实例以防止数据损坏：

Terminal window

1
wsl --shutdown

接着，将现有的系统状态导出为 .tar 压缩包：

Terminal window

1
wsl --export Ubuntu-22.04 E:\Users\<your_windows_username>\AppData\wsl\ubuntu2204.tar
2
wsl --export Ubuntu-24.04 E:\Users\<your_windows_username>\AppData\wsl\ubuntu2404.tar

3.2 将压缩包导入新位置#

使用 wsl --import 命令将刚才导出的 .tar 文件导入到我们在 E 盘创建的新目录中。为了方便区分，我们将导入后的新实例命名为小写的 ubuntu2204 和 ubuntu240：

Terminal window

1
wsl --import ubuntu2204 E:\Users\<your_windows_username>\AppData\wsl\ubuntu2204 E:\Users\amara\AppData\wsl\ubuntu2204.tar
2
wsl --import ubuntu2404 E:\Users\<your_windows_username>\AppData\wsl\ubuntu2404 E:\Users\amara\AppData\wsl\ubuntu2404.tar

Note

利用 wsl --import，你可以将同一个 .tar 包导入多次并赋予不同名称，从而实现多开同一个发行版。虽然在隔离环境方面类似于 Docker，但 WSL2 原生支持 WSLg，可以直接运行 Linux 图形化应用，这在某些桌面开发场景下比 Docker 更具优势。

3.3 恢复默认用户#

导入完成并启动新的分发后，你可能会发现默认登录用户变成了 root。我们需要将其改回你原本的 Linux 用户名。如果你的分发并没有发现此类问题，可以跳过本节。

进入新的 WSL 实例：

Terminal window

1
wsl ~ -d ubuntu2204

使用 nano 编辑器修改 WSL 配置文件（如果你更习惯图形化界面，也可以执行 apt update && apt install gedit -y 后使用 gedit）：

Terminal window

1
sudo nano /etc/wsl.conf

在文件中添加或修改以下内容（将 <your_linux_username> 替换为你在 WSL 中的用户名）：

1
[user]
2
default=<your_linux_username>

保存并退出：依次按下 Ctrl + X，输入 Y 确认保存，最后按 Enter 退出。

退出当前 WSL 会话，并在 Windows 终端中重启改实例使配置生效：

Terminal window

1
# 终止实例
2
wsl --terminate ubuntu2204
3
# 重新进入验证用户是否恢复正常
4
wsl ~ -d ubuntu2204

3.4 设置为默认分发并清理善后#

如果一切验证无误，将新的实例设置为系统的默认 WSL 分发：

Terminal window

1
wsl --set-default ubuntu2404

确认无误后，就可以卸载 C 盘中的旧分发了：

Terminal window

1
wsl --unregister Ubuntu-22.04
2
wsl --unregister Ubuntu-24.04

最后，删除存放在 E 盘的过渡文件 .tar 压缩包以释放空间。此时再次执行 wsl -l -v，你应该能看到干净清爽的列表了。

4 总结#

迁移安装最大的好处就是能显著减小 C 盘的存储压力。不过，如果你的物理磁盘总容量本身较小（比如只有 512GB 单盘），笔者依然更推荐直接重装系统并只保留一个 C 盘分区，统一管理存储空间。

此外，根据微软官方文档的建议，为了获得最佳的文件 I/O 性能，进行 Linux 相关的开发时，请务必将项目文件直接存储在 WSL 的 Linux 文件系统（如 ~ 目录下），而不是跨文件系统存储在 Windows 盘符（如 /mnt/c）中。

参考资料#

C++ 中的 stack

Thu, 19 Feb 2026 02:45:00 GMT

要真正理解栈这种结构，意味着我们要剥离事物表象，追究其最本质的问题，即我们到底面临什么样的数据处理需求，才导致了 “栈” 这种结构的诞生？

我们不需要把栈仅仅看作是教科书上的定义，而是把它看作是为了解决特定时序问题而设计的一种 “受限” 模型。

1. 什么是栈？#

从本质上来说，计算机处理任务通常有两种模式：

并行/随机：所有任务都在桌面上铺开，想拿哪个拿哪个（类似数组或哈希表）。
嵌套/依赖：任务 B 必须依赖任务 A 的环境，任务 C 又依赖 B。要完成 A，必须先挂起 A 去做 B；要做 B，必须先挂起 B 去做 C。

栈（Stack）就是为了解决第二种模式而诞生的。

1.1 核心定义：LIFO#

栈是一种线性表，但它是一种受限的线性表。它的核心逻辑是后进先出（Last In, First Out - LIFO）。

你可以把它想象成叠盘子：

压入（Push）：你只能把新盘子放在最上面。
弹出（Pop）：你只能取走最上面的盘子。
查看（Top/Peek）：你只能看到最上面盘子的花纹，无法直接看到底部的盘子。

生活中的栈模型：想要拿到底部的盘子，必须先移走顶部的盘子

1.2 为什么它是 “受限” 的？#

数组（Array）允许你访问 index[0] 也可以访问 index[100]。栈为什么要把这种能力 “阉割” 掉？

答案就是为了强制秩序。

通过限制 “只能操作顶部”，栈强制程序员必须按照严格的 “原路返回” 逻辑来处理数据，从而消除了随机访问带来的复杂性和潜在错误。

2. 为什么需要栈？#

如果计算机世界没有栈，很多基础逻辑就会崩塌。我们需要栈，是因为它是保存上下文（Context）和实现回朔（Backtacking）最自然的模型。

2.1 函数调用（The Call Stack）#

这是栈存在最底层、也最不可或缺的原因。

从本质上来说，CPU 在执行代码时是个高度专注的执行机器，它完全依赖程序计数器（PC, Program Counter）来决定下一步跑哪条指令。当代码从 main() 跳转到 func_a() 时，本质上是强行修改了 PC 寄存器的值。随之而来的致命问题是：当 func_a() 跑完，CPU 怎么知道该跳回 main() 里的哪一行继续执行？

你可能会想，用一个专门的寄存器（比如链接寄存器 LR）把返回地址保存起来不就行了？

在只有单层调用的情况下，这确实可行。但现实是，代码中充满了嵌套调用：main() 调用了 func_a()，而 func_a() 中又调用了 func_b()。如果只依赖单一寄存器，当调起 func_b() 时，新的返回地址回无情地覆盖掉之前 func_a() 的返回地址。等到 func_b() 执行结束，程序就再也找不到回 main() 的路了。

此外，函数不仅需要记住 “从哪儿来”，还要保护好自己的 “现场”。每个函数都有自己的局部变量，执行时还会征用各种通用寄存器。在跳入下一个函数前，当前的这些状态（Context）必须被原封不动地保存下来。

由于函数调用的逻辑是绝对的 “嵌套与回溯”——最后被调用的 func_b() 必须最先执行完毕并交出控制权，func_a() 才能继续，做后才轮到最外层的 main()。这种 “后出发的先结束，先出发的最后兜底” 的生命周期，与 LIFO (Last-In, First-Out) 结构严丝合缝。

所有，系统在内存中专门开辟了调用栈（Call Stack）。每次进入新函数，就把它的返回地址、局部变量和寄存器状态打包成一个栈帧（Stack Frame）压入栈顶；函数一结束，就将栈顶弹出，完美恢复上一层函数的现场。没有栈，现代编程语言的函数嵌套和递归机制就根本无法实现。

调用栈示例：如果子程序 DrawSquare 调用了 DrawLine，DrawLine 的栈帧就会被压入栈顶（如图中绿色部分所示）。栈指针（Stack Pointer）始终指向最新的栈顶位置

2.2 递归（Recursion）#

既然函数调用依赖栈来保存上下文，那么递归可以说是把栈的这种特性压榨到了机制。

使用海龟绘图（Turtle Graphics）递归绘制谢尔宾斯基三角形（Sierpinski triangle）的过程

从人类的思维来看，递归是自己调用自己，但在 CPU 和内存眼里，根本没有 “同一个函数” 的概念。对于计算机而言，不管是 func_a() 调用 func)b()，还是 func_a() 调用 func_a()，动作是完全一样的——仅仅是 PC（程序计数器）指针跳转，并在内存中开辟一个新的栈帧。

假设我们在写一个计算阶乘的递归函数（fact(n)）。当 func(3) 内部调用 fact(2) 时，此时的局部变量 n=3 必须被冻结并保护起来。如果没有栈 fact(2) 内部的变量就会直接覆盖掉原来 n=3 的内存空间。等到递归触底反弹时，程序根本想不起最初传入的参数是什么。

得益于栈的 LIFO 机制，每一次自我调用，系统都会把当前的参数、局部变量和返回地址像叠盘子一样压入（Push）栈中。不管向下深挖了多少层，每一层的数据都被独立且安全地封存在自己的栈帧里。当遇到终止条件（Base Case）开始回归时，栈再一层层弹出（Pop），精准地恢复每一层的现场。可以说，栈时递归能够成立的物理载体。

当然，如果嵌套层数过深导致栈空间耗尽，就会引发经典的 Stack Overflow 栈溢出。

2.3 状态撤销（Undo）与历史回溯#

你在编辑器里敲击键盘，后者在设计软件中画图，想要按下 Ctrl + Z 撤销刚刚的失误。

人类的时间是线性向前的，但 “撤销” 操作要求我们能够逆转时间。这种逆转不是随机的，而是必须严格遵守 “最近发生的事情，最先被抹去” 的自然法则。你最后敲下的那一个字符，必须是第一个被删除的。

所以，这里的历史记录被抽象成了一个栈：

入栈（Push）：每当你执行一个操作（比如输入字符、改变颜色、移动光标），系统就会把这个动作的 “状态快照” 或 “增量数据” 打包，压入历史记录栈的栈顶。
出栈（Pop）：当年你触发撤销（Undo）时，系统直接从栈顶取回最后一次保存的状态，并将其弹出，界面随之恢复到上一个时刻。

没有栈这种 “后进先出” 的模型，系统就无法建立起具有时间顺序的后悔药机制。任何需要 “原路” 返回的场景（比如浏览器的 “后退” 按钮、迷宫算法的回溯路径），其背后的灵魂数据机构都是栈。

2.4 符号匹配与语法解析#

编译器在编译代码时，或者解析器在处理一段复杂公式时，需要检查代码中的 { [ ( ) ] } 括号是否成对闭合、合法嵌套。

编译器阅读代码的顺序是从左到右的单向扫描。但在代码的世界里，最晚开启的作用于，必须最早被关闭。这种一种典型的 LIFO 结构需求。

面对一长串括号，系统处理的算法极其优雅，完全依赖栈来实现：

扫描与入栈：逐个字符读取，只要遇到 “左括号”（如 {、[、(），不管三七二十一，直接压入栈中。这代表着进入了一个新的层级，正在等待它的结束。
匹配与出栈：一旦遇到 “右括号”（如 )、]、}），此时立刻去查看栈顶元素。如果栈顶正好是能与它匹配的左括号，说明当前最内层的逻辑闭环了，于是将栈顶弹出，继续往下走。

利用栈进行括号匹配的逻辑：左括号入栈，右括号消栈，最后栈空则合法

如果遇到右括号时栈是空的（说明没有多余的左括号等待闭合），或者栈顶的左括号类型不匹配（比如 { 遇到了 ]），那么编译器就可以立刻抛出 Syntax Error（语法错误）。当整个文件扫描完，如果栈里面还有残留的左括号，说明有作用域没关上。

利用栈，编译器不仅能判断对错，还能精准定位到哪一层的括号出了问题。

3. C++ STL 中的 `std::stack`#

在 C++ 标准模板库（STL）中，std::stack 被设计得非常精妙。它不是一个从零开始写的容器，而是一个容器适配器（Container Adapter）。

3.1 什么是 “容器适配器”？#

std::stack 本身不直接管理内存，它更像是一个外壳。它内部包裹着另一个真正的容器（比如 std::vector、std::deque 后 std::list）。

它屏蔽了底层容器的随机访问结构（如 []），只暴露 push、pop、top 等接口，从而强制你遵守栈的规则。

3.2 核心语法与操作#

在使用前需包含头文件：

1
#include <stack>

基本操作（时间复杂度均为 O(1)O(1)O(1)）。

操作	函数	描述	注意事项
入栈	`push(val)`	将元素拷贝到栈顶	设计拷贝/移动构造
原地构造	`emplace(args)`	在栈顶直接构造元素	推荐，比 `push` 更高效，省去拷贝
出栈	`pop()`	移除栈顶元素	返回值为 `void`，不返回被移除的元素
查看	`top()`	返回栈顶元素的引用	如果栈为空调用此函数回导致未定义行为（通常崩溃）
判空	`empty()`	栈为空返回 `true`	操作前务必检查
大小	`size()`	返回元素数量	-

Push 操作将元素压入栈顶，Pop 操作移除栈顶元素，两者都不能触及栈底

3.3 为什么 C++ 的 `pop()` 不返回元素？#

在很多其他语言（如 Java, Python）中，pop() 会移除并返回栈顶元素。但在 C++ STL 中，pop() 是 void，你需要先 top() 获取值，再 pop() 移除。

究其原因是异常安全（Exception Safety）。

如果 pop() 函数即移除元素又返回元素（按值返回），在返回过程中如果发生了拷贝构造异常（比如内存不足），那么这个元素即从栈里丢了，又没能成功交给调用者，导致数据永久丢失。

将 top() 和 pop() 分离是 C++ 追求安全的体现。

4. 算法题实战#

点击题目即可跳转。

4.1 洛谷：B3614【模板】栈 #

1
#include <iostream>
2
#include <cstdint>
3
#include <string>
4

5
using namespace std;
6

7
const uint64_t N = 10e6 + 1;
8
uint64_t stk[N] = {0};
9
uint64_t top_idx = 0; // 栈顶指针，指向栈顶元素的下一个位置
10

11
int main(void) {
12
    uint64_t t = 0;
13
    cin >> t; // 数据组数
14

15
    while (t--) {
16
        top_idx = 0; // 每组数据都清空栈
17
        uint64_t n = 0; // 操作的次数
18
        cin >> n;
19

20
        while (n--) {
21
            string operation;
22
            uint64_t x = 0;
23
            cin >> operation;
24

25
            if ("push" == operation) {
26
                cin >> x;
27
                stk[top_idx++] = x;
28
            } else if ("pop" == operation) {
29
                if (0 == top_idx) {
30
                    cout << "Empty" << endl;
31
                } else {
32
                    --top_idx;
33
                }
34
            } else if ("query" == operation) {
35
                if (0 == top_idx) {
36
                    cout << "Anguei!" << endl;
37
                } else {
38
                    cout << stk[top_idx - 1] << endl;
39
                }
40
            } else if ("size" == operation) {
41
                cout << top_idx << endl;
42
            } else {
43
                continue;
44
            }
45
        }
46
    }
47

48
    return 0;
49
}

展开收起

4.2 力扣：20. 有效的括号 #

1
class Solution {
2
public:
3
    bool isValid(string s) {
4
        std::stack<char> stk;
5

6
        for (const char& c : s) {
7
            if ('(' == c || '[' == c || '{' == c) {
8
                stk.push(c);
9
            } else {
10
                if (stk.empty()) {
11
                    return false;
12
                }
13

14
                char top = stk.top();
15

16
                if (')' == c && '(' != top) {
17
                    return false;
18
                }
19

20
                if (']' == c && '[' != top) {
21
                    return false;
22
                }
23

24
                if ('}' == c && '{' != top) {
25
                    return false;
26
                }
27

28
                stk.pop();
29
            }
30
        }
31

32
        return stk.empty();
33
    }
34
};

展开收起

4.3 洛谷：【深基15.习9】验证栈序列 #

1
#include <iostream>
2
#include <vector>
3
#include <stack>
4

5
constexpr int N = 1000000 + 1;
6

7
int main(void) {
8
    std::vector<int> pushed(N);
9
    std::vector<int> popped(N);
10

11
    int q = 0;
12
    std::cin >> q;
13

14
    while (q--) {
15
        int n = 0;
16
        std::cin >> n;
17

18
        // 读取入栈序列
19
        for (int i = 0; i < n; i++) {
20
            std::cin >> pushed[i];
21
        }
22

23
        // 读取出栈序列
24
        for (int i = 0; i < n; i++) {
25
            std::cin >> popped[i];
26
        }
27

28
        // 模拟验证
29
        std::stack<int> stk;
30
        int popped_idx = 0;
31

32
        // 依次入栈
33
        for (int i = 0; i < n; i++) {
34
            stk.push(pushed[i]);
35

36
            while (popped_idx < n && !stk.empty() && stk.top() == popped[popped_idx]) {
37
                stk.pop();
38
                popped_idx++;
39
            }
40
        }
41

42
        // 判断
43
        if (stk.empty()) {
44
            std::cout << "Yes" << std::endl;
45
        } else {
46
            std::cout << "No" << std::endl;
47
        }
48
    }
49

50

51
    return 0;
52
}

展开收起

4.4 洛谷：P1449 后缀表达式 #

1
#include <iostream>
2
#include <stack>
3
#include <string>
4

5
int main(void) {
6
    std::stack<int> stk;
7
    std::string expression;
8
    std::string num_str;
9
    int num = 0;
10
    int result = 0;
11

12
    std::cin >> expression;
13

14
    for (const char& ch : expression) {
15
        if (ch == '@') break;
16

17
        if (std::isdigit(static_cast<unsigned char>(ch))) {
18
            num_str += ch;
19
        } else if (ch == '.') {
20
            if (!num_str.empty()) {
21
                stk.push(std::stoi(num_str));
22
                num_str.clear();
23
            }
24
        } else {
25
            int a = stk.top(); stk.pop();
26
            int b = stk.top(); stk.pop();
27
            int result = 0;
28
            switch (ch) {
29
                case '+': result = b + a; break;
30
                case '-': result = b - a; break;
31
                case '*': result = b * a; break;
32
                case '/': result = b / a; break;
33
            }
34
            stk.push(result);
35
        }
36
    }
37

38
    result = stk.top();
39

40
    std::cout << result << std::endl;
41

42
    return 0;
43
}

展开收起

4.5 洛谷：P1241 括号序列 #

1
#include <iostream>
2
#include <string>
3
#include <stack>
4
#include <vector>
5

6
bool is_match(char left, char right) {
7
    return ('(' == left && ')' == right) || ('[' == left && ']' == right);
8
}
9

10
int main(void) {
11
    std::string expression;
12
    std::cin >> expression;
13

14
    std::stack<int> stk;
15
    std::vector<bool> matched(expression.size(), false);
16

17
    for (int i = 0; i < static_cast<int>(expression.size()); ++i) {
18
        char ch = expression[i];
19
        if ('(' == ch || '[' == ch) {
20
            stk.push(i);
21
            continue;
22
        }
23

24
        if (!stk.empty() && is_match(expression[stk.top()], ch)) {
25
            matched[stk.top()] = true;
26
            matched[i] = true;
27
            stk.pop();
28
        }
29
    }
30

31
    for (int i = 0; i < static_cast<int>(expression.size()); ++i) {
32
        if (matched[i]) {
33
            std::cout << expression[i];
34
            continue;
35
        }
36

37
        if ('(' == expression[i] || ')' == expression[i]) {
38
            std::cout << "()";
39
        } else {
40
            std::cout << "[]";
41
        }
42
    }
43
    std::cout << std::endl;
44

45
    return 0;
46
}

展开收起

5. 进阶知识（底层容器的选择）#

std::stack 是一个模板类（定义在头文件 <stack>），定义如下：

1
template<class T, class Container = std::deque<T>>
2
class stack;

注意第二个参数 Container。默认情况下，C++ 使用 std::deque（双端队列）作为底层容器，而不是 std::vector。

5.1 为什么默认用 `std::deque` 而不是 `std::vector`？#

扩容代价：std::vector 在内存不足扩容时，需要把所有元素搬运到新内存块，代价较大。std::deque 是分段内存，扩容时只需分配新段，不需要搬运旧数据。
内存效率：对于大量进出的栈操作，std::deque 的内存回收和分配策略通常比 std::vector 更平滑。

std::deque 的内部结构：由中控器（Map）管理的一系列分段连续内存缓冲区，非常适合两端操作

当然，如果你确定需要极致的连续内存性能，也可以手动指定：

1
std::stack<int, std::vector<int>> stk;

参考资料#

操作系统中的进程

Mon, 26 Jan 2026 22:10:00 GMT

在计算机科学的教科书中，关于进程（Process）的定义往往只有冷冰冰的一句话：

进程是程序的一次执行过程。

这句话虽然准确，但它掩盖了太多细节。对于初学者而言，这更像是一个黑盒。为什么要有进程？为什么不能直接操作物理地址？所谓的上下文切换到底切换了什么？

要真正理解进程，我们不能只看定义，而必须回到计算机发展的历史，从本质出发，看看是怎样的资源瓶颈和物理限制，逼迫工程师们发明了进程这个概念。

0. 起点：硬件即程序#

时间背景	代表
1940s - 1950s 初	ENIAC

在进程这个概念诞生之前，计算机的世界是纯粹且静止的。如果非要为这个 “史前时代” 选一个代表，那非 ENIAC（Electroinc Numeric Numerical Integrator and Computer，电子数值计算机）莫属。在这个阶段，软件和硬件之间并没有明显界限，甚至可以说，根本没有现代意义上的“软件”。

想象一下，你面对的是一个占地 167 平方米、重达 27 吨的庞然大物。这就是 ENIAC，它是那个时代算力的巅峰，但对于 “任务管理” 而言，它确实最原始的形态：它没有任何中间层来管理资源；同一时间，这台巨兽只能为解决一个问题而存在。

早期的编程：Glen Beck 与 Betty Snyder 正在对 ENIAC 进行硬连线

在 ENIAC 上 “切换任务” 并不是像今天一样双击一个图标一样简单。那是一场体力劳动。当时的 “编程”，实际上就是 “接线”。

程序员（通常是女性数学家）需要拿着粗大的连接线（Patch Cables），在巨大的配线板上进行物理连接。每一个插孔的连接，每一排开关的拨动，都代表着指令的逻辑流向。当你把线插好，这台机器就变成了解决那个特定方程的专用电路。

操作员正在手动更改 ENIAC 的线路配置

似乎有点类似于现在的 FPGA。

既然没有操作系统，那谁来切换任务呢？那自然也只能让人来手动切换了。

ENIAC 全景：巨大的体积与原始的操作方式

在这个时期，ENIAC 的加法速度已经高达 5000 次/秒，但准备计算的过程确慢得令人发指。而正是这种极高的计算速度与极低的任务切换效率之间的巨大鸿沟，成为了推动计算机科学向前发展的原动力。

1. 第一次进化：消除人的延迟 —— 批处理系统#

时间背景	代表
1955 - 1960s 初	GM-NAA I/O（为 IBM 704 开发）

1945 年，随着 John von Neumann 在其里程碑式的著作《First Draft of a Report on the EDVAC》中正式确立了冯·诺依曼架构，程序终于从繁琐的硬件连线进化为存储在磁带上的指令。虽然这一边个消除了物理插拔线缆的需求，但在早期的 Open Shop（开放式机房）模式依然由人主导：程序员带着磁带走进机房，装带、运行、卸带、离开，然后下一个人进来。

冯·诺依曼架构：存储程序计算机的基石

当时的 CPU（如 IBM 704）如同黄金般珍贵。人的动作（装磁带、按按钮）可能需要花费几分钟，但 CPU 可能几秒钟就执行完毕。

让一台每秒运行数万次指令的 CPU 停下来等人，这是对计算资源极大的浪费。为了解决 “人太慢，CPU 等人” 的矛盾，批处理系统（Batch Processing）应运而生。

批处理系统的工作流示意图

1956 年，通用汽车（GM）的研究部门为 IBM 704 编写了 GM-NAA I/O，这被认为是世界上第一个真正意义上的操作系统。

工程师们发明了一个叫做 Monitor 监控程序的常驻小软件。它的逻辑非常简单：

它始终停留在内存的一小块区域。
它负责读取磁盘上的下一个作业（Job）。
自动加载作业 →\rightarrow→ 运行作业 →\rightarrow→ 作业结束 →\rightarrow→ 把控制权还给 Monitor →\rightarrow→ 加载下一个。

常驻监控程序 (Monitor) 的内存布局

此时，依然没有进程的概念，只有作业（Job）。内存里依然一次只住一个程序。

2. 第二次进化：消除 I/O 的延迟 —— 多道程序设计#

时间背景	代表
1960s 中期	IBM OS/360

批处理虽然解决了人的问题，但没解决硬件的问题。即使是自动运行，当程序需要读取磁带或磁盘时，由于机械设备的物理限制，I/O 操作的速度比 CPU 慢了几个数量级（毫秒 vs 微秒）。

每当程序发起 I/O 请求（比如读取数据块），CPU 就不得不停下来傻等。这种等待在 CPU 眼里是极其漫长的。

为了解决 “I/O 太慢，CPU 等 I/O” 的矛盾，多道程序设计（Multiprogramming）横空出世。IBM 在其传奇的 Systen/360 大型机上大力推行这一概念。

IBM System/360 Model 30 控制台

工程师们想出了一个绝妙的主意：既然内存变大了，为什么不一次性装入多个作业呢？

当 Job A 在等待磁带数据时（阻塞），操作系统把 CPU 切给 Job B 用。
当 Job B 也在等打印机时，再切给 Job C。

多道程序设计下的内存划分

这一刻，计算机科学迎来了一个关键的转折点：为了在多个程序之间来回切换，我们需要保存每个程序的状态。

在 OS/360 中，出现了用来描述任务状态的数据结构 TCB（Task Control Block）。这正是后来 PCB（Process Control Block）的前身。

OS/360 中的系统控制块 (TCB) 结构

此时，TCB 主要完成两个任务：

现场保护：当 CPU 从 A 切到 B 时，A 的寄存器（算到一半的结果、程序计数器 PC 等）必须存进 TCB，否则下次回来状态就全部丢失了（因为寄存器只有一套）。
状态标记：系统需要记录谁在 Running，谁在 Waiting，谁已经 Ready。

3. 终极进化：以人为本 —— 分时系统与进程#

时间背景	代表
1960s 晚期 - 1970	Multics, Unix

到了 60 年代末，计算机不再仅仅用于科学计算，人们开始通过终端（Teletype/屏幕/键盘）与计算机交互。如果继续沿用多道程序设计的逻辑（只有 I/O 阻塞才切换），会发生什么？

假设 Job A 中写了一个死循环 while(1) 且不进行 I/O，它将永远霸占 CPU。坐在终端前的用户 B 敲下键盘，屏幕毫无反应。这对于交互式系统是不可接受的。

为了解决 “响应时间太慢，用户体验差” 的矛盾，MIT、贝尔实验室和通用电气联合开发了 Multics（虽然它过于复杂，但其思想催生了后来的 Unix）。

系统引入了硬件定时器。这一改变是革命性的：

抢占式调度（Preemptive）：无论程序 A 是否运行完，每隔几十毫秒（一个时间片），操作系统强制打断它，保存上下文，把 CPU 扔给程序 B。
幻觉：这种快速的切换，让每个用户都产生了一种 “我独占了一台电脑” 的错觉。

轮转调度算法 (Round-Robin) 时间片轮转示意

也就是在这个时期，进程这个概念被正式确立，并赋予了现代含义。为了维持这种 “独占的幻觉”，操作系统构建了两道高墙：

时间的虚拟化：通过保存/回复 CPU 寄存器上下文，让每个进程觉得拥有独立的 CPU。
空间的虚拟化：通过 MMU（内存管理的单元）和页表，让每个进程觉得拥有独立的、连续的内存空间（虚拟内存）。

至此，进程不再仅仅是用户的代码，它是：

Note

代码 + 动态执行上下文（某一时刻寄存器中的值）+ 虚拟地址空间

参考资料#

本文参考了以下资料，排名无先后顺序：

C++ 中的初始化列表和列表初始化

Sat, 03 Jan 2026 15:07:00 GMT

很多初学者容易混淆初始化列表（Member Initializer List）和列表初始化（List Initialization），因为它们的名字很像，但它们实际上解决的是完全不同的问题：

初始化列表：解决的是对象生命周期与内存模型的问题（“什么时候赋初值”）
列表初始化：解决的是类型系统的统一性与安全性的问题（“用什么语法赋初值”）

初始化列表（Member Initializer List）#

它的形式出现在构造函数参数列表之后，函数体大括号之前，以 : 开头。

1
class A {
2
    int x;
3
public:
4
    A(int val) : x(val) {} // 初始化列表
5
};

初始化 vs. 赋值#

在 C++ 的对象模型中，“初始化”（Initialization）和 “赋值”（Assignment）是两个截然不同的物理过程。

内存分配（Allocation）：在栈上或堆上划出一块内存
初始化（Initialization）：在这块内存上构建对象，使其成为一个合法的实例
赋值（Assignment）：对象已经存在了，擦出旧值，填入新值。

构造函数的执行时间线：

进入构造函数之前：编译器必须确保所有成员变量都已经 “出生”（初始化完成）
进入构造函数体（{...}）：这已经是 “出生后” 的世界了，这里面写的代码都是 “赋值” 操作。

为什么要用初始化列表？#

如果你不用初始化列表，而是写在函数体内：

1
class Person {
2
    std::string name;
3
public:
4
    // 写法 1：在函数体内赋值
5
    Person(const std::string& n) {
6
        name = n;
7
    }
8
};

底层发生了什么？

隐式初始化：在进入 { 之前，编译器发现 name 还没有初始化，于是强行用 std::string 的默认构造函数。name 变成了一个空字符串 ""
赋值操作：进入 { 后，执行 name = n;。调用 std::string 的赋值运算符，把刚才那个空字符串的内容丢弃，拷贝 n 的内容

这就类似于，你先建了一个空房子，然后立即把它拆了重建成你想要的样子，这就是双倍的开销。

正确的写法（初始化列表）：

1
// 写法 2：使用初始化列表
2
Person(const std::string& n) : name(n) {}

底层发生了什么？

直接构造：直接调用 std::string 的拷贝构造函数，用 n 来 “生出” name
函数体为空，无操作。收益：省去了一次默认构造和一次赋值操作。

必须使用的场景（物理限制）#

有些东西必须 “出生时” 就确定，生出来后再改就晚了。这些情况必须使用初始化列表：

const 成员：常量一旦出生就不能修改（不能赋值）
引用成员（&）：引用一旦出生必须绑定到一个对象，不能重新绑定（不能赋值）
没有默认构造函数的类成员：如果成员是一个类，且它没有默认构造函数（必须带参），编译器无法在进入函数体前 “隐式初始化” 它，必须显式指定

初始化的顺序（内存布局决定）#

初始化列表中的顺序并不决定初始化的真实顺序！成员变量的初始化顺序严格由它们在类定义（Class Definition）中声明的顺序决定。

1
class A {
2
    int x;
3
    int y;
4
public:
5
    // 错误示范！看起来像先算 y，其实 x 会先初始化，次数 y 是垃圾值
6
    A(int val) : y(val), x(y) {}
7
};

C++ 对象的内存布局在编译器就确定了（x 在前，y 在后）。析构时必须按相反顺序销毁。为了保证构造和析构的对称性（LIFO），构造顺序必须固定，不能随你怎么写列表儿改变。

列表初始化（List Initialization）#

它的形式是使用花括号 {}。

1
int a{0};
2
std::vector<int> v{1, 2, 3};

统一初始化语义#

在 C++11 之前，初始化的语法简直是精神分裂：

1
int a = 5;
2
int b(5);
3
int arr[] = {1, 2};
4
struct Point p = {1, 2};

C++11 引入 {} 旨在统一初始化（Uniform Inialization）：万物皆可 {} 初始化。

底层机制：`std::initializer_list`#

当你用{1, 2, 3, 4} 初始化一个容器（如 std::vector）时，发生了什么？

编译器魔法：编译器会在静态存储区悄悄创建一个数组
包装：编译器构建一个 std::initializer_list<T> 对象。这其实是一个轻量级的 “视图” 或 “胖指针”，它只包含两个指针：一个指向数组开头，一个指向结尾（或长度）
传递：这个轻量级对象被传给 std::vector 的构造函数
消费：vector 遍历这个 list，把数据拷贝到自己的内存里

这就是为什么你可以给 std::vector 赛任意数量的初始值。

安全特性：防止窄化转换（Narrowing Conversion）#

这是一个类型安全设计。初始化意味着 “建立一个合法的初始状态”。如果数据在初始化过程中丢失了精度，那么这个初始状态本身就是 “不诚实” 的。

1
int a = 3.14; // C++98: 允许 a 变成 3（截断）
2
int b{3.14}; // C++11: 编译器报错！禁止数据丢失

{} 语法强制要求：如果源类型的值无法无损地放入目标类型，编译器必须报错。

解决 “最令人头秃的解析”（Most Vexing Parse）#

C++ 的语法歧义：

1
// 你的意图：创建一个对象 a，调用默认构造函数
2
A a();

编译器的理解：声明了一个函数 a()，它不接受参数，返回类型是 A。

解决办法：使用 {}：

1
A a{}; // 明确无误，这就是创建对象

因为函数声明不可能用 {} 结尾。

两者的 “撞车”#

当一个类既有普通构造函数，又有接受 std::initializer_list 的构造函数时，{} 会极度优先匹配后者。

1
class Magic {
2
public:
3
    Magic(int a, int b) {
4
        // 构造函数 1：普通构造
5
        std::cout << "Normal Constructor" << std::endl;
6
    }
7

8
    Magic(std::initializer_list<int> list) {
9
        // 构造函数 2：列表构造
10
        std::cout << "List Constructor" << std::endl;
11
    }
12
};
13

14
Magic m1(10, 20); // 调用构造函数 1
15
Magic m2{10, 20}; // 调用构造函数 2（因为 {10, 20} 被视为列表）

展开收起

如何选择 `{}` 与 `()`？#

`{}` 的写法#

直接列表初始化（Direct List Initialization）#

特征：不带等号 =
心智模型：我非常确定我要构造这个对象，请直接用这些参数造出来，不许做任何隐式类型转换。

1
// 1. 普通变量
2
int x{0};                       // x 初始化为 0
3
double d{3.14};                 // d 初始化为 3.14
4

5
// 2. 类对象
6
std::vector<int> v{1, 2, 3};    // 容器包含 1, 2, 3
7
Person p{"Alice", 20};          // 调用 Person(string, int)
8

9
// 3. 堆内存 new
10
int* ptr = new int{5};          // 申请内存并初始化为 5
11

12
// 4. 临时对象（匿名对象）
13
func(Person{"Bob", 30});
14

15
// 5. 基类与成员初始化
16
Derive(int x, int y) : Base{x}, m_val{y} {}

展开收起

拷贝列表初始化（Copy List Initialization）#

特征：带有等号 =
心智模型：先把右边的花括号转换成目标类型，然后再拷贝（或移动）给左边

1
// 1. 变量定义
2
int x = {0};
3
std::vector<int> v = {1, 2, 3};
4

5
// 2. 函数传参（隐式构造）
6
void foo(std::vector<int> v);
7
foo({1, 2, 3});                 // 编译器隐式地把 {1, 2, 3} 转换成了 vector
8

9
// 3. 函数返回值
10
std::vector<int> bar() {
11
    return {1, 2, 3};           // 隐式构造并返回
12
}

直接列表初始化和拷贝列表初始化的选择#

在绝大多数情况下，由于现代编译器的优化，拷贝列表初始化会被直接优化成为直接列表初始化，这被称为复制省略（Copy Elision）。

但是存在一种例外情况，那就是 explicit 关键字声明的构造函数。

`explicit` 关键字的影响#

如果一个类的构造函数被声明为 explicit（显式），那么第 2 种写法（带等号的会被禁止）。

1
class Widget {
2
public:
3
    explicit Widget(int n) {}
4
};
5

6
Widget w1{10};      // OK：直接初始化，显式调用
7
Widget w2 = {10};   // Error：拷贝列表初始化要求 “隐式转换”，但被 explicit 阻止了

所以我们可以得出结论：Type x{...} 比 Type x = { ... } 更加通用，因为它不受 explicit 的限制，更推荐使用不写等号的写法。

真的应该所有情况都用 `{}` 吗？#

虽然 C++ Core Guidenlines 推荐默认使用 {}，但你必须警惕两个巨大的陷阱。这两个陷阱的根源在于编译器对 std::initializer_list 的极度偏爱。

陷阱 1：`std::vector` 的构造#

1
std::vector<int> v1(10, 5); // 用 ()
2
std::vector<int> v2{10, 5}; // 用 {}

解析：

v1（圆括号）：调用 vectore(size_type n, const T& val)，创建了 10 个元素，每个元素都是 5
v2（花括号）：编译器看到 {}，优先查找是否接受 std::initializer_list 的构造函数，找到了，于是创建了 2 个元素，分别是 10 和 5

当构造函数发生重载时，如果存在接受 std::intitalizer_list 的版本，编译器会贪婪地优先匹配它，哪怕需要进行一些类型提升。只有完全匹配不上了，才会退回去找普通的构造函数。

建议：

原则上：默认用 {}
例外：当在调用容器的大小/数量构造函数时，必须用 ()，否则会被误解为 “元素内容”

陷阱 2：`auto` 类型推导的歧义#

这一点在 C++11/14 和 C++17 中表现不同，非常令人困惑。

1
auto x = {1};
2
// x 的类型是什么？是 int 吗？
3
// NO! x 的类型是 std::initializer_list<int>

如果你本意是想要一个 int，结果得到了一个轻量级列表对象，后面的代码可能会出问题。

修正写法（C++17 起）：

1
auto x{1};      // C++17 规定推导为 int
2
auto y = {1};   // 推导为 std::initializer_list<int>

建议：配合 auto 使用 {} 时要格外小心，最好明确类型，或者确保你真的想要 std::initializer_list。

`{}` 的特性：默认值初始化（Value Initialization）#

这是 {} 最让我觉得 “舒服” 的地方。

如果你想把一个对象清零，或者初始化为 “空状态”：

1
// 旧写法
2
int i;      // 危险！如果是局部变量，i 的值是随机的（垃圾值）
3
int* p;     // 危险！野指针
4

5
// 新写法（空花括号）
6
int i{};    // 安全！保证初始化为 0
7
int* p{};   // 安全！保证初始化为 nullptr
8
double d{}; // 安全！保证初始化为 0.0

空的 {} 触发值初始化（Value Initialization）。对于内置类型（int、float、指针），它会执行零初始化（Zero Initialization）。

C++ 中的构造函数

Sat, 03 Jan 2026 13:05:00 GMT

对于 C++ 对象而言，我们认为：对象 = 内存 + 语义（不变量）。

内存：仅仅是电子与硅晶体中状态未知的比特位。
语义：这段内存代表什么含义（是 int、是 char 还是 float），以及它必须满足的条件（“不变量”，Invariant）。

构造函数（Constructor）的本质就是将 “原始、混沌” 的内存强制转换为 “持有特定语义的、合法的对象” 的原子操作过程。

核心逻辑#

在 C 语言中，创建一个 struct 通常分为两步：

分配内存（malloc 或栈上声明）
赋值（init 函数或手动赋值）

问题在于：如果在第 1 步和第 2 步之间使用该对象，就会导致灾难（未定义行为）。或者，如果使用者忘记了第 2 步，系统就会处于 “非法状态”。

C++ 引入构造函数就是为了保证：

如果一个对象存在，那么它一定是合法的。

构造函数保证了初始化（Initialization）与定义（Defination）的不可分割性。

构造函数的执行流#

当你写下 T object(args); 时，编译器实际执行了以下步骤：

分配内存：在栈或堆上找到一块足够容纳 sizeof(T) 的空间。此时，内存里的数据是随机的（Garbage）。
执行初始化列表（Initialization List）：这是真正的初始化时刻。
执行函数体（Function Body）：这实际上是后续的计算或赋值操作，而非初始化。

为什么首选初始化列表？#

因为 C++ 规定成员变量在进入构造函数体 {} 之前必须完成构建。

1
Class() : member(value) {} // 直接在内存位置上构造 member

使用初始化列表的成本仅为 1 次构造。

1
Class() { member = value; }

过程：

调用 member 的默认构造函数（无参）。
调用 member 的赋值运算符 operator=。

在这个过程中的成本为：1 次构造 + 1 次赋值（还可能设计旧内存释放和新内存申请）。

初始化列表不仅是效率优化，对于 const 成员或 reference（引用）成员，它是唯一的初始化方式，因为它们创建后不可修改（不可赋值）。

构造函数的分类#

根据对象资源管理的不同需求，构造函数演化出了四种主要形态。我们将用资源所有权的视角来区分它们。

默认构造函数（Default Constructor）#

语义：无中生有
形式：T()
视角：当对象被创建但外界未提供任何信息时，对象应处于什么状态？通常是 “空状态” 或 “零状态”
注意：如果类中包含原始指针，编译器生成的默认构造函数不会置空指针（由于 C 的遗留包袱），这会导致悬垂指针。因此现代 C++ 提倡显式定义或使用成员默认初始化（int* p = nullptr;）

参数化构造函数（Parameterized Constructor）#

语义：根据蓝图定制
形式：T(args...)
视角：将外部数据约束映射到内部不变量。例如，创建 “圆” 对象，参数是半径。构造函数必须检查 radius > 0，这就是维护 “不变量”

拷贝构造函数（Copy Constructor）#

语义：复制（细胞分裂、克隆）
形式：T(const T& other)
视角：
- 如果对象时值语义（如整数、坐标），直接按位拷贝（Shallow Copy）
- 如果对象持有资源（如堆内存指针、文件句柄），必须进行深拷贝（Deep Copy）
- 本质矛盾：如果只复制指针，两个对象指向同一块内存，析构时会发生 “Double Free” 错误。因此拷贝构造函数必须重新分配资源。

移动构造函数（Move Constructor）#

移动构造函数是 C++11 提出的革命性进步。

语义：所有权转移（器官移植）
形式：T(T&& other)
视角：
- 在 C++98 中，如果要将一个临时对象（即将销毁）放入容器，比如先复制再销毁。这极度浪费性能（如复制一个巨大的 std::vector）
- 移动构造函数利用右值引用（&&），识别出 other 是一个即将消亡的对象。
- 它偷走 other 的资源（指针指向新主，旧指针置空），而非复制数据
- 代价：极低（仅是指针赋值）

关键机制与陷阱#

`explicit` 关键字：拒绝隐式转换#

C++ 默认允许单参数构造函数进行隐式类型转换。

1
struct Buffer { Buffer(int size) { ... } };
2
void func(Buffer b);
3

4
func(42)； // 编译器偷偷执行了 Buffer(42)，可能并不是你想要的

从安全角度（Safety First）出发，隐式类型转换破坏了强类型系统。标记 explicit 禁止这种 “自作聪明” 的行为，强制显式调用。

委托构造（Delegating Constructors）#

允许一个构造函数调用同类的另一个构造函数。这是为了准许 DRY（Don’t Repeat Yourself）原则，防止初始化逻辑碎片化。

构造与虚函数#

永远不要在构造函数中调用虚函数。

原理：在基类构造期间，派生类的部分尚未初始化。为了安全，C++ 此时将对象视为基类类型。虚函数表（vtalbe）指针指向基类表，多态失效。

RAII 与构造函数#

将上述所有内容串联起来的概念就是 RAII（Resource Acquisition Is Initialization），这是 C++ 的灵魂。

资源获取即初始化：资源的生命周期严格绑定对象的生命周期
构造函数：资源的获取点（锁住互斥量、打开文件、分配内存）
析构函数：资源的释放点（解锁、关闭、释放）

C++ 的构造函数不仅仅是用来 “赋值” 的函数，它是类型系统安全性的守门人，是资源管理自动化的起点。

掌握构造函数，不仅仅是记住语法，而是要时刻思考：

这个对象诞生的一瞬间，我如何保证它拥有了所需的资源，且处于绝对合法的状态？

C++ 中的 list

Sat, 03 Jan 2026 13:05:00 GMT

在现代 C++ 开发中，虽然 std::vector 足以应付绝大多数的场景，但是在某些特定场景下，std::list 依旧是不可替代的神器。

核心概念与底层原理#

头文件：#include <list>
本质：双向链表（Doubly Linked List）
内存模型：非连续内存。每个元素（节点）都是独立分配在堆上的，节点之间通过指针（prev 和 next）连接
特点：
- 不支持随机访问：不能使用下标 l[5] 访问元素，必须从头一个一个遍历过去
- 插入 / 删除极快：只要持有了某个位置的迭代器，在该位置插入或删除元素的操作是 O(1)O(1)O(1) 的，且不需要移动其他元素

初始化与构造#

用法与 std::vector 非常相似：

1
#include <list>
2

3
std::list<int> l1;              // 空链表
4
std::list<int> l2 = {1, 2, 3};  // 列表初始化
5
std::list<int> l3(l2);          // 拷贝构造
6
std::list<int> l4(5, 100);      // 5 个 元素，全是 100

独有的操作优势（`std::vector` 做不到的）#

这是 std::list 存在的理由。由于它是链表，它支持一些操作极其高效，或者提供了 std::vector 根本没有的接口。

头部操作#

std::vector 在头部插入 / 删除操作极其低效（O(N)O(N)O(N)），而 std::list 则是瞬间完成（O(1)O(1)O(1)）。

push_front(val)：头部插入
pop_front()：头部删除

接合（Splicing）#

可以将一个 std::list 的元素（全部或部分）直接 “剪切” 并 “粘贴” 到另一个 std::list 中，这是纯指针操作，没有数据拷贝，所以速度极快。

1
std::list<int> list1 = {1, 2, 3};
2
std::list<int> list2 = {4, 5, 6};
3

4
auto it =  list1.begin();
5
++it; // 指向 2
6

7
// 将 list2 的所有元素 “移动” 到 list1 的 2 前面
8
// list2 变空，list1 变为 {1, 4, 5, 6, 2, 3}
9
list1.splice(it, list2);

专用成员函数#

由于 std::list 无法随机访问，标准库算法（如 std::sort）对它无效。因此 list 自带了一套经过优化的成员函数：

l.sort()：排序（稳定排序，底层通常是归并排序）。注意：千万别读 std::list 用 std::sort(l.begin(), l.end())，编译会报错
l.remove(val)：删除所有等于 val 的元素
l.remove_if(pred)：删除满足条件的元素
l.unique()：删除相邻的重复元素（去重前通常要先 sort）
l.reverse()：逆置链表
l.merge(l2)：合并两个已排序的链表（l2 会变空）

迭代器特性#

这是决定选择 std::vector 还是 std::list 的关键因素。

类型：双向迭代器（Bidirectional Iterator）
- 支持：++it、--it、*it
- 不支持：it + 5，it < other_it（不能跳跃，不能比较大小）
稳定性（Validity）：极高
- 掺入操作：绝对不会让现有的迭代器失效
- 删除操作：只有指向被删除节点的那个迭代器会失效，其他的完全不受影响
- 对比 std::vector：std::vector 一旦扩容，所有迭代器全部失效；中间插入，后面所有迭代器失效。

`std::list` 和 `std::vector` 的选择#

这是一个经典的 Trade-off（权衡）问题：

特性	`std::vector`	`std::list`
随机访问	O(1)O(1)O(1)（支持 `[]`）	不支持（O(N)O(N)O(N)）
尾部插入	O(1)O(1)O(1)	O(1)O(1)O(1)
头部/中间插入	O(N)O(N)O(N)（很慢，要挪动数据）	O(1)O(1)O(1)（很快，前提是有迭代器）
内存布局	连续（Cache 命中率高）	分散（Cache 命中率低）
额外内存	较少（少量预留空间）	较大（每个元素都要存两个指针）
迭代器失效	容易失效	几乎不失效

结论：

95% 的情况用 std::vector：现代 CPU 的缓存机制非常依赖内存连续性。即使是在中间插入，对于小对象（如 int），std::vector 往往也比 std::list 快，因为 std::list 的遍历会导致大量的 Cache Miss。
以下情况可以用 std::list：
1. 需要频繁在头部或中间插入 / 删除，且元素总数很多
2. 对象非常大，拷贝代价极高（虽然 C++11 移动语义缓解了这个问题）
3. 核心需求：你需要保存指向某个元素的迭代器，并且在后续操作中（无论怎么插入删除其他元素），希望这个迭代器一直有效

C++11 新增：`std::forword_list`#

C++11 引入了 std::forword_list（单向链表）：

特点：只有 next 指针，没有 prev 指针
优势：比 std::list 更省内存（少存一个指针）
劣势：只能向前遍历，功能受限
场景：极其追求内存优化的哈希表桶实现等

C++ 中的 vector

Sat, 03 Jan 2026 10:50:00 GMT

std::vector 是 C++ 中最重要、最常用的容器，没有之一。它的本质是动态数组（Dynamic Array）。

std::vector 是在堆（Heap）上管理一块连续的内存，可以存放任意类型的对象。

核心特性与底层原理#

头文件：#include <vector>
内存模型：连续内存。这意味着它和 C 数组一样，支持通过指针偏移量快速访问，并且对 CPU 缓存（Cache）非常友好。
自动扩容：当存入数据量超过当前容量时，std::vector 就会申请一块更大的内存（通常是原来的 1.5 倍或 2 倍），将旧数据移动/拷贝过去，然后释放旧内存。

初始化与构造#

1
#include <vector>
2

3
// 1. 默认构造（空 vector）
4
std::vector<int> v1;
5

6
// 2. 指定大小和默认值
7
std::vector<int> v2(10);        // 10 个元素，默认初始化 0
8
std::vector<int> v3(10, 5);     // 10 个元素，每个都是 5
9

10
// 3. 列表初始化（C++11）
11
std::vector<int> v4 = {1, 2, 3, 4};
12

13
// 4. 拷贝构造
14
std::vector<int> v5(v4);
15

16
// 5. 迭代器范围构造（常用与从其他容器拷贝）
17
int arr[] = {10, 20, 30}
18
std::vector<int> v6(arr, arr + 3);

展开收起

容量与大小#

函数	说明	备注
`size()`	当前元素个数	实际存了多少个
`capacity()`	当前分配的内存能存多少个	`capacity` ⩾\geqslant⩾ `size`
`empty()`	是否为空	推荐使用，比 `size() == 0` 更语义化
`reserve()`	预分配内存	仅改变 `capacity`，不改变 `size`
`resize(n)`	改变元素个数	改变 `size`，如果变大则填充默认值
`shrink_to_fit()`	释放未使用的内存（C++11）	让 `capacity` 搜索到 `size` 大小

为什么 `reserve` 非常重要？#

1
std::vector<int> v;
2
v.reserve(1000); // 一次性分配好内存
3
for (int i = 0; i < 1000; i++) {
4
    v.push_back(i); // 这里不会再发生内存重新分配，效率极高
5
}

增删查改#

插入与添加#

push_back(val)：在尾部添加元素（会发生拷贝或移动）。
emplace_back(arg...)（C++11）：原地构造。直接在 std::vector 尾部构造对象，省去了一次临时对象的构造和拷贝 / 移动，效率通常更高。
insert(it, val)：在迭代器指向的位置插入。效率为 O(N)O(N)O(N)，因为要移动后续所有元素。

删除#

pop_back：删除尾部元素（O(1)O(1)O(1)）。
erase(it)：删除指定位置元素（O(N)O(N)O(N)，后续元素前移）。
clear()：清空所有元素，szie 变为 0，但 capacity 通常不变（内存不释放）。

访问#

v[i]：下标访问，不检查越界。
v.at[i]：检查越界，越觉抛 std::out_of_range。
v.front() / v.back()：访问首尾。
v.data()：返回指向底层数组首元素的指针（T*）。常用于和 C 语言 API 交互。

迭代器失效#

由于 std::vector 是连续内存，当结构发生变化时，指向旧内存的迭代器、指针、引用可能会失效。

扩容时失效：当 push_back 导致 std::vector 扩容（reallocate）时，原内存被释放，所有指向原数据的迭代器 / 指针瞬间全部失效。
插入 / 删除时失效：当 insert 或 erase 一个位置时，该位置之后的所有迭代器都会失效（因为数据移动了）。

1
std::vector<int> v = {1, 2, 3, 4};
2
for (auto it = v.begin(); it != v.end(); ++it) {
3
    if (*it % 2 == 0) {
4
        v.erase(it); // 错误！erase 后 it 已失效，下一次 ++it 会崩溃
5
    }
6
}
7

8
// 正确写法（利用 erase 返回值更新迭代器）
9
for (auto it =  v.begin(); it != v.end()) {
10
    if (*it % 2 == 0) {
11
        it = v.erase(it); // erase 返回指向下一个元素的迭代器
12
    } else {
13
        ++it;
14
    }
15
}

展开收起

特殊版本：`std::vector<bool>`#

这是一个历史遗留的 “坑”。为了节省空间，C++ 标准库特化了 std::vector<bool>，它不是存储 bool（1 字节），而是存储 bit（1 比特）。

后果：

你无法获得元素的地址：&v[0] 是非法的，因为无法寻址单个比特。
它的 operator[] 返回的不是 bool&，而是一个代理对象。
非线程安全：并发读写邻近的 bit 可能会导致数据竞争（因为它们位于同一个字节内）。

建议：如果需要存布尔值且不缺那点内存，用 std::vector<char> 或 std::deque<bool> 代替。如果确实需要位操作，考虑使用 std::bitset。

现代化操作#

C++20：`std::erase` 和 `std::erase_if`#

在 C++20 之前，要从 std::vector 中删除满足特定条件的所以元素，需要使用 “Erase-Remove Idiom”（v.erase(std::remove(...), v.end()），非常啰嗦。

C++20 简化了：

1
std::vector<int> v = {1, 2, 3, 4, 5, 6};
2

3
// 删除所有偶数
4
std::erase_if(v, [](int x) { return x % 2 == 0; });

最佳实践#

优先使用 emplace_back：代替 push_back，特别是存放复杂对象时。
善用 reserve：如果你能预估数据量，一定要先 reserve，在数据量较大时，能够极大的优化性能。
避免头部/中间插入：在 std::vector 头部插入数据（insert(begin(), val)）是非常慢的（O(N)O(N)O(N)），如果有这种需求，请改用 std::deque 或 std::list。
慎用 std::vector<bool>：除非你清楚你自己在做什么。
小心引用失效：在循环中做 push_back 时，千万不要同时持有指向该 std::vector 内部元素的引用，一旦扩容，引用就变成悬空指针了。

C++ 中的 string

Sat, 03 Jan 2026 08:28:00 GMT

std::string 是 C++ Standard Library 提供的标准类之一，这也是 C++ 开发中最常用的类之一，它本质上是对 C 风格字符串（char*）的封装，提供了自动内存管理和丰富的操作接口。

核心概念#

std::string 位于 <string> 头文件中，本质上是对 std::basic_string<char> 的特化版本。

头文件：#include <string>
命名空间：std
特点：动态管理内存，自动处理扩容，兼容 C 风格字符串。

初始化与构造#

1
#include <string>
2
#include <vector>
3

4
std::string s1;                     // 默认构造，空字符串 ""
5
std::string s2 = "Hello, World";    // 拷贝初始化
6
std::string s3("Hello, World");     // 直接初始化
7
std::string s4(5, 'A');             // 生成 "AAAAA"
8
std::string s5(s2);                 // 拷贝构造
9
std::string s6(s2, 1, 3);           // 子串构造：从索引 1 开始取 3 个字符 -> "ell"
10

11
// C++11 及以后
12
std::string s7 = {'H', 'i'};        // 列表初始化

容量与属性#

了解容量对于优化性能至关重要，特别是避免不必要的内存重分配。

函数	说明	备注
`size()` / `length()`	返回字符数量	两者完全等价，一般用 `size()`
`empty()`	判断是否为空	推荐使用，比 `size() == 0` 语义更清晰
`capacity()`	当前分配的内存容量	通常 `>=size()`
`reserve(n)`	预分配 `n` 字节内存	避免 `append` 时的多次内存重分配
`shrink_to_fit()`	释放多余内存（C++11）	让 `capacity` 接近 `size`

元素访问与遍历#

访问单个字符#

operator[]：s[i]。不检查越界，效率高，但越界为导致未定义行为。
at()：s.at[i]。检查越界，越界会抛出 std::out_of_range 异常。
front() / back()：访问首尾字符。

C 风格字符串#

c_str()：返回 const char*，以 NULL 结尾。主要用于兼容旧式 C 接口（如 printf）。
data()：C++11 前不保证 NULL 结尾，C++11 后与 c_str() 基本一致。

遍历#

1
std::string s = "Hello, World";
2

3
// 1. 基于下标
4
for (size_t i = 0; i < s.size(); ++i) { /* ... */ }
5

6
// 2. 基于迭代器
7
for (auto it = s.begin(); it != s.end(); ++i) { /* ... */}
8

9
// 3. 基于范围 for 循环（C++11，推荐）
10
for (char c: s) { /* ... */ }       // 值拷贝
11
for (char& c: s) { c = toupper(c) } // 引用修改

修改与操作#

操作	函数	示例
追加	`+=`、`append()`、`push_back()`	`s += " World"`
插入	`insert(pos, str)`	`s.insert(0, "Hi ")`
删除	`erase(pos, len), pop_back()`	`s.erase(0, 3)`
替换	`replace(pos, len, str)`	`s.replace(6, 5, "C++")`
清空	`clear()`	把 `size` 设置为 0，`capacity` 通常不变
截断/扩充	`resize(n)`	改变 `size`，多出的补默认值

查找与子串#

所有查找函数如果未找到，都会返回常量 std::string::npos（通常是 -1 的无符号形式，即最大的 size_t()）。

1
std::string = "filename.txt";
2

3
// 1. 查找 find
4
size_t pos = s.find(".");
5
if (pos != std::string::npos) {
6
    // 找到了
7
}
8

9
// 2. 反向查找 rfind（找最后一个出现的位置）
10
size_t last_dot = s.rfind(".");
11

12
// 3. 查找集合 find_first_of / find_first_not_of
13
// 查找第一个出现的元音字母
14
size_t v_pos = s.find_first_of("aeiou");
15

16
// 4. 获取子串 substr
17
// 参数：substr(开始位置, 长度)
18
std::string name = s.substr(0, pos); // "filename"
19
std::string ext = s.substr(pos + 1); // "txt"（省略长度则取到末尾）

展开收起

类型转换#

需要包含头文件 <string>。

数值转字符串 `std::to_string(value)`#

1
std::string s = std::to_string(3.14); // "3.140000"

字符串转数值#

std::stoi(s)：int
std::stol(s)：long
std::stod(s)：double
注意：这些函数会处理前导空格，但遇到非法字符会抛异常

现代化特性#

C++17：`std::string_view`#

std::string 是 “拥有者”，其拷贝开销大。std::string_view 只是一个 “观察者”（包含指针和长度），零拷贝。

函数参数尽量使用 std::string_view 代替 const std::string&，特别是当你只需要读取字符串内容时。

1
// 避免了临时 std::string 对象的构造和内存分配
2
void print_prefix(std::string_view sv) {
3
    i f(sv.substr(0, 3) == "Pre") { // substr 也是 O(1) 操作
4
        // ...
5
    }
6
}

C++20#

填补了长期以来 C++ std::string 缺少高频接口的遗憾：

s.starts_with("prefix")：判断前缀
s.ends_with("suffix")：判断后缀
s.contains("sub")：判断包含

底层原理#

SSO（Small String Optimization）#

原理：为了避免短字符串频繁的堆内存分配（Heap Allocation），std::string 内部通常有一个小的栈缓冲区（通常 15 或 22 字节，取决于编译器实现）。

效果：

如果字符串很短（例如："Hello"），直接存放在栈上对象内部，无 malloc，速度极快。
如果字符串变长，才会在堆上分配内存，指针指向堆。

COW（Copy-On-Write）#

在 C++11 之后已被废弃。现在的标准规定 std::string 不允许使用 COW。这意味着 std::string a = b; 一定会发生深拷贝（除非使用 std::move）。

最佳实践#

参数传递#

只读不拥有：C++17 前用 const std::string&，C++17 后优先用 std::string_view。
需要修改：用 std::string&。
需要拥有权（Sink）：可以直接传值 std::string 并配合 std::move。

性能优化#

在循环中追加字符串前，先用 reserve() 预留空间（写在循环之前）。
尽量避免在循环内部频繁构造 std::string。
换行符优先用 \n 而不是 std::endl（除非你需要立即刷新缓冲区）。

安全性#

永远不要对 c_str() 返回的指针进行 delete 操作。
当 string 对象被修改或销毁后，之前获取的 iterators、references 和 pointers（如 c_str() 的结果）可能会失效。

Windows 包管理神器 Scoop：从入门到自定义安装配置

Fri, 05 Dec 2025 13:00:00 GMT

如果你习惯了 Linux 下 apt、pacman 或 macOS 下 brew 的爽快体验，那么回到 Windows 面对满屏的安装包和 “下一步” 肯定会感到繁琐。

Scoop 是 Windows 下的一款轻量级包管理工具。与 Chocolatey 或 Winget 不同，Scoop 的设计哲学是 “非侵入式”：

权限洁癖：默认安装在用户目录，无需 UAC 提权（除非安装全局软件）。
绿色环保：自动处理环境变量（Shim 机制），卸载时瞬间清除，不残留注册表垃圾。
版本控制：利用 Git 管理软件仓库（Bucket），方便版本回退。

本文将带你从零开始配置一个完美的 Scoop 环境。

1. 调整 Scoop 安装位置#

Scoop 默认将软件安装在 C 盘。作为开发者，我们通常希望将工具链与系统盘分离。在运行安装脚本前，我们需要先设置环境变量。

还没有安装 Scoop（推荐）#

打开 PowerShell（无需管理员权限），依次执行以下命令。假设我们要安装到 D:\Users\abc\scoop（请根据你的实际情况修改路径）。

第一步：设置用户安装目录#

这是普通软件（Chrome, VSCode 等）的安装位置。

Terminal window

1
$env:SCOOP = 'D:\Users\abc\scoop'
2
[Environment]::SetEnvironmentVariable('SCOOP', $env::SCOOP, 'User')

第二步：设置全局安装目录（可选）#

这是需要管理员权限（如驱动、系统级工具）的软件安装位置。

Terminal window

1
$env:SCOOP_GLOBAL = 'D:\ProgramData\scoop'
2
[Environment]::SetEnvironmentVariable('SCOOP_GLOBAL', $env::SCOOP_GLOBAL, 'Machine')

Note

注意：修改 Machine 级别的变量通常需要管理员权限的 PowerShell。

警告：路径规范 Scoop 的安装路径中严禁包含空格和中文字符！

❌ 错误示例：D:\Program Files\Scoop 或 D:\我的软件\Scoop

✅ 正确示例：D:\Users\abc\scoop 或 D:\Scoop

备选方案：通过图形界面设置#

如果你不习惯命令行，也可以通过 Windows 设置：

搜索 “编辑系统环境变量”。
点击 “环境变量(N)…”。
在 “用户变量” 中新建 SCOOP，值为你的自定义路径。
在 “系统变量” 中新建 SCOOP_GLOBAL，值为你的全局路径。

已经安装了 Scoop（迁移）#

如果你已经安装了 Scoop 但想迁移目录，操作稍微繁琐一些，因为 Scoop 不写注册表，它是“绿色”的。

将原目录（默认 C:\Users\<user_name>\scoop）剪切并粘贴到新目录（例如 D:\Scoop）。
修改系统环境变量 Path：
- 删除指向旧目录的条目（如 C:\Users\...\scoop\shims）。
- 添加新目录的 shim 路径（如 D:\Scoop\shims）。
关键步骤：打开新的 PowerShell 终端，执行以下命令重置所有软件的链接：
Terminal window
```
1
scoop reset *
```

2. 安装 Scoop#

环境变量配置完成后，在 PowerShell 中执行以下命令进行安装：

Terminal window

1
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
2
Invoke-RestMethod -Uri [https://get.scoop.sh](https://get.scoop.sh) | Invoke-Expression

第一行：允许当前用户运行本地脚本。
第二行：下载并执行 Scoop 官方安装脚本。

安装完成后，输入 scoop help，如果有输出，说明安装成功。

如果在新开启一个终端后执行 scoop 报错，则需要配置系统 PATH 变量，添加例如：D:\Users\abc\scoop\shims。

3. 初始化配置#

安装必备组件#

Scoop 依赖 Git 来管理仓库，同时强烈建议安装 Aria2 来进行多线程下载加速。

Terminal window

1
scoop install git aria2

安装完成后，建议对 Aria2 进行调优，关闭警告并开启多线程：

Terminal window

1
scoop config aria2-warning-enabled false
2
scoop config aria2-retry-wait 4
3
scoop config aria2-max-connection-per-server 16
4
scoop config aria2-split 16
5
scoop config aria2-min-split-size 1M

添加常用软件仓库 (Buckets)#

Scoop 默认的 main 仓库软件较少且由于标准严格，通常只包含 CLI 工具。我们需要添加社区仓库来扩展生态。

Terminal window

1
scoop bucket add extras      # 包含大量 GUI 软件 (Chrome, VSCode 等)
2
scoop bucket add versions    # 包含旧版本软件
3
scoop bucket add java        # Java 开发相关
4
scoop bucket add nerd-fonts  # 编程字体 (FiraCode NF, JetBrainsMono NF)

4. 装机必备软件清单#

这里列出了一份高频使用的软件清单，涵盖了开发、系统增强和效率工具。

你可以一次性复制执行：

Terminal window

1
# 系统工具与命令行增强
2
scoop install gsudo everything scoop-search starship fzf ripgrep bat powertoys everything-powertoys
3

4
# 开发工具
5
scoop install uv neovim vscode jetbrains-toolbox

软件清单详解：

gsudo: Windows 下的 sudo，比官方的更强，体验与 Linux 一致。
scoop-search: 秒级搜索 Scoop 仓库软件（比原生 scoop search 快几十倍）。
everything: Windows 文件搜索神器。
powertoys: 微软官方出品的系统增强工具集。
everything-powertoys: 让 PowerToys 的启动器调用 Everything 的索引。
starship: 极速、高颜值的终端提示符（Prompt），支持显示 Git 状态、Python 版本等。
fzf: 命令行模糊查找工具。
ripgrep (rg): 速度极快的 grep 替代品。
bat: 带语法高亮和 Git 集成的 cat 替代品。
uv: Rust 编写的 Python 包版本管理器，速度飞快。
neovim: 现代化 Vim 编辑器。
vscode: 最流行的代码编辑器。
jetbrains-toolbox: 管理 IDEA, PyCharm 等 JetBrains 全家桶。

5. 日常维护与进阶#

更新软件#

Scoop 的更新分为两步：先更新仓库列表，再更新软件。

Terminal window

1
scoop update           # 更新 scoop 本身和 bucket
2
scoop update *         # 更新所有已安装的软件

清理旧版本#

Scoop 默认会保留软件的旧版本（为了方便回退）。如果你的磁盘空间紧张，可以清理旧包：

Terminal window

1
scoop cleanup *        # 清理所有软件的旧版本

软件备份与迁移#

这是我最喜欢 Scoop 的一点：你可以导出一份列表，在另一台电脑上瞬间还原你的工作环境。

导出列表：

Terminal window

1
scoop export > scoop-apps.json

在另一台电脑恢复：

Terminal window

1
scoop import scoop-apps.json

6. 常见问题解决#

Windows 搜索找不到安装的软件#

现象：安装了 Chrome 或 VS Code，但按 Win 键搜索不到。

原因：Windows 索引默认只覆盖特定的开始菜单目录，具体路径为：C:\Users\<user>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs（在运行窗口中输入 shell:programs 后点击 Enter 也可直接打开）。

解决方法： Scoop 实际上会自动创建快捷方式到 C:\Users\<user>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Scoop Apps。如果搜索不到，通常是因为索引未更新或快捷方式未正确生成。

尝试执行以下命令重置：

Terminal window

1
# 重置指定软件的快捷方式
2
scoop reset <package-name>
3

4
# 或者重置所有软件（推荐）
5
scoop reset *

reset 命令会重新执行安装脚本中的 “链接” 步骤，重建 .exe 的 shim 和开始菜单快捷方式。

此外，也可以使用 Scoop 自带的体检工具来发现路径或权限问题：

Terminal window

1
scoop checkup

英语翻译技巧

Tue, 02 Dec 2025 01:35:00 GMT

在备考 CET-6 或雅思写作时，许多同学面临的最大障碍不是词汇量，而是思维模式（Mindset）。中英文在底层逻辑上存在巨大的鸿沟：中文重意合、动态、叙事；英文重形合、静态、结构。

本文将拆解中英翻译的核心差异，并提供一套可操作的翻译三步法。

一、核心思维差异（Core Divergences）#

1. 动态 vs. 静态（Nominalization）#

法则： 汉语多用动词（Verb-heavy）；学术英语多用名词（Noun-heavy）。

在翻译时，要学会名词化（Nominalization）：将中文的动作或性质抽象为英语的名词短语。这能显著提升句子的“信息密度”。

原文：这就解释了为什么我们需要从不同角度看问题。
❌ Chinglish: This explains why we need to see the problem from different angles. (动词堆砌)
✅ Academic: This is an illustration of the need for a different perspective on the issue. (名词主导)

2. 主动 vs. 被动（Objectivity）#

法则： 汉语习惯“人”做主语；英语习惯“物”做主语，强调客观事实。

原文: 人们普遍认为，阅读能扩大词汇量。
❌ Chinglish: People generally believe that reading can increase vocabulary. (语法正确，但太口语)
✅ Academic: It is widely acknowledged that vocabulary can be expanded through reading. (被动结构，客观严谨)

3. 意合 vs. 形合（Explicit Logic）#

法则： 汉语逻辑往往隐含在语序中（隐性）；英语逻辑必须通过连接词显性表达（显性）。

中文常用“流水句”，英语则必须用逻辑词像胶水一样把句子粘起来。

逻辑关系	中文结构 (隐性)	英文连接词 (显性)
因果	天气冷，电池坏了。	The battery failed due to the low temperature.
转折	代码跑通了，效率很低。	The code runs successfully; however, its efficiency is low.
递进	他修好了bug，优化了算法。	He fixed the bug; furthermore, he optimized the algorithm.

二、句子的平衡学（Syntactic Balance）#

1. 尾重原则（End-Weight）#

英语句法中，句子是有“物理重量”的。

轻元素： 代词、系动词 (is/are)。
重元素： 长从句、复杂修饰语。

为了避免“头重脚轻”，英语倾向于快速给出主谓骨架，把复杂的修饰扔到后面。

原文: 掌握一门外语对大学生来说是至关重要的。
❌ Chinglish: To master a foreign language is crucial for college students. (主语太长)
✅ Academic: It is crucial for college students to master a foreign language proficiently. (形式主语 It 占位)

尾重原则出现是因为人类的短期记忆是有限的。如果主语（Subject）太长，听者/读者要在大脑里面一直“悬着”这个主语，等很久才能等到谓语（Verb），这会造成认知负担（Cognitive Load）。

2. 如何选择主句（Subject Selection）#

英语句子只能有一个核心（Main Clause），其他信息必须降级。

结果（观点） > 原因/方式： 英语看重 Result（新信息）。
- 原文: 他每天努力学习，终于考上了北大。
- 译文: He was admitted to Peking University (主句) by studying hard every day.
实意动作 > 状态描述：
- 原文: 他是个热心人，经常帮助邻居。
- 译文: Being a warm-hearted man (降级为分词), he frequently helps his neighbors (主句).

三、翻译三步法#

Step 1: 拆解与定位 (Analysis)#

不要一上来就翻。先找到中文里“谁”做了“什么”。如果句子过长（比如一段话只有一个句号的场景），需要根据句子表达的含义对句子进行划分层次，对每个层次分别进行翻译，再使用逻辑词联系上下文。

注意： 中文常省略主语，翻译时必须补全（如补 It 或 There be）。

Step 2: 转换与降级 (Syntactic Demotion)#

确定主句后，对其余成分进行语法降级：

V-ing / V-ed (分词): 表伴随、原因。 (Standing at the window…)
Preposition (介词): 学术神器 With, By, Due to, In terms of. (With the population increasing…)
Clause (从句): Which, That, Although.

Step 3: 润色与精准 (Polishing)#

拒绝绝对化 (Hedging): 除非是定理，否则少用 must/will，多用 may, likely, tend to。体现学术严谨性。
词汇升级 (Lexical Precision):
- Change →\rightarrow→ Modify / Alter
- Think →\rightarrow→ Argue / Contend
- Make →\rightarrow→ Generate / Fabricate

四、总结#

翻译的本质不是 Words to Words，而是 Meaning to Meaning。

多用名词代替动词。
多用被动代替主动。
多用连接词显化逻辑。
长短结合，利用 It 句型平衡结构。

深入理解逻辑与英语中的 “让步” (Concession)

Tue, 02 Dec 2025 01:30:00 GMT

什么是 “让步” 的逻辑内核？#

在正常的线性逻辑中，我们通常认为：

原因 A →\rightarrow→ 导致结果 B
例如：因为下雨了（A），所以我没出门（B）。←\leftarrow← 顺理成章。

但是，世界是复杂的。有时候，原因 A 发生了，它预期的结果 B 缺没有发生，反而发生了相反的结果 C。

事实 A（本来应该阻碍 C）→\rightarrow→ 依然发生了结果 C。
例如：虽然下雨了（A），但我还是出门了（C）。

这就是 “让步” 的本质：

Tip

承认一个不利于你结论的事实（这就是 “让”，退一步），然后转折，通过强调你的结论依旧成立，来反衬结论的强大（这就是 “步”，进两步）。

想象一个弹簧：你把它压下去（让步），是为了让它弹得更高（主句）。

为什么英语中如此强调 “让步”？#

在英语学习中经常看到 “让步状语从句”（Adverbial Clause of Concession），是因为英语非常注重逻辑连接词（Connectives）。

在中文里，我们往往靠语境来表达：“下雨了，我还是去了。”（没有关联词，你也懂）。但在英语里，必须用逻辑连接词把这个逻辑关系标出来。

常见的表达 “让步” 的逻辑连接词#

英语里的 Although, Though, Even if, Despite, In spite of 都在大声喊：“注意！下面我要说一个跟前面预期相反的结论了！”

经典的 “虽然……但是……” 陷阱#

这是中国学生最容易错的地方。

中文逻辑：因为有冲突，所以既要说“虽然”，又要说“但是”来强调冲突。例如：虽然他很穷，但是他很开心。 (双重标记)。

而在英文逻辑中：只要你用了 “虽然（Although）”，逻辑关系就已经确立了，再加“但是（But）”就是废话（Redundant）。例如：Although he is poor, he is happy. (正确)，而 Although he is poor, but he is happy. (错误)

为什么我们需要 “让步”？#

你可能会问：“为什么要这么麻烦？直接说结论不就行了吗？”。比如，为什么要说 “虽然我很忙，但我会帮你”？直接说 “我会帮你” 不行吗？运用“让步”逻辑，通常有三个高级目的：

增强论证的力度（反衬法）#

普通说法： “这个电机性能很好。”（平铺直叙）让步说法： “虽然这个电机体积只有拳头大，但它能输出巨大的扭矩。”

通过承认“体积小”这个通常的劣势，反衬出“扭矩大”这个技术指标的强悍。这就是工程思维中的 Trade-off（权衡）后的亮点。

展现思维的严谨性（防守反击）#

在与他人进行辩论时，如果你只说自己对，别人会觉得你偏激。而如果采用让步策略： “我承认（Concede）你的观点 X 在某些情况下是有道理的（让一步），但是，在当前的核心场景下，我的方案 Y 更优。”

以此达到的效果效果是你先封堵了对方的嘴，表明你考虑过反对意见，显得你客观、全面。

礼貌与情商（缓冲地带）#

直接拒绝： “你是错的。”（太生硬），而如果采用让步拒绝： “尽管你的出发点是好的，但这个方案目前不可行。”，以此达到的效果：先肯定对方的一部分（给面子），再否定核心内容。

总结#

回到最开始的问题，“让步”到底是什么意思？

字面上：先退一步，承认障碍或对立面的存在。
逻辑上：即使有 XXX 这个干扰因素，结论 YYY 依然成立。
功能上：它是一种**“欲扬先抑”**的思维工具。

简而言之：让步，就是为了让你的结论看起来更不容易、更坚定、或者更客观，而故意先承认一些相反事实的逻辑手段。

CS2 游戏设置优化

Tue, 25 Nov 2025 15:00:00 GMT

CS2（Counter-Strike 2）是 Valve 推出的经典第一人称射击游戏，继承了 CS 的核心玩法并全面升级了 Source 2 引擎。

游戏的默认设置通常并不适合竞技，我们需要做出一些更改。本文设置的核心逻辑是：流畅度（FPS） > 画面清晰度（能看清敌人） > 画面特效。

启动项设置（Launch Options）#

在 Steam 库中右键 CS2 →\rightarrow→ 属性 →\rightarrow→ 通用 →\rightarrow→ 启动选项，输入以下代码：

Terminal window

1
-novid -nojoy -consold -high +fps_max 0

novid：跳过开场动画，启动更快。
nojoy：禁用手柄支持，释放少量系统资源。
-console：开启控制台。
-high：将 CS2 进程设置为高优先级，理论上能提升性能稳定性。
+fps_max 0：解除游戏内帧率上限，让显卡全力运行。

视频设置（Video Settings）#

按 Esc →\rightarrow→ 设置 →\rightarrow→ 视频 →\rightarrow→ 高级视频

增强角色对比度（Boost Player Contrast）：【启用】（必开！这能让你在暗处更容易看清敌人，非常重要）
多重采样抗锯齿（MSAA）：【4X MSAA】（建议值。如电脑配置较低，可降至 2X。不建议关闭，否则物体边缘锯齿严重，难以看清远处的敌人）
全局阴影效果（Global Shadow Quality）：【高】或【中】（尽量要开低，因为这决定了能否看到墙角的敌人影子）
模型/贴图细节（Shader Detail）：【低】（为了提高 FPS，且画面更干净，减少干扰）
着色器细节（Shader Detail）：【低】（CS2 的水面和燃烧瓶）
粒子细节（Praticle Detail）：【低】（同上）
环境光遮蔽（Ambient Occlusion）：【禁用】（一种增加画面深度的特效，但会显著降低 FPS，对竞技无益）
高动态范围（HDR）：【性能】（Performance）
NVIDIA Reflex 低延迟：【启用 + 增强】（减少鼠标延迟，手感更跟手）

常规视频设置：

显示模式：【全屏】（必须全屏，窗口化会有输入延迟）
刷新率：选你显示器支持的最高数值（例如 144Hz，240Hz，这在 FPS 游戏中至关重要）

鼠标与感度（Mouse & Sensitivity）#

核心原则：千万不要用过高的灵敏度。低灵敏度能提供更强的稳定性和精准度。

鼠标 DPI（硬件）：建议设置为 400 或 800（大多数职业选手的选择）
游戏内灵敏度
- 如果你是 800 DPI，建议灵敏度在 0.8 - 1.2 之间。
- 如果你是 1600 DPI，建议灵敏度在 0.4 - 0.6 之间。
- 原则：你需要能够用一次从鼠标垫最左滑到最右的操作，在游戏中转身 180 度多一点点即可。太快了你根本瞄不准头。
变焦灵敏度（狙击镜）：1.00（默认即可）。

特别提醒：请务必在 Windows 系统鼠标设置中，关闭“提高指针精确度”（Mouse Acceleration）。这对形成肌肉记忆非常有害。

游戏设置（Game Settings）#

主要调整 HUD（界面）和雷达，让你对战局更加清晰。

最大匹配延迟：100（防止匹配到太远的服务器，太卡没法玩）。
启用开发者控制台（~）：【是】（以后你会用到很多指令）。

雷达/平板（Radar）：非常重要，默认雷达太小了

雷达地图定中玩家：【是】
雷达旋转：【是】
雷达缩放（Radar Scale）：0.40 - 0.50（建议调小一点，这样你能看到大半张地图的信息，防止队友报点你看不到）。
HUD 比例：可以稍微调小（0.9），让视野更开阔。

音频设置（Audio）#

主音量：适中。
音频均衡器：【清晰】（Crisp）（通常能让脚步声更明显）。
L/R 隔离度：50% - 70% 之间。
音乐：
- 主菜单音量：随意。
- MVP 音量：建议调低，太吵。
- 炸弹/人质音量（Ten Second Warning）：【10% - 15%】（这个必须开！当音乐响起时，说明炸弹还有 10 秒爆炸，此时如果没有拆弹器就赶紧跑保抢，不要去拆了）。
- 其他音乐：全部设为 0（避免干扰听脚步）。

准星推荐（Crosshair）#

新手不建议用动态准星（走路回扩散的那种），建议用静态准星。

风格：经典（静态）
颜色：绿色、青色或黄色（在地图中对比度高，容易看清）。
中心点：不建议开

推荐代码：按 Esc →\rightarrow→ 设置 →\rightarrow→ 游戏 →\rightarrow→ 准星 →\rightarrow→ 分享或导入，粘贴下面的代码：

ZywOo (世界顶级选手同款，小且精准): CSGO-Qzpx5-BRLwA-xEljr-coqJp-hzrLq
简单易用的十字 (适合新手): CSGO-7ANjy-XxRae-25YoE-7Bfnp-QQSFE

装备（Loadout）#

CS2 采用 5-5-5 装备选择系统，你需要为每个栏位预设好枪械。

T 方配置（恐怖分子）#

T 的枪械的特点是：便宜、威力大（AK 能一枪爆头）、**适合进攻。

手枪（Pistos）：

Glock-18（格洛克，默认）：自带的。跑打精准度高，适合手枪局一群人冲锋。
P250：只要 $300，没钱时买一把，近距离大头很痛。
Tec-9：T 方跑打之王。一定要带！它的射速快、弹匣大、移动射击极其精准。非常适合新手冲锋破点。
Desert Eagle（沙鹰）：$700 的“手炮”。虽然难用，但是还是带上吧，虽然也用不到。
Dual Berettas (双持贝瑞塔或双枪): 备选，近距离火力压制强。

中级武器（Mid-Tier）：

MAC-10 (吹风机): 必带。T方经济局神器，跑得飞快，贴脸无敌，而且很便宜。
MP7: 稍微贵一点，但比 MAC-10 更稳，适合稍微远一点的距离。
XM1014 (连喷): 全自动散弹枪，在特定地图（如办公室、炼狱小镇）用来无脑推土。

步枪（Rifles）：

AK-47: 核心中的核心。CS2 的灵魂，一枪爆头必杀。必须练好。
Galil AR（加利尔/咖喱）: 穷人救星。当你钱不够买 AK 时，$1800 的咖喱是性价比最高的选择，弹匣大（35发），容错率高。
SG 553: 带瞄准镜的步枪。虽然射速慢，但架点稳，打远距离比 AK 容易。
SSG 08（鸟狙）: 便宜的狙击枪，移动速度快。
AWP（大狙）: 必须带，哪怕你不玩，也要帮队友买。

CT 方配置（反恐精英）#

CT 的枪械特点是：精准、消音、适合架点防守，但普遍较贵，且主战步枪不能一枪爆头（有头盔时）。

手枪（Pistols）：

USP-S（默认）: 推荐选 USP 而不是 P2000。USP 有消音器，且第一发非常准，适合远距离点名。
P250: 经济局混起专用。
Five-SeveN（57/FN57）: CT方近战神枪。一定要带（替换掉 CZ75）。它的穿甲能力极强，弹匣大，当 T rush 过来时，这把手枪经常能刷屏。
Desert Eagle: 同上。

中级武器（Mid-Tier）：

MP9（小蜜蜂）: CT方最强冲锋枪。射速极快，是反制 T Rush 的神器。跑着打、跳着打都很准。
MAG-7（警喷）: 只有 5 发子弹，但它是唯一一把跳起来打依然精准的喷子，非常适合守门口。

步枪（Rifles）：

M4A1-S (消音M4): 新手强烈推荐，后坐力极小，非常好压枪。
FAMAS (法玛斯): CT 的经济步枪。当你钱不够买 M4 时只能买它，虽然手感一般，但还得带。
AUG: 带镜子的 M4。当你守长距离点位（如 Dust2 A大）时，开镜很稳。
AWP: 防守方的威慑力核心。
SSG 08: 鸟狙。

其他#

PP-Bizon（野牛）：非常推荐，跑打真的很爽，建议多玩。只要第一局什么都不起（不买甲，不买道具），哪怕手枪局输了，后面也能把把起全甲 + 野牛。
M249：价格昂贵（$5200），性能笨重，实战性价比极低。不建议新手购买，有这钱不如给大哥发把大狙，再给自己买把野牛冲前面给大哥拿信息。

小米手机 (HyperOS/MIUI) 深度优化指南：移除 AI 组件与去广告

Tue, 25 Nov 2025 14:00:00 GMT

随着 HyperOS 和 MIUI 的更新，系统集成了越来越多的 AI 功能和后台服务。虽然部分功能很实用，但对于追求极致流畅、隐私保护或老机型用户来说，这些组件可能意味着额外的耗电和卡顿。

本文将介绍如何通过 ADB (Android Debug Bridge) 安全地移除这些组件，并进行系统级优化。

通过 ADB 卸载 AI 及冗余组件#

此操作不需要 ROOT 权限，但需要一台电脑（Windows/Mac/Linux 均可）。

1. 准备工作#

开启开发者模式：
- 进入设置 →\rightarrow→ 我的设备 →\rightarrow→ 全部参数。
- 连续点击“OS 版本号”约 5-7 次，直到提示“您已处于开发者模式”。
开启 USB 调试：
- 进入设置 →\rightarrow→ 更多设置 →\rightarrow→ 开发者选项。
- 开启**“USB 调试”**。
- 开启 “USB 调试（安全设置）”（重要：如果不开启此项，部分系统应用无法被卸载，提示 Permission denied）。
连接电脑：
- 使用数据线连接手机与电脑。
- 在电脑上下载并解压 SDK Platform Tools (ADB 工具包)。

2. 执行卸载命令#

在电脑终端（CMD 或 Powershell）进入 ADB 工具目录，输入以下命令确认连接：

Terminal window

1
adb devices

如果手机弹出授权窗口，请点击“允许”。看到设备序列号后，即可使用以下格式卸载应用：

Terminal window

1
adb shell pm uninstall --user 0 <包名>

注意：--user 0 表示仅针对当前用户卸载，不会破坏系统分区。如果出现问题，可以通过恢复出厂设置完全还原。

3. 建议卸载的清单#

以下是小米系统中常见的 AI 相关及“臃肿”组件的包名。请根据你的需求选择性执行：

🤖 核心 AI 与语音组件#

如果你不使用小爱同学，这些服务在后台占用大量资源。

组件名称	包名	说明
小爱同学	`com.miui.voiceassist`	语音助手主程序
小米 AI 引擎	`com.xiaomi.aiasst.service`	场景识别、AI 调度
AI 视觉/传送门	`com.miui.contentextension`	屏幕识别、选词搜索
小爱建议/负一屏	`com.miui.personalassistant`	桌面左侧的负一屏
小爱翻译	`com.xiaomi.scanner`	包含扫一扫和翻译功能

📢 广告与分析组件 (推荐删除)#

这些组件主要用于推送广告和收集数据，删除后系统更清爽。

组件名称	包名	说明
系统广告服务 (MSA)	`com.miui.systemAdSolution`	MIUI System Ads，广告核心
小米分析	`com.miui.analytics`	数据采集与分析
用户反馈	`com.miui.miservice`	反馈服务
智能服务	`com.miui.hybrid`	混合推送服务
快应用服务框架	`com.miui.hybrid.accessory`	经常误触打开快应用

📦 其他常见臃肿软件#

组件名称	包名	说明
小米浏览器	`com.android.browser`	建议使用 Chrome 或 Edge 替代
小米视频	`com.miui.video`	包含大量在线内容
小米音乐	`com.miui.player`	QQ 音乐简化版，可以试一试
小米钱包	`com.mipay.wallet`	如果不用 NFC 刷卡可删

4. 如何恢复误删的应用？#

如果你不小心删除了重要组件，可以通过以下命令恢复（无需重置手机）：

Terminal window

1
adb shell cmd package install-existing <包名>

例如恢复小爱同学：adb shell cmd package install-existing com.miui.voiceassist

5. 推荐工具：UAD#

如果你觉得敲命令太麻烦，可以使用开源图形化工具 UAD (Universal Android Debloater)。

UAD 是一个跨平台的图形界面软件，能自动识别小米手机的臃肿软件，并标注“安全删除”、“谨慎删除”，非常适合新手。

⚠️ 警告：绝对不要卸载 com.miui.home（系统桌面）或 com.android.systemui，否则手机会黑屏或无法进入系统。

系统设置优化#

除了卸载软件，正确的设置也能显著提升体验。

1. 关闭内存扩展 (Memory Extension)#

路径：设置 →\rightarrow→ 更多设置 →\rightarrow→ 内存扩展
建议：关闭
原因：这个功能使用闪存（Flash Storage）模拟内存（SWAP）。手机闪存的随机读写速度远低于物理内存（RAM）。开启后不仅不会让手机变快，反而会增加 I/O 负担，导致系统在切换应用时掉帧，并增加发热和耗电。对于 8GB 及以上内存的机型，此功能完全是副作用。

2. 关闭系统广告开关#

虽然卸载了 MSA，但部分开关仍建议手动关闭以防漏网之鱼。

系统工具广告：设置 →\rightarrow→ 账号 →\rightarrow→ 关于小米账号 →\rightarrow→ 系统广告 →\rightarrow→ 关闭。
应用内推荐：分别进入天气、日历、下载管理、应用商店、文件管理的设置中，找到并关闭“内容推荐”、“个性化服务”或“资讯”。

3. 调整动画速度#

路径：开发者选项 →\rightarrow→ 向下滚动找到绘图栏目。
设置：
- 窗口动画缩放 →\rightarrow→ 0.5x
- 过渡动画缩放 →\rightarrow→ 0.5x
- Animator 时长缩放 →\rightarrow→ 0.5x
效果：这不会改变手机的实际处理速度，但会缩短 UI 动画的持续时间，让手机在体感上响应更加迅速干脆。

*免责声明：本文提供的操作涉及系统层面的修改。虽然通过 pm uninstall --user 0 卸载应用通常是安全的且可逆的，但操作不当仍可能导致系统不稳定。

在 Windows 上使用 Docker、Git Bash 和 overleaf-toolkit 部署 Overleaf 社区版

Sat, 18 Oct 2025 14:30:00 GMT

0. 前言#

Overleaf 是一个广受欢迎的在线 LaTeX 编辑器，它极大地简化了 LaTeX 的使用门槛。虽然官方提供了在线服务，但是处于数据隐私、网络稳定或自定义需求，我们常常希望搭建一个私有的 Overleaf 实例。Overleaf 官方提供了基于 Docker 的 toolkit 工具来简化社区版的部署流程。

然而，官方的 toolkit 主要面向 Linux/macOS 环境，在 Windows 上通过 Git Bash 执行时会遇到一个棘手的路径问题。本教程将详细记录如何在 Windows 11/10 环境下，借助 Docker Desktop 和 Git Bash，成功部署 Overleaf 社区版，并提供关键的脚本修复方案。

1. 环境准备#

在开始之前，请确保你的系统已安装并正确配置了以下软件：

Windows 10/11：需开启 Hyper-V 或 WSL 2 功能
Docker Desktop for Windows：建议使用 WSL 2 后端，性能更佳。安装后请确保 Docker 服务已正常启动。
Git for Windows: 安装时请务必勾选 Git Bash Here 选项，我们将使用它来执行 shell 脚本。

笔者环境参考：

OS: Windows 11 Professional 24H2
Docker: 28.5.1
Git: 2.51.0.windows.2

2. 部署步骤#

第一步：克隆 Overleaf Toolkit 仓库#

首先，打开 Git Bash，选择一个你喜欢的工作目录（例如 D:\），然后执行以下命令克隆官方的 toolkit 仓库：

Terminal window

1
# 进入 D:\
2
cd /d
3

4
# 克隆官方仓库
5
git clone https://github.com/overleaf/toolkit.git ./overleaf-toolkit
6
cd ./overleaf-toolkit

第二步：修复 Windows 路径兼容性问题#

这是整个教程最核心的一步。官方的 docker-compose 脚本在生成容器挂载路径时，没有正确处理 Git Bash 在 Windows 上的路径格式，导致 Docker 无法找到数据卷。

我已就此问题向官方提交了 Issue #379，并提交了修复方案 PR #380。

鉴于此 PR 还并未被合并到主分支，需要用户自行进行修改。

解决方案如下：

使用你喜欢的代码编辑器（如 VS Code 或者记事本）打开 bin/docker-compose 文件。

找到 set_base_vars() 函数，其中有两次对 OVERLEAF_IN_CONTAINER_DATA_PATH 变量的赋值。我们需要在路径的开头额外添加一个斜杠 /。

修改前：

Terminal window

1
OVERLEAF_IN_CONTAINER_DATA_PATH=/var/lib/overleaf

修改后：

Terminal window

1
OVERLEAF_IN_CONTAINER_DATA_PATH=//var/lib/overleaf

注意：此函数有两处 OVERLEAF_IN_CONTAINER_DATA_PATH=/var/lib/overleaf，请务必全部修改。这个修改的本质是帮助 Git Bash/MSYS2 正确地将 POSIX 风格的路径 /var/lib/overleaf 转换为 Docker 能理解的 Windows 路径。

第三步：初始化并启动 Overleaf 服务#

修改脚本后，我们回到 Git Bash 终端，继续在 overleaf-toolkit 目录下执行命令。

初始化 Overleaf 配置#

执行 init 命令，该命令会生成初始化配置文件，例如 config/overleaf.rc、config/variables.env、config/version 等。

Terminal window

1
./bin/init

启动 Overleaf 容器服务#

初始化完成后，执行 up 命令来启动所有服务。

Terminal window

1
./bin/up

提示：首次执行时，由于需要下载多个 Docker 镜像，此过程可能会持续较长时间，具体取决于你的网络速度。请耐心等待，确保所有镜像都成功拉取。

执行成功后，你将看到大量的服务日志输出。

第四步：首次访问与管理员配置#

服务启动后，打开你的浏览器，访问 http://127.0.0.1。

首次访问时，你会被引导至管理员账户创建页面。请根据提示设置你的第一个管理员用户的邮箱和密码。创建成功后，你就可以使用这个账户登录并开始使用你的私有 Overleaf 实例了！

3. 日常管理#

在日常使用中，你可能会需要启动或停止 Overleaf 服务。

停止服务：在 overleaf-toolkit 目录下打开 Git Bash，执行：

Terminal window

1
./bin/stop

重新启动服务：同样，在 overleaf-toolkit 目录下执行：

Terminal window

1
./bin/up

总结#

通过对 bin/docker-compose 脚本进行一个小小的修改，我们成功解决了 overleaf-toolkit 在 Windows + Git Bash 环境下的路径兼容性问题，顺利地部署了 Overleaf 社区版。自托管 Overleaf 不仅保障了数据安全，还提供了更自由的定制空间。

希望这篇教程能帮助到同样遇到此问题的同学。

Notes of Effective CMake

Fri, 08 Aug 2025 15:17:00 GMT

1. The Philosophy of Modern CMake#

Why “Effective CMake”?#

Just like with C++, the way you write CMake code significantly impacts your project’s maintainability, ease of use for others, and scalability. Adopting modern practices is key.

CMake is Code#

Treat your CMakeLists.txt files with the same care as your source code. Apply principles like Don’t Repeat Yourself (DRY), keep it clean, and write comments where necessary.

2. The CMake Language: A Quick Tour#

Organization#

CMake code can be organized in three ways:

Directories (CMakeLists.txt): The entry point for a project or sub-project. add_subdirectory() adds another directory (which must contain a CMakeLists.txt) to the build.
Scripts (<name>.cmake): Executed with cmake -P <script>.cmake. They are useful for automation but cannot define build targets like executables or libraries. In other words, not all commands are supported.
Modules (<name>.cmake): Reusable code included in your projects via include(). They are located in the CMAKE_MODULE_PATH.

Commands#

CMake commands are case-insensitive, but their arguments (including variable names) are case-sensitive.

1
# command_name(ARGUMENT1 ARGUMENT2 ...)
2
project(MyProject VERSION 1.0)

Caution

Command invovations are not expressions, so you cannnot put a command invocation directly as an argument of another command or inside an if condition. They are not possible.

Variables#

1
# Set a variable
2
set(MY_VARIABLE "Hello")
3

4
# Reference a variable (dereference)
5
message(STATUS "My variable is: ${MY_VARIABLE}")
6

7
# Unset a variable
8
unset(MY_VARIABLE)

IMPORTANT

In CMake, everything is a string. Lists are just strings separated by semicolons ; (e.g., "item1;item2;item3").
An unset or undefined variable expands to an empty string. This can be a common source of bugs! Use if(DEFINED VAR_NAME) to check if a variable is set.
CMake variables are not environment variables (unlink Makefile).

WARNING

Avoid custom variables in the arguments of project commands.

In modern CMake, what we need is targets and properties. See them later.

Comments#

1
# This is a single-line comment.
2

3
#[=[
4
This is a multi-line comment.
5
It can contain other symbols and even # characters.
6
#]=]

Generator Expressions: The `$<...>` Syntax#

Generator expressions, often called “genex,” are a powerful CMake feature that uses the $<...> syntax. They are not evaluated when CMake first reads your CMakeLists.txt. Instead, they are written into the native build files (like Makefiles or Visual Studio projects) and are evaluated during the build process.

This delayed evaluation is crucial because it allows you to create build configurations that are aware of things that are only known at build time, such as the specific build type (Debug, Release), the compiler being used, or the language of a source file.

IMPORTANT

Think of generator expressions as placeholders that the final build tool (like Make, Ninja, or MSBuild) will fill in with the correct value at the right time. This is much more flexible than using if() statements in CMake, which are only evaluated once when you run cmake.

Common Use Cases and Examples#

Conditional Compilation Definitions ($<CONFIG:...>)

This is the most common use case. You want to define a preprocessor macro differently for Debug and Release builds.

1
# In Debug mode, VERBOSITY will be 2. In all other modes (e.g., Release), it will be 0.
2
target_compile_definitions(my_app PRIVATE
3
    "VERBOSITY=$<IF:$<CONFIG:Debug>,2,0>"
4
)

The $<IF:condition,true_value,false_value> expression is evaluated at build time. If the configuration is Debug, it resolves to VERBOSITY=2; otherwise, it becomes VERBOSITY=0.

Conditional Include Directories ($<BUILD_INTERFACE:...> and $<INSTALL_INTERFACE:...>)

A library often has different include paths when being built inside a project versus when it’s installed on a system.

1
target_include_directories(my_lib PUBLIC
2
    # When my_lib is built as part of this project, use the source directory.
3
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
4

5
    # When an external project uses an installed version of my_lib, the path is just 'include'.
6
    $<INSTALL_INTERFACE:include>
7
)

This ensures your library is usable both during development and after deployment without any changes.

Compiler-Specific Flags ($<CXX_COMPILER_ID:...>)

You can pass specific flags depending on the compiler being used (e.g., GCC, Clang, MSVC).

1
# Enable strong warnings, but use the correct flag for each compiler.
2
set(GCC_CLANG_WARNINGS "-Wall -Wextra -Wpedantic")
3
set(MSVC_WARNINGS "/W4")
4

5
target_compile_options(my_app PRIVATE
6
    "$<IF:$<CXX_COMPILER_ID:MSVC>,${MSVC_WARNINGS},${GCC_CLANG_WARNINGS}>"
7
)

Language-Specific Standards ($<COMPILE_LANGUAGE:...>)

If your target mixes C and C++ code, you can set standards for each language.

1
target_compile_features(my_app PRIVATE
2
    # Set C++ standard to 17 for all C++ files.
3
    $<COMPILE_LANGUAGE:CXX>:cxx_std_17
4

5
    # Set C standard to 11 for all C files.
6
    $<COMPILE_LANGUAGE:C>:c_std_11
7
)

Generator expressions are a cornerstone of modern, robust, and portable CMake scripts. Mastering them allows you to write cleaner and more powerful CMakeLists.txt files.

Custom Commands: `function()` vs. `macro()`#

You can create your own commands to reduce code duplication.

function(): Creates a new variable scope. To pass results back to the caller, you must use set(... PARENT_SCOPE).
macro(): Does not create a new scope. It performs simple text replacement, much like a C preprocessor macro.

TIP

Rule of Thumb:

Use function() by default to avoid polluting the caller’s scope with side effects.
Use macro() only when you need to wrap a command that has an output parameter or when you explicitly want side effects in the caller’s scope.

3. The Core of Modern CMake: Targets and Properties#

Modern CMake revolves around targets and their properties. A target can be an executable, a library, or a custom target.

WARNING

Avoid directory-level commands like include_directories(), link_libraries(), and add_compile_options(). They use global state and make dependencies hard to reason about. Always prefer the target_* equivalents.

WARNING

Don’t use file(GLOB) in your CMakeLists.txt anymore.

Thinking in Targets#

Imagine targets as objects in an OOP language.

Constructor: add_executable(), add_library()
Member Functions: target_sources(), target_include_directories(), target_link_libraries(), etc.
Member Variables: Properties like VERSION, SOURCES, INTERFACE_INCLUDE_DIRECTORIES.

1
# Create a library target
2
add_library(my_lib STATIC my_lib.cpp my_lib.h)
3

4
# Add properties to the target
5
target_include_directories(my_lib PUBLIC include)
6
target_compile_features(my_lib PUBLIC cxx_std_17)

Build Specifications vs. Usage Requirements#

Non-INTERFACE_ properties define the build specification of a terget
INTERFACE_ properties define the usage requirements of a target.

This is the most critical concept in modern CMake. When you link a library, the consumer needs to know its include directories, compile definitions, etc.

PRIVATE: The property is only for building this target. It is not passed on to consumers (Non-INTERFACE_).
INTERFACE: The property is only for consumers of this target. The target itself doesn’t use it for its own build. This is perfect for header-only libraries (INTERFACE_).
PUBLIC: The property is for both the target’s build (PRIVATE) and for its consumers (INTERFACE).

Example#

1
# A logging library that uses spdlog internally
2
add_library(my_logger my_logger.cpp)
3

4
# my_logger needs the spdlog headers to compile.
5
# Anyone who uses my_logger does NOT need spdlog headers directly.
6
target_include_directories(my_logger
7
    PRIVATE
8
        ${spdlog_SOURCE_DIR}/include
9
)
10

11
# Anyone who uses my_logger needs my_logger's own headers.
12
target_include_directories(my_logger
13
    PUBLIC
14
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
15
        $<INSTALL_INTERFACE:include> # Different path after installation
16
)

展开收起

Header-Only Libraries#

For libraries that are headers-only, create an INTERFACE library. It has no sources and only defines usage requirements.

1
add_library(my_header_lib INTERFACE)
2

3
target_include_directories(my_header_lib INTERFACE
4
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
5
    $<INSTALL_INTERFACE:include>
6
)

WARNING

The library interface may change during installation. Use the BUILD_INTERFACE and INSTALL_INTERFACE generator expressions as filters

4. Working with Dependencies#

Finding Packages with `find_package()`#

This is the standard way to find and use external libraries that have been installed on the system or are part of the project.

1
# Find the Boost library, version 1.71 or newer.
2
# It is REQUIRED; CMake will fail if it's not found.
3
find_package(Boost 1.71 REQUIRED COMPONENTS system thread)
4

5
# If found, use the imported target provided by Boost
6
if(Boost_FOUND)
7
    target_link_libraries(my_app PRIVATE Boost::system Boost::thread)
8
endif()

Note

Regardless of the mode/package used, a <PackageName>_FOUND variable will be set to indicate whether the package was found.

IMPORTANT

Always use the official, namespaced, imported targets (e.g., Boost::system, Qt5::Core, GTest::GTest). Never use the old-style _LIBRARIES and _INCLUDE_DIRS variables. Imported targets handle all dependency properties for you automatically.

IMPORTANT

Use a Find module for third party libraries that are not built with CMake that don’t support clients to use CMake. Also, report this as a bug to their authors.

If you need to write a find module for a third-party library, report this as a bug to the authors. Because most people use CMake, it’s a problem that don’t support it.

Fetching Dependencies at Configure Time with `FetchContent`#

For dependencies that you want to download and build alongside your project, FetchContent is the modern, preferred approach. It’s great for ensuring all developers use the exact same version of a dependency.

1
include(FetchContent)
2

3
# Declare the dependency
4
FetchContent_Declare(
5
    googletest
6
    GIT_REPOSITORY https://github.com/google/googletest.git
7
    GIT_TAG        release-1.12.1
8
)
9

10
# Make it available (downloads and adds it as a sub-project)
11
FetchContent_MakeAvailable(googletest)
12

13
# Now you can link to it just like any other target in your project
14
target_link_libraries(my_tests PRIVATE GTest::GTest GTest::Main)

Note

FetchContent is generally preferred over Git submodules because it gives the parent project more control and is easier to manage.

Exporting Your Project as a Package#

When you want other projects to use your library with find_package(), you need to generate package configuration files.

Install Targets: Use install(TARGETS ...) to specify where your library files (.a, .so, .dll) and headers should be installed. Use the EXPORT keyword to associate them with a target export set.
Install Export Set: Use install(EXPORT ...) to create a <name>Targets.cmake file. This file contains the definitions of your imported targets (e.g., MyLib::MyLib).
Create Version and Config Files: Use CMakePackageConfigHelpers to generate a version file (<name>ConfigVersion.cmake) and write a config file (<name>Config.cmake). The config file is the entry point that find_package looks for.

This process tells other projects how to use your library by defining an imported target like YourProject::YourLib.

For example:

1
# standard steps to build the library
2
find_package(Bar 2.0 REQUIRED)
3
add_library(Foo ...)
4
target_link_libraries(Foo PRIVATE Bar::Bar)
5

6
# 1. Install targets
7
install(TARGETS Foo EXPORT FooTargets
8
    LIBRARY DESTINATION lib
9
    ARCHIVE DESTINATION lib
10
    RUNTIME DESTINATION bin
11
    INCLUDES DESTINATION include)
12

13
# 2. Install Export Set
14
install(EXPORT FooTargets
15
    FILE FooTargets.cmake
16
    NAMESPACE Foo::
17
    DESTINATION lib/cmake/Foo)
18

19
# 3. Create Version file
20
include(CMakePackageConfigHelpers)
21
write_basic_package_version_file("FooConfigVersion.cmake"
22
    VERSION ${Foo_VERSION}
23
    COMPATIBILITY SameMajorVersion
24
    )
25
install(FILES "FooConfig.cmake" "FooConfigVersion.cmake"
26
    DESTINATION lib/cmake/Foo)

展开收起

Create and write config files FooConfig.cmake:

1
include(CMakeFindDependencyMacro)
2
find_dependency(Bar 2.0)
3
include("$${CMAKE_CURRENT_LIST_DIR}/FooTargets.cmake")

5. Testing with CTest#

CTest is CMake’s testing framework. It acts as a test driver, running test executables and reporting results.

Basic Setup#

Enable Testing: Add enable_testing() to your root CMakeLists.txt. This command should be called only once in the top-level project.
Add Tests: Use add_test() to define a test case. A test is typically an executable that returns 0 for success and non-zero for failure.

1
# In your tests/CMakeLists.txt
2
add_executable(run_all_tests tests.cpp)
3
target_link_libraries(run_all_tests PRIVATE my_lib GTest::GTest GTest::Main)
4

5
# Define a test named "MyLib.UnitTests" that runs the "run_all_tests" executable.
6
add_test(NAME MyLib.UnitTests COMMAND run_all_tests)

TIP

It’s a good practice to adopt a naming convention for your tests, like Project.Component.TestType. This makes filtering much easier.

Running Tests#

You can then run all tests from your build directory:

Terminal window

1
# Run all tests, with 4 parallel jobs and verbose output on failure
2
ctest -j4 --output-on-failure

Advanced: Filtering Tests#

You can run a subset of your tests using a regular expression with the -R flag.

Terminal window

1
# Run only the tests whose names start with "MyLib."
2
ctest -R "^MyLib\\."

Advanced: Testing for Compile Failure#

Sometimes, you want to ensure that certain code fails to compile (e.g., when testing static_assert). You can create a test for this.

1
# Create a library that is expected to fail compilation.
2
# EXCLUDE_FROM_ALL prevents it from being built during a normal build.
3
add_library(foo_fail STATIC EXCLUDE_FROM_ALL foo_fail.cpp)
4

5
# Add a test that tries to build this specific target.
6
# The test "passes" if the build command fails.
7
add_test(NAME Foo.CompileFail
8
    COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target foo_fail
9
)
10

11
# We can even check for a specific error message in the build output.
12
# The test passes if the build fails AND the output contains this regex.
13
set_tests_properties(Foo.CompileFail PROPERTIES
14
    PASS_REGULAR_EXPRESSION "static assert message"
15
    WILL_FAIL TRUE # Informs CTest that a non-zero return code is expected (success)
16
)

展开收起

Advanced: Driving CTest with a Script#

For complex testing scenarios, especially in CI/CD environments, you can use a CMake script to drive CTest.

build_and_test.cmake

1
# This script automates the configure, build, test, and submit steps.
2
set(CTEST_SOURCE_DIRECTORY "/path/to/source")
3
set(CTEST_BINARY_DIRECTORY "/path/to/build")
4

5
set(CTEST_CMAKE_GENERATOR "Ninja") # Specify the generator
6

7
ctest_start("Continuous") # Start a new CTest run
8
ctest_configure()         # Run cmake
9
ctest_build()             # Run cmake --build
10
ctest_test()              # Run ctest
11
ctest_submit()            # Submit results to a dashboard like CDash

You would run this script from the command line:

Terminal window

1
ctest -S build_and_test.cmake

This keeps CI-specific logic out of your main CMakeLists.txt.

6. Cross-Compiling with Toolchain Files#

Cross-compiling is the process of building code on one machine (the host) that is intended to run on a different machine (the target), which may have a different architecture (e.g., building for ARM on an x86-64 host).

CMake handles this through Toolchain Files. A toolchain file tells CMake how to find the correct compilers, linkers, and libraries for the target system.

The Role of the Toolchain File#

You specify the toolchain file when you first configure your project with cmake.

Terminal window

1
# Configure the project using the my-arm-toolchain.cmake file
2
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=/path/to/my-arm-toolchain.cmake

WARNING

A toolchain file is for describing the environment, not for project logic. Avoid setting project options or variables in it. Its only job is to set up the compilers and search paths.

Example Toolchain File#

Here is an example of a toolchain file for cross-compiling to Windows from a Linux host using MinGW-w64.

mingw-toolchain.cmake

1
# The name of the target operating system
2
set(CMAKE_SYSTEM_NAME Windows)
3

4
# Specify the cross-compilers
5
set(CMAKE_C_COMPILER   x86_64-w64-mingw32-gcc)
6
set(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
7

8
# Where to find the target environment's headers and libraries
9
set(CMAKE_FIND_ROOT_PATH /usr/x86_64-w64-mingw32)
10

11
# Adjust the search behavior for programs, libraries, and includes
12
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
13
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
14
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
15

16
# Set an emulator to run target executables on the host system
17
set(CMAKE_CROSSCOMPILING_EMULATOR "wine64")

展开收起

Running Cross-Compiled Tests#

You can’t directly run a target executable on the host machine. The CMAKE_CROSSCOMPILING_EMULATOR variable (set in the toolchain file) tells CTest how to run the tests. It specifies a program (like wine for Windows apps on Linux, or qemu-arm for ARM binaries) that can emulate the target environment.

When you run ctest, it will automatically prefix test commands with the emulator:

Terminal window

1
# CTest will effectively run:
2
wine64 my_test_executable.exe

This allows you to run your unit tests on the host machine even when cross-compiling.

7. Packaging with CPack#

CPack is CMake’s packaging tool. It can create installers (NSIS, WiX), archives (.zip, .tar.gz), and Linux packages (.deb, .rpm).

Include CPack: Add include(CPack) to your root CMakeLists.txt.
Set CPack Variables: Configure package metadata by setting CPACK_* variables.

1
set(CPACK_PACKAGE_NAME "MyAwesomeApp")
2
set(CPACK_PACKAGE_VERSION "1.0.0")
3
set(CPACK_GENERATOR "ZIP;TGZ") # Create a .zip and a .tar.gz
4
# ... other variables

Run CPack from your build directory to create the packages:

Terminal window

1
cpack

8. Static Analysis Integration#

Integrating static analysis into the build process is a powerful way to enforce code quality and catch bugs early.

The Philosophy of Handling Warnings#

A common piece of advice is to “treat warnings as errors,” typically by passing the -Werror flag to the compiler. However, this approach can be counterproductive and painful.

Why -Werror Causes Pain:

Blocks Progress: You cannot enable -Werror until you have fixed every single existing warning in the codebase.
Hinders Upgrades: You cannot upgrade your compiler or increase the warning level (e.g., from -Wall to -Wextra) until you have fixed all the new warings that appear. This creates a significant barrier to modernization.
Makes Deprecation Difficult: You cannot mark your own internal APIs as [[deprecated]] as long as they are still in use, because this would generate a warning and fail the build. But once they are no longer used, you might as well just remove them.

A Better Approach: Treat New Warnings as Errors#

A more practical and agile strategy is to manage warnings in development cycles:

Allow New Warnings Temporarily: At the beginning of a development cycle (e.g., a new sprint), allow new warnings to be introduced. This is the time to upgrade compilers, update dependencies, or enable more aggressive warning flags.
Burn Down Warnings: During the cycle, the team’s goal is to fix all existing warnings and drive the count back down to zero.
Repeat: This iterative process allows for continuous improvement without bringing development to a halt.

Pull Out All the Stops: Powerful Analysis Tools#

Modern C++ has a rich ecosystem of static analysis tools that go far beyond compiler warnings. You should integrate them into your build.

clang-tidy: A Clang-based linter framework to diagnose and fix typical programming errors, style violations, and interface misuse. cpplint: An automated checker to ensure code adheres to Google’s C++ style guide.
include-what-you-use (IWYU): A tool for analyzing #includes to ensure you include exactly what you use, which can improve compile times and code clarity.
clazy: A Clang plugin that finds Qt-specific antipatterns and performance issues.

Modern CMake Integration via Target Properties#

Modern CMake provides dedicated target properties to run these tools alongside the compiler.

<LANG>_CLANG_TIDY
<LANG>_CPPLINT
<LANG>_INCLUDE_WHAT_YOU_USE
LINK_WHAT_YOU_USE (Checks for unused library links)

Where <LANG> is C or CXX. These properties are initialized by their corresponding CMAKE_... variables.

1
# Example of enabling clang-tidy and include-what-you-use
2
set_target_properties(my_app PROPERTIES
3
    CXX_CLANG_TIDY "clang-tidy;-checks=-*,readability-*,modernize-*"
4
    CXX_INCLUDE_WHAT_YOU_USE "include-what-you-use;-Xiwyu;--mapping_file=/iwyu.imp"
5
)

IMPORTANT

The major advantage of this approach is that diagnostics from these tools are seamlessly integrated into your build output and appear directly in your IDE, just like regular compiler errors and warnings.

Best Practice: Analyzing Header Files#

A common pitfall is that header files without an associated source file (.cpp) will not be analyzed.

TIP

For each header file, ensure there is an associated source file that #include it, preferably as the very first line. This source file can even be empty otherwise.

You can use a simple script to create these missing source files:

1
#!/usr/bin/env bash
2
# Create an empty .cpp file for every .h file that doesn't have one.
3
for fn in `comm -23 \
4
            <(ls *.h | cut -d '.' -f 1 | sort) \
5
            <(ls *.c *.cpp | cut -d '.' -f 1 | sort)`
6
do
7
    echo "#include \"$fn.h\"" >> $fn.cpp
8
done

Enabling Analysis from Outside the Project

To keep your CMakeLists.txt clean, you can enable and configure these tools from the command line during the configure step. This is ideal for CI/CD pipelines.

Reference#

Visual Studio C++ 工程实践指南

Tue, 29 Jul 2025 17:50:00 GMT

解决方案（Solution）与项目（Project）#

一个解决方案是用于组织和管理一个或多个相关联项目的容器。这套结构旨在将一个复杂的实际问题，分解成多个功能独立的模块（项目）来开发和管理。

解决方案（.sln 文件）：这是最高层级的组织单位，它定义了所包含的项目以及它们之间的依赖关系和构建配置。当你打开一个 .sln 文件时，Visual Studio 会加载整个工作区。
项目（.vcxproj、csproj 等文件）：每个项目对应一个独立的模块，最终会生成一个可执行文件（.exe）、一个静态库（.lib）或一个动态链接库（.dll）。

需要注意的地方：

单一启动项目：在一个解决方案中，通常只有一个项目被设置为启动项目。启动项目是点击 “开始调试”（F5）时，Visual Studio 将会编译和运行的项目。可以在解决方案资源管理器中右键点击不同的项目，选择 “设为启动项目”。
“将解决方案和项目放在同一目录中”：
- 勾选：解决方案文件（.sln）和项目文件（例如 .vcxproj）会存放在同一个文件夹中。这对于只有一个或少数几个项目的简单解决方案来说，目录结构更扁平、更清晰。
- 不勾选（默认）：Visual Studio 会创建一个顶层文件夹来存放解决方案文件（.sln），然后在该文件夹下为每一个项目再创建一个独立的子文件夹。当解决方案包含多个项目时，这种结构更加有条理，是更推荐的做法。

过滤器（Filter）#

过滤器（Filter）是 Visual Studio 解决方案资源管理器中的一个虚拟文件夹结构。它的主要作用是帮助开发者组织和分类源文件、头文件等，使项目看起来更整洁，所有的代码文件（源文件和头文件）都应该加入过滤器中。开发者可以自由地创建、重命名或删除过滤器，这不会影响磁盘上文件的实际位置。

而对于编译器（例如 MSVC、GCC 等）在编译代码时，只关心真实的目录结构，而非过滤器中的配置。所以当编译器报错 “无法打开源文件” 或 “找不到头文件” 之类的错误时，问题几乎总是出在项目属性的路径配置上，而不是解决方案资源管理器的过滤器结构。

如何正确配置包含目录？#

当项目需要引入外部头文件（例如来自另一个项目货第三方库）时，必须明确告知编译器去哪里查找这些文件。

在解决方案资源管理器中右键点击项目，选择属性。
确保顶部的配置和平台设置正确。
导航到 C/C++ →\rightarrow→ 常规。
在附加包含目录字段中，添加所需头文件所在的真实目录路径。

在 Visual Studio 中选择的目录会被设置为绝对路径，当解决方案发生移动，或者发送给合作者时，就会导致错误。这可以通过 Visual Studio 中提供的宏来解决。

宏（Macro）#

Visual Studio 提供了一系列预定义的宏（Macro），这些宏会在构建时被动态地解析为具体的路径。

常用宏变量：

宏	描述
`$(SolutionDir)`	解决方案文件（`.sln`）所在的目录
`$(ProjectDir)`	当前项目文件（`.vcxproj`）所在的目录
`$(OutDir)`	最终输出文件（如 `.exe`、`.dll`）的存放目录
`$(IntDir)`	编译过程中产生的中间文件（如 `.obj`）的存放目录
`$(Configuration)`	当前的构建配置名称，如 `Debug` 或 `Release`
`$(Platform)`	当前的构建平台名称，如 `x64` 或 `Win32`

示例#

假设解决方案目录结构如下：

Terminal window

1
MySolution/
2
├── MySolution.sln
3
├── ProjectA/
4
│   └── ProjectA.vcxproj
5
└── Libraries/
6
    └── MyLib/
7
        └── include/
8
            └── my_header.h

如果 ProjectA 需要包含 my_header.h，则可以在 ProjectA 的 “附加包含目录” 中设置为：$(SolutionDir)\Libraries\MyLib\include。

这样一来，即使将整个 MySolution 文件夹移动到其他位置，这个相对路径依然有效。

库的使用#

静态库（Static Library，`.lib`）#

静态库是在链接阶段被并入到目标程序中的。最终生成的可执行文件会包含静态库的所有代码，因此文件体积较大，但运行时不依赖外部文件。

创建#

在解决方案中右键点击 “解决方案” →\rightarrow→ 添加 →\rightarrow→ 新建项目 →\rightarrow→ 静态库

使用#

引用#

在需要使用此库的项目上，右键点击引用
选择添加引用，然后在弹出的对话框中勾选所需的静态库项目

这是推荐的方式，原因如下：

它会自动设置链接器的输入，确保链接器能够找到库文件
它会自动创建项目依赖项，保证在编译主项目之前，静态库项目总是被优先编译
它还会自动将静态库的头文件目录添加到主项目的附加包含目录中，让开发者能够直接 #include

手动配置（不推荐）#

如果引用的库是一个已经编译好、非解决方案内的 .lib 文件，则需要手动配置：

附加库目录：在项目属性的链接器 →\rightarrow→ 常规中，添加 .lib 文件所在的目录。
附加依赖项：在项目属性的链接器 →\rightarrow→ 输入中，添加 .lib 文件的具体名称（例如 libtest.lib）

动态链接库（Dynamic Link Library，`.dll`）#

动态库是程序运行时由操作系统加载到内存中的。多个程序可以共享同一个 DLL，从而节省磁盘空间和内存。项目生成时会同时产生一个 .dll 文件（运行时需要）和一个 .lib 文件（链接时需要）。

注意事项：

导出与导入：从 DLL 中暴露函数或类给其他项目使用，需要使用 __declspec(dllexport) 关键字。而在使用该 DLL 的项目中，则需要使用 __declspc(dllimport) 来声明这些函数或类。
运行时环境：当运行依赖于 DLL 的程序时，操作系统必须能够找到这个 .dll 文件。通常由以下几种方式：
1. 将 .dll 文件放置在与可执行文件（.exe）相同的目录下
2. 将 .dll 文件所在的目录添加到系统的 PATH 环境变量中。
3. 在 Visual Studio 中进行调试时，它通常会自动处理好路径问题。

使用 CMake 自动生成解决方案#

对于跨平台项目或大型复杂项目，直接使用 Visual Studio 的项目文件进行管理可能会变得非常繁琐。CMake 是一个强大的、开源的构建系统生成工具，它可以根据简单的配置文件（CMakeLists.txt）自动生成适用与多种平台和 IDE 的原生构建环境，包括 Visual Studio 的 .sln 和 .vcxproj 文件。

手动配置#

为项目的根目录以及各个子模块（库、可执行文件）编写 CMakeLists.txt 文件。
创建一个独立的构建目录（通常命名为 build），以保持源码树的干净。
在 build 目录中运行 CMake，指令通常为 cmake ..，它会查找上一级目录的 CMakeLists.txt 并生成构建文件。
最后，用 Visual Studio 打开在 build 中生成的 .sln 文件。

原生支持#

从 Visual Studio 2017 开始，Visual Studio 提供了对 CMake 的原生集成支持。

可以直接用 Visual Studio 打开一个包含 CMakeLists.txt 的文件节哀，而无需手动运行 cmake 命令和打开生成的 .sln 文件。Visual Studio 会自动在后台完成这一切，并提供完整的智能提示、构建和调试支持。

这对于使用 CMake 的项目来说，是目前最便捷的开发方式。

参考资料#

工程课代表——Visual Studio 工程实践开发

VMware Workstation 17.x 中的虚拟机按键反应迟钝解决办法

Fri, 23 May 2025 14:34:00 GMT

问题描述#

在 VMware Workstation 17.x 中的虚拟机按键反映迟钝，具体而言即是屏幕显示的字符速度跟不上手打字的速度，你能很明显得感觉到迟钝。

特别是长按方向键选择时，长按一两秒，光标会移动好几秒，跟手性非常差，非常难受。

笔者这里所说的“跟手性”是指：当用户开始输入时，屏幕就开始刷新字符，刷新字符的速度与用户打字的速度不能差太多，并且当用户停止输入时，屏幕能立即停止刷新字符。

笔者环境#

VMware Workstatio 17 Pro：17.6.3 build-24583834
虚拟机：Ubuntu 16.04
操作系统：Windows 11 专业版 26100.4061

解决方法#

请按照以下步骤操作，修改虚拟机的配置文件：

关闭虚拟机：确保虚拟机处于完全关闭状态（Power Off），而非挂起（Suspend）。
找到配置文件：进入虚拟机所在的文件夹，找到后缀为 .vmx 的配置文件（通常与虚拟机同名）。
编辑文件：右键点击该文件，选择使用记事本（Notepad）或 VS Code 打开。
添加配置：在文件的末尾添加以下代码：

1
keyboard.vusb.enable = "TRUE"

保存并重启：保存文件后，重新启动虚拟机即可生效。

原理说明：该配置强制启用了虚拟 USB 键盘设备，绕过了某些导致延迟的输入仿真层。

测试环境#

Ubuntu 16.04
Ubuntu 18.04
Ubuntu 22.04
ElementaryOS 7 Horus

在以上虚拟机中，笔者对此方法进行了测试，都取得了很好的效果。

FAQ#

是否需要降低核心数#

网上有很多其他的教程说可以降低 CPU 的核心数，具体原理是减少虚拟机等待的时间。

笔者实测，降低 CPU 核心数确实能带来一定速度的提升，但是效果很微弱。

但是当我在 *.vmx 文件中添加了 keyboard.vusb.enable = "TRUE" 后，我将虚拟机的核心数提高到了 16 个，在虚拟机中打字时的跟手性也非常好，只是整个虚拟机有时候会有点卡顿，完全在可接受的范围内。

不过一般来说，核心数只需要设置为 1-4 即可，不然可能会拖慢宿主机的运行。

终上所述，核心数并无太大影响，读者自己有数就行。

是否需要关闭 3D 图形加速#

网上还有很多的教程说需要关闭 3D 图形加速，但是有很多软件的运行是需要这个功能的比如 Gazebo，不然就会变得非常卡。

关闭 3D 图形加速后，确实能够比较明显的感觉到在虚拟机中打字时的跟手性有改善，但是也还没有到那种可以忍受的地步（至少对我而言）。

在 *.vmx 文件中添加了 keyboard.vusb.enable = "TRUE" 后，我开启了 3D 图形加速，笔者实测打字的跟手性依旧非常好，同上的效果，只是虚拟机本身有一点卡顿，但完全在可接受的范围内。

综上所述，无需关闭 3D 图形加速。不过开启了 3D 加速确实会影响虚拟机的运行，如果你的工作不需要大量 3D 渲染的话，笔者还是建议关闭 3D 图形加速功能。

参考资料#

学习 fgets 函数和 strcspn 函数

Sun, 20 Aug 2023 15:44:31 GMT

0. 为什么要专门发布一篇文章来说明这两个函数？#

原因是今晚上在做牛客网的题目的时候，遇到了这么一个问题。

虽然这道题对大多数人来说都算是比较简单的题目，但是对于我这么一个小白还是比较难写的。最开始我是这么写的代码：

1
#include <stdio.h>
2

3
void reverse(char* arr) {
4
    char* left = arr;
5
    char* right = &arr[strlen(arr) - 1];
6
    while(left < right) {
7
        char mid = *left;
8
        *left = *right;
9
        *right = mid;
10
        left++;
11
        right--;
12
    }
13
    for(int i = 0; i < strlen(arr); i++) {
14
        printf("%c", arr[i]);
15
    }
16
}
17

18
int main(void) {
19
    char arr[10000];//之所以创建这么大一个数组是因为题目中的示例10非常长
20
    scanf("%s", arr);
21
    reverse(arr);
22
    return 0;
23
}

展开收起

但是这样写代码连题目中的示例 1：输入：I am a student；输出：tneduts a ma I 都没有通过，最终只输出了一个 I。

这是为什么呢？我思索了半天才明白是我的这一行代码 scanf("%s", arr); 有问题，就是因为 scanf("%s", arr) 会读取一个字符串，但会在遇到空格、制表符或换行符时停止。换句话说，它只会读取输入字符串中的第一个单词，然后停止。

例如，如果你输入 “Hello World”，scanf("%s", str) 会将 “Hello” 作为一个字符串读取，而 “World” 则会留在输入流中等待后续读取。

所以示例输入的 I am a student 只有 I 进入了 arr[10000] 中，剩下的字符串仍然留在输入流中等待下一次读取。所以最终自然而然也就只会输出 I。

知道了问题的原因自然就要想办法解决问题，但是说实话，对于小编这种很笨的学生来说，几乎是不可能的。所以，我就去求助了 ChatGPT。ChatGPT 给出的解决办法是使用 fgets 函数，但是我真就第一次听这个函数，也完全不懂这个函数该如何使用，于是我就准备写下这篇文章来记录我的欠缺。

那么下面就开始正题：

1. `fgets`函数#

1.1 函数介绍#

fgets 是 C 语言标准库 stdio 中的一个函数，用于从文件流（通常是标准输入流 stdin 或其他文件流）中读取一行字符串。它的主要作用是读取指定长度的字符，并且会保留换行符（如果存在的话）。

函数原型：

1
char *fgets(char *str, int n, FILE *stream);

1.2 参数说明#

str：一个指向字符数组的指针，用于存储读取的字符串。
n：要读取的最大字符数（包括字符串结尾的空字符 \0），通常为字符数组的长度。
stream：文件流指针，通常是 stdin（标准输入流）或其他文件指针。
fgets 会读取指定长度的字符，直到遇到换行符（包括换行符在内），或者读取了 n-1 个字符（包括字符串结尾的空字符 \0 ），或者到达文件末尾为止。它会将读取的字符串存储到 str 指向的字符数组中，并在字符串的末尾添加一个空字符 \0，以表示字符串的结束。

1.3 注意事项#

fgets 会保留字符串中的换行符，所以如果不需要换行符，可以使用字符串处理函数（如 strcspn）将其替换为空字符 \0。
如果输入的字符串的长度超过了指定的 n-1，fgets 只会读取 n-1 个字符，其余字符会留在输入流中，可能影响后续的输入。
fgets 在成功读取字符串时返回 str，在到达文件末尾或发生错误时返回 NULL。

1.4 使用示例#

1
#include <stdio.h>
2
#include <string.h>
3

4
int main() {
5
    char str[100]; // 最多读取 99 个字符（包括结尾的空字符）
6

7
    printf("请输入一个字符串：");
8
    fgets(str, sizeof(str), stdin); // 从标准输入读取一行字符串
9

10
    str[strcspn(str, "\n")] = '\0'; // 去掉换行符（如果有）
11

12
    printf("你输入的字符串是：%s\n", str);
13

14
    return 0;
15
}

展开收起

1.5 题目代码修改#

所以我原本写的代码中的 scanf("%s", arr) 应该改成 fgets(arr, sizeof(arr), stdin)。

是否这么写代码我就能通过测试了呢？#

当然不是，事实上代码最终的输出结果是：

1
tneduts a ma I

所以最后的输出还是错误了，多输出了一个换行符 \n。

事实上这里有很多种方法可以去除原来字符串末尾的换行符，但我最终选择了使用 strcspn 函数来处理,所以下面我会介绍 strcspn 函数。

2. `strcspn`函数#

2.1 函数介绍#

strcspn 是 C 语言标准库 string 中的一个函数，用于查找一个字符串中第一次出现指定字符集合中的任何字符的位置。它返回的是第一个匹配字符的索引位置。

1
size_t strcspn(const char *str1, const char *str2);

2.2 参数说明#

str1：要查找的字符串。
str2：一个包含字符集合的字符串，strcspn 会查找这个字符集合中的字符在 str1 中的第一次出现。
strcspn 会从 str1 的起始位置开始查找，直到遇到 str2 中的任何字符，或者到达字符串末尾。它返回第一个匹配字符的索引位置，如果未找到匹配字符，则返回 str1 的长度。

2.3 注意事项#

strcspn 返回的是 size_t 类型，它是无符号整数类型。如果未找到匹配字符，返回值会等于字符串的长度。因此，在使用返回值时，应该注意数据类型和范围。

2.4 使用示例#

1
#include <stdio.h>
2
#include <string.h>
3

4
int main() {
5
    char str[] = "Hello, World!";
6
    char chars[] = " ,"; // 字符集合包含空格和逗号
7

8
    size_t index = strcspn(str, chars);
9

10
    if (index < strlen(str)) {
11
        printf("第一个匹配字符在位置：%zu\n", index);
12
        printf("匹配字符是：%c\n", str[index]);
13
    } else {
14
        printf("未找到匹配字符\n");
15
    }
16

17
    return 0;
18
}

展开收起

3. 最终代码#

1
#include <stdio.h>
2

3
void reverse(char* arr) {
4
    char* left = arr;
5
    char* right = &arr[strlen(arr) - 1];
6
    while(left < right) {
7
        char mid = *left;
8
        *left = *right;
9
        *right = mid;
10
        left++;
11
        right--;
12
    }
13
    for(int i = 0; i < strlen(arr); i++) {
14
        printf("%c", arr[i]);
15
    }
16
}
17

18
int main(void) {
19
    char arr[100000];
20
    fgets(arr, sizeof(arr), stdin);
21
    arr[strcspn(arr, "\n")] = '\0';
22
    reverse(arr);
23
    return 0;
24
}

展开收起

4. 题后反思#

最终的代码运行成功后，我总有一种大材小用的感觉，我就思考能不能用 scanf 函数来实现呢？经过与 ChatGPT 的一番讨论后，我最终找到了另一种更为简单的代码：那就是使用 %[^\n] 来格式化输入。

5. `%[^\n]`#

5.1 介绍与解释#

%[^\n] 是 C 语言中用于格式化输入的格式字符串之一。它用于 scanf 函数中，用于读取一行字符串，直到遇到换行符为止。

让我解释一下 %[^\n] 的含义：

%[：这部分表示开始读取一个自定义字符集。在方括号内放置你想要读取的字符的集合。
^：在方括号内的开头，^ 表示反转字符集。即，%[^\n] 表示读取除换行符外的所有字符。
\n：这是一个转义序列，表示换行符。

所以，%[^\n] 的意思是，读取除换行符之外的所有字符，直到遇到换行符为止，并且不会读取换行符！！！

5.2 再次修改代码#

所以，我们最终可以将代码从 fgets(arr, sizeof(arr), stdin); arr[strcspn(arr, "\n")]; 修改成 scanf("%[^\n]");。

6. 感悟#

通过这到题目，我深刻的感受到了什么叫做“条条大路通罗马”。作为小白的我，还有很多的知识去学习、去探索、去使用。

Better Mistakes

我会用 Git，但它到底在做什么？从对象数据库到现代工作流

先把几个基础概念钉牢#

仓库与工作区不是同一个东西#

暂存区不是待上传清单#

HEAD、branch 与 commit#

tracked、untracked、modified 与 staged#

本地分支、远端跟踪分支与 upstream#

先说结论：Git 保存的是快照，不是补丁#

从零建一个可以解剖的仓库#

第一个 blob：内容如何变成 ID#

git add 不是”添加文件”，而是更新下一张快照#

从 index 写出 tree，再创建 commit#

git diff 到底在比较什么#

先选对两端#

逐行拆一份 unified diff#

diff --git：一个文件级变化开始了#

index：前后 blob 与文件模式#

--- 与 +++：旧文件和新文件标签#

@@：hunk 在两边的坐标#

hunk 正文：看每行第一个字符#

新建、删除、改权限和重命名怎么看#

适合不同阅读阶段的 diff 视图#

branch 和 HEAD 原来如此轻#

detached HEAD 是什么#

为什么现在更推荐 switch 和 restore#

merge、rebase 和 cherry-pick 都在改什么#

Fast-forward：历史没分叉，只移动指针#

merge：保留分叉，增加汇合点#

rebase：复制 commit，换一组 parent#

cherry-pick：复制选定的 commit#

远端不是云端魔法，只是另一个仓库#

fetch：下载对象，更新远端跟踪引用#

pull：先 fetch，再选择一种集成策略#

push：上传缺少的对象，请远端移动 ref#

撤销操作：先问要改哪一层#

常用决策表#

revert 为什么适合公开历史#

reflog：引用移动的本地黑匣子#

Git 为什么不会为每个版本保存一整份大文件#

clone 到底复制了什么#

多任务开发：worktree 比反复 stash 更直接#

一套我现在愿意长期使用的命令行#

初始配置#

每日开始#

制作原子 commit#

同步并复核#

阅读历史#

定位引入 bug 的 commit#

哪些旧习惯该换，哪些只是需要理解#

把 AI 放回正确的位置#

继续拆下去#

一台不存在的计算机：QEMU 工作原理与实践

先把名字拆开#

一条命令其实在描述什么？#

我先启动 512 字节，而不是一个发行版#

从复位向量到 0x7c00#

TCG 到底模拟了什么？#

KVM 为什么快，又为什么仍然需要 QEMU？#

Machine 不是一个无关紧要的名字#

我让 QEMU 自己交出 ARM 硬件图#

固件启动、磁盘启动和直接内核启动#

1. 固件加磁盘#

2. -bios 启动固件或裸机镜像#

3. -kernel 直接内核启动#

-nographic 不等于 -display none#

设备前端与后端必须成对阅读#

raw 与 qcow2 不是”大文件与小文件”#

VirtIO 为什么不是”模拟一块更快的真网卡”？#

网络：先用 user，理解后再上 TAP#

QEMU user mode：只模拟一个进程#

HMP、QMP 和 Guest Agent 是 3 个平面#

HMP：给人使用的 Monitor#

QMP：给程序使用的控制 API#

Guest Agent：进入 Guest OS 的通道#

用 GDB 在第一条指令前拦住机器#

日志、trace 和可重复执行#

时钟、SMP 和”偶尔失败”#

一套可重复的内核实验命令#

常见失败怎样沿层次定位？#

`HEAD`、branch 与 commit#

`git add` 不是”添加文件”，而是更新下一张快照#

`git diff` 到底在比较什么#

`diff --git`：一个文件级变化开始了#

`index`：前后 blob 与文件模式#

`---` 与 `+++`：旧文件和新文件标签#

`@@`：hunk 在两边的坐标#

为什么现在更推荐 `switch` 和 `restore`#

`merge`：保留分叉，增加汇合点#

`rebase`：复制 commit，换一组 parent#

`cherry-pick`：复制选定的 commit#

`fetch`：下载对象，更新远端跟踪引用#

`pull`：先 fetch，再选择一种集成策略#

`push`：上传缺少的对象，请远端移动 ref#

`revert` 为什么适合公开历史#

多任务开发：`worktree` 比反复 stash 更直接#

从复位向量到 `0x7c00`#

2. `-bios` 启动固件或裸机镜像#

3. `-kernel` 直接内核启动#

`-nographic` 不等于 `-display none`#

`No bootable device`#

`Could not access KVM kernel module`#

先做出一个真的 `.ko`#

`make -C ... M=... modules` 为什么像走了两遍？#

`src`、`obj`、`srctree`、`objtree`#

一行 `obj-m` 怎样进入 `scripts/Makefile.build`？#

`.cmd` 才是增量构建的记忆#

`modpost` 不是又一个链接器#

`.ko` 仍然是一个可重定位 ELF#

从 `insmod` 到 `module_init()`#

`Invalid module format`#

`Unknown symbol`#

`Operation not permitted`#

`Required key not available` 或 `Key was rejected by service`#

把 `obj-m` 换成 `obj-y` 会发生什么？#

内建时 `module_init()` 变成 initcall#

一个 `config` 到底定义了什么？#

`n`、`m`、`y` 不是 3 个字符串#

`depends on` 是上限，不是自动开关#

`default` 只在用户没有决定时说话#

`select` 很方便，也很锋利#

`defconfig`、`.config` 到底谁是谁？#

`Kconfig` 是规则库#

`defconfig` 是最小起点#

`.config` 是当前构建的完整用户配置#

`savedefconfig` 做反向压缩#

Linux 中谁消费 `obj-y` 和 `obj-m`？#

直接编辑 `.config` 后不重新求解#

把 `select` 当作递归安装依赖#

只看 `menuconfig` 中是否可见#