100 个 C++ 语言典型错误

The 100 Mistakes of C++ — and How to Avoid Them

📖 在线阅读：https://walterfan.github.io/cpp-100-mistakes/

借鉴 100 Go Mistakes and How to Avoid Them 的组织形式，为中文 C++ 开发者整理的一份「错误目录」。全书把典型错误归纳为 13 章，逐条给出错误示例 → 为什么错 → 正确做法，并标注所依赖的 C++ 标准版本与（可选的）ISO C++ Core Guidelines 条目。实际收录 100+ 条（约 105 条），编号 #1–#105 全局连续。

---

目录结构

章	主题	编号区间
1	代码与项目组织	#1–#6
2	基本类型与转换	#7–#15
3	内存管理与 RAII	#16–#25
4	资源与所有权	#26–#36
5	移动语义与值类别	#37–#45
6	类、对象与继承	#46–#55
7	模板与泛型	#56–#64
8	标准库容器与算法	#65–#74
9	并发	#75–#85
10	错误处理	#86–#93
11	标准库与 API 使用	#94–#98
12	性能与优化	#99–#102
13	系统编程与 Linux I/O（平台相关）	#103–#105

书稿源文件位于 source/cpp-100-mistakes/。

---

本地构建

本书使用 Sphinx + MyST-Parser， 依赖通过 Poetry 管理。Python 虚拟环境位于项目根目录的 ./.venv。

一次性环境准备

# 安装 Poetry（如未安装）
pipx install poetry

# 安装本书的构建依赖到 ./.venv
make install

常用命令

命令	作用
make html	生成 HTML 到 build/html/
make serve	在 http://127.0.0.1:7800/ 静态托管 build/html/
make livehtml	实时预览，文件改动自动重建
make pdf	生成 PDF（需要 xelatex + xeCJK）
make clean	清空 build/ 输出
make lint	运行链接检查（sphinx linkcheck）
make check	lint + html，CI 入口
make publish	构建并强制推送 build/html/ 到 gh-pages 分支
make publish-status	打印 GitHub Pages 配置和已部署站点的 URL
make help	列出所有可用 target

所有命令默认都通过 poetry run 包装，也支持先 poetry shell 进入虚拟环境后直接运行。

---

发布到 GitHub Pages

发布走 gh-pages 分支 模式：

1. 在 GitHub 仓库 Settings → Pages 把 Source 设为 Deploy from a branch，Branch 选 gh-pages / (root)（首次发布前完成此步）。

2. 本地运行：

   make publish

   该 target 会先 make html，然后把 build/html/ 强制推送到远端的 gh-pages 分支，并自动添加 .nojekyll，确保以下划线开头的资源 （如 _static/）能被正确服务。

3. 几十秒后访问 https://walterfan.github.io/cpp-100-mistakes/。

CI（.github/workflows/publish.yml）只做构建验证，不做部署 —— 每次推送 master 或提 PR 时跑一次 make install && make html，并把 build/html/ 上传为工作流 artefact。

---

项目结构

cpp-100-mistakes/
├── source/                        # Sphinx 源 (MyST Markdown)
│   ├── conf.py                    # Sphinx 配置
│   ├── index.md                   # 目录入口
│   ├── _static/                   # 静态资源
│   └── cpp-100-mistakes/          # 书稿正文
│       ├── README.md              # 前言与完整目录
│       └── ch01-*.md ... ch13-*.md
├── build/                         # 构建产物（git ignored）
├── pyproject.toml                 # Poetry 元数据 + 依赖
├── poetry.lock                    # 依赖锁
├── poetry.toml                    # 虚拟环境配置（in-project）
├── Makefile                       # 构建 / 预览 / 发布入口
└── .github/workflows/publish.yml  # CI 验证（无部署）

---

许可

本书内容（含正文、代码示例、插图等）采用 Creative Commons BY-NC-SA 4.0 许可发布： 署名 — 非商业性使用 — 相同方式共享。

Copyright © 2026 Walter Fan