课前准备:机器、工具、账号
本合集目录
本章目录
单册说明:本文件是卷 0 的第 4 章,可独立阅读。前置:第 3 章(请求旅程图)。本章把环境一次装到位,后面四卷不再为"装不上"停摆。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 0 · 起点与路线(第 4 / 5 章) |
| 前置章节 | 0.3 全景地图 |
| 本章产出 | 四个工具装好 · 六个账号就绪 · 一个固定实验目录 |
| 对应代码 | code/check_env.py(一条命令验 14 项,见 0.4.6) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 终端里 python --version、node -v、git --version 三条命令都能出结果 |
0.4.1 一句话结论:环境要"装一次、别再管"
新手最常见的浪费不是看不懂代码,而是每次开始都被环境打断:今天 Python 装不上,明天 npm 报错,后天 SSH 连不上。所以本章的原则是:
一次装齐,全部验证,写成一个可复制的清单。
装完这一步,后面四个月你都不需要再碰安装流程。
0.4.2 硬件与系统:够用就行
| 项 | 最低 | 推荐 | 说明 |
|---|---|---|---|
| 内存 | 8 GB | 16 GB | 同时开浏览器(几十个标签)、编辑器、终端时,8G 会开始换页 |
| 硬盘 | 20 GB 可用 | 60 GB 可用 | Node 与 Python 的依赖目录很能长 |
| CPU | 双核 | 四核 | 影响构建速度,不影响能不能学 |
| 系统 | Windows 10 / macOS 12 / 主流 Linux | 同上 | 三系统本教程都覆盖 |
⚠️ 不要用平板或用不了的旧电脑硬撑。 装不上 Node 的机器会让你在第一周就放弃,这个损失比换机器大。
0.4.3 四个必装工具
① Git:版本控制
| 系统 | 装法 | 验证 |
|---|---|---|
| Windows | 官网下载 Git for Windows(自带 Git Bash,后面所有命令都在它里面跑) | git --version |
| macOS | xcode-select --install 或官网安装包 |
同上 |
| Linux | sudo apt install git(Debian/Ubuntu) |
同上 |
装完立刻配身份,只做一次:
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
⚠️ 邮箱建议和后面注册 GitHub 用同一个,否则提交记录在 GitHub 上不会归到你名下。
② VS Code:编辑器
官网下载即可。装完做一件事:打开"文件夹",而不是打开单个文件(卷 1 第 3 章会解释为什么这条决定了你后面半年是否顺)。
推荐装两个扩展,别多装:中文语言包(可选)、Python。
③ Node.js:跑前端工具链
去官网下 LTS 版本(长期支持版),不要装 Current。装完验证:
node -v
npm -v
⚠️ Windows 上如果 node 提示"不是内部或外部命令",是安装时没勾选加入 PATH。重装并勾选,不要去改环境变量猜。
④ Python:写后端
| 系统 | 装法 | 验证 |
|---|---|---|
| Windows | 官网安装包,务必勾选 Add Python to PATH | python --version |
| macOS | brew install python 或官网包 |
python3 --version |
| Linux | 通常自带;缺则 sudo apt install python3 python3-venv |
同上 |
⚠️ Windows 上可能同时存在 python 和 py 两个入口;macOS/Linux 上是 python3。这不是错,是历史遗留,卷 5 会讲怎么在项目里隔离。
0.4.4 六个账号(按需要注册,不必一次全齐)
| 账号 | 用来做什么 | 什么时候需要 | 备注 |
|---|---|---|---|
| GitHub | 存代码、远程仓库 | 卷 3 | 免费版够用;别用公司邮箱注册后再想迁 |
| 云服务器厂商 | 租一台服务器 | 卷 1 第 5 章 | 学生机/轻量应用服务器即可,1 核 2G 起步;选 Ubuntu |
| 域名注册商 | 买域名 | 卷 7 第 5 章 | 中国大陆服务器需备案,流程预留时间 |
| 大模型 API(可选) | 文本分析能力 | 卷 8 | 不用它也能学完全书,用假数据替代即可 |
| 代码托管备用(可选) | 国内访问更稳 | 视网络 | 与 GitHub 二选一即可 |
| 密码管理器(强烈建议) | 存密钥、令牌 | 立刻 | 你会产生十几个密钥,靠脑子记必然丢 |
网络环境的现实问题
如果你在国内网络下遇到 npm install 或 pip install 极慢、超时,这属于网络问题而不是安装失败。判断方法:报错里出现 ETIMEDOUT、ECONNRESET、read timeout 这类词,就是网络。
处理原则(按顺序试,别一上来就换源):
- 先重试一次——很多超时是瞬时抖动;
- 仍然超时,再按官方文档配置镜像源;
- 公司/学校网络有代理时,注意 npm、pip、git 三者要分别配置代理,配一个不会全局生效。
⚠️ 不要为了装包去下载来路不明的"一键安装包"。安装包是恶意软件的重灾区,而官方安装包本来就不难装。
0.4.5 目录约定:给实验一个固定家
这是本章最重要的习惯,比装任何工具都值钱:
~/code/ ← 所有项目放这里,路径里不要有中文和空格
└─ dudao/ ← 本书的主线项目
├─ frontend/
├─ backend/
└─ notes/ ← 你的实验记录
~/.ssh/ ← 密钥放这里(工具默认位置,别乱动)
| 规则 | 为什么 |
|---|---|
| 路径不要用中文、不要有空格 | 大量工具链对空格和中文路径处理不好,报错信息还看不出原因 |
| 一个项目一个文件夹 | 避免"到底哪个是最后版本" |
笔记单独放 notes/ |
三个月后你会感谢自己记过命令 |
Windows 用户注意:C:\Users\你的名字\... 如果用户名是中文,很多构建工具会出问题。稳妥做法是把项目放在 C:\code\ 这类纯英文路径下。
0.4.6 装完就验证:一条命令过十四项
不必手工逐条试。卷 0 随书带了一个自检脚本(code/check_env.py,同样只用标准库):
py code/check_env.py # Windows
python3 code/check_env.py # macOS / Linux
# 网络受限时跳过联网检查
py code/check_env.py --no-network
输出长这样(真实运行结果):
[通过] Python 版本 3.13.14 · Windows AMD64
[通过] Git(git) git version 2.55.0.windows.3
[通过] Node.js(node) v22.22.2
[通过] npm(npm) 11.13.0
[通过] SSH 客户端(ssh) OpenSSH_10.3p1
[通过] Git 身份 TYH <[email protected]>
[警告] 实验目录 E:\项目\code(路径含中文)
→ 把项目移到 C:\code\ 这类纯英文无空格路径
[通过] 端口 8000 空闲,可直接起本地服务
[警告] 大模型密钥 未设置 AI_API_KEY
→ 卷 0 不需要;卷 8 用到时再配,现在留空不影响学习
[通过] DNS 解析 example.com → 104.20.23.154
[通过] TCP 连通 443 端口可建立连接
--------------------------------------------
合计 14 项:通过 11 · 警告 3 · 失败 0
结论:可以开始卷 1。警告项不阻断,按需处理。
怎么读这份结果:
| 结果 | 含义 | 该做什么 |
|---|---|---|
[失败] |
阻断项,后面必然卡住 | 按 → 提示修掉,重跑 |
[警告] |
不阻断,但会留隐患 | 卷 1 之前顺手处理掉,尤其"路径含中文" |
未设置 AI_API_KEY |
正常 | 卷 8 才需要,现在留空 |
脚本退出码:全通过为 0,有失败项为 1——所以你以后可以把它塞进任何自动化流程里当门禁。
如果你更喜欢手工确认,这五条等价:
git --version
node -v
npm -v
python --version || python3 --version
ssh -V
| 输出 | 说明 |
|---|---|
| 有版本号 | 通过 |
command not found / 不是内部或外部命令 |
没装或没进 PATH,回上面对应小节 |
| 版本号很低(如 Node 12) | 太旧,卸载重装 LTS |
本章验收
-
py code/check_env.py跑到「失败 0」(或失败项已逐条修完并重跑通过) - 四条命令(git / node / npm / python)都能输出合理版本号
- Git 已配置
user.name与user.email,且邮箱与 GitHub 一致 - VS Code 已装好,能"打开文件夹"并看到左侧文件树
- 已在
~/code/下建好纯英文路径的实验目录 - 至少注册了 GitHub 账号,并记进密码管理器
自测
Q1:为什么要求项目路径不能有中文和空格?
看答案
很多命令行工具、构建器、Python 包在拼接路径时不做转义,遇到空格会把一个路径拆成两段,遇到中文可能出现编码不一致。报错通常表现为"文件不存在"或莫名其妙的语法错误,看起来像代码问题,实际是路径问题,排查成本极高。既然换个路径就能规避,就不必去挑战它。Q2:node -v 报"不是内部或外部命令",最快的修法是什么?
看答案
确认是否真的装了(去官网看安装包是否装完),然后重装并勾选"Add to PATH"。不建议手工去系统设置里拼 PATH 字符串——那是新手把环境搞坏的第一大原因,而且报错更隐蔽。Q3:为什么说"网络超时"不是"安装失败"?这个区分有什么实际价值?
看答案
因为两者的修法完全不同:安装失败要换版本、装编译依赖;网络超时要重试、换源、配代理。很多人把 ETIMEDOUT 当成"这个包不能装",于是去下载替代品或改代码,问题反而扩大。看报错里的关键词(timeout / reset)就能一次分清。下一步
环境装好了,最后一章做 12 项自检,并据此决定你从哪一卷进、哪几章可以跳过。