EC528 课堂 - 505 错误演示参考卡（打印用）

【演示操作流程】单页版本

┌──────────────────────────────────────────────────────────────┐
│  第一步：制造错误 (2 min)                                     │
│  ─────────────────────────────────────────────────────────── │
│  $ vim _layouts/ec440.html                                   │
│  找到最后一行的 {\% endif \%}                                  │
│  ❌ 改成: {\% comment \%} missing {\% endcomment \%}             │
│  保存: :wq                                                    │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│  第二步：观察错误 (2 min)                                     │
│  ─────────────────────────────────────────────────────────── │
│  $ bundle exec jekyll serve                                  │
│  看到: ❌ Liquid Exception: ... 'endif' expected             │
│  按 Ctrl+C 停止                                              │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│  第三步：诊断问题 (3 min)                                     │
│  ─────────────────────────────────────────────────────────── │
│  $ bundle exec jekyll build --trace                          │
│  查看输出中的三个关键信息：                                   │
│    1️⃣  错误类型: Liquid Exception                            │
│    2️⃣  文件位置: _layouts/ec440.html, line 42               │
│    3️⃣  问题描述: Expected 'endif'                           │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│  第四步：查看代码上下文 (2 min)                               │
│  ─────────────────────────────────────────────────────────── │
│  $ sed -n '38,45p' _layouts/ec440.html                       │
│  输出:                                                        │
│    38  {\% if page.toc \%}                                     │
│    39    <div>                                               │
│    40      ...                                               │
│    41    </div>                                              │
│    42  {\% comment \%} ERROR HERE {\% endcomment \%} ❌          │
│    43                                                         │
│    44  <footer>                                              │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│  第五步：修复错误 (2 min)                                     │
│  ─────────────────────────────────────────────────────────── │
│  $ vim _layouts/ec440.html                                   │
│  改回: {\% endif \%}                                           │
│  保存: :wq                                                    │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│  第六步：验证修复 (2 min)                                     │
│  ─────────────────────────────────────────────────────────── │
│  $ bundle exec jekyll build                                  │
│  看到: ✅ ... done in 2.345 seconds                          │
│  没有错误 = 成功！                                            │
│  访问 http://localhost:4000 确认网站正常                    │
└──────────────────────────────────────────────────────────────┘

【日志分析秘诀】关键词检查法

寻找这些… 意思 怎么做
Liquid Exception 模板出错 检查 Liquid 标签
line XXX 在哪一行 打开文件 +XXX
in 'xxx.html' 在哪个文件 vim xxx.html
YAML error 配置错误 检查缩进
Gem::LoadError 依赖错误 bundle install
Traceback 完整错误链 从下往上读

黄金法则：

【常见 Jekyll 错误】速查表

❌ Liquid Exception: Syntax Error [in ‘…’ line X]

原因: Liquid 模板标签未闭合或拼写错误
检查:  ✓ {\% if \%} 对应 {\% endif \%} 吗?
      ✓ {\% for \%} 对应 {\% endfor \%} 吗?
      ✓ 过滤器名称对吗?
修复: vim [文件] +[行号]

❌ YAML syntax error in _config.yml

原因: YAML 格式错误（缺引号、缩进、特殊字符）
检查: ✓ 引号成对了吗? ("..."  或 '...')
     ✓ 缩进统一了吗? (都用 2 个空格)
     ✓ 有特殊字符吗? (冒号、#...需要加引号)
修复: vim _config.yml

❌ Gem::LoadError / bundler: command not found

原因: 缺少或冲突的 Ruby 包
检查: ✓ bundle check
     ✓ bundle install
修复: bundle install && bundle update

❌ Errno::ENOENT: No such file or directory

原因: 配置中的路径不存在
检查: ✓ ls -la [路径]
     ✓ _config.yml 中什么路径出错了?
修复: 修改配置或创建目录

【快速命令速查】

# 安全地尝试构建（显示所有错误）
bundle exec jekyll build --trace 2>&1 | head -50

# 启动本地服务（用于测试）
bundle exec jekyll serve --force-polling

# 清理并重新构建（解决诡异问题）
bundle exec jekyll clean && bundle exec jekyll build --trace

# 只看错误信息
bundle exec jekyll build 2>&1 | grep -E "Error|Exception"

# 验证 YAML 文件
ruby -ryaml -e 'YAML.load_file("_config.yml")' && echo "✅ OK"

# 看某个文件的特定行
sed -n '38,45p' _layouts/ec440.html

# 查看最近的改动
git diff HEAD~1 _layouts/ec440.html

# 恢复文件到上一个版本
git checkout _layouts/ec440.html

【学生自检清单】遇到错误时

【讲师笔记】演示时间表

时间 活动 注意
0:00-1:00 问题启发 “遇到 500 怎么办?”
1:00-4:00 制造错误 让学生看着
4:00-6:00 启动服务看错误 指出 Exception 关键词
6:00-9:00 –trace 诊断 讲解三个关键信息
9:00-11:00 查看代码 定位问题行
11:00-14:00 修复并验证 让学生看到修复过程
14:00-18:00 讨论和Q&A 思考题

总时长: 18 分钟 (可调整)

【思考题】课堂讨论用

  1. 如果这个错误在生产环境，用户会看到什么?
  2. 日志中最有用的一条信息是?
  3. 怎样才能预防这个错误?
  4. CI/CD 怎么帮助我们提早发现这个问题?
  5. 如果有 10 000 个访问者同时遇到这个错误?

【黄金法则】

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃  永远首先查看日志，日志里有所有答案！   ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

诊断错误的 4 步:
  1️⃣  获取完整日志信息
  2️⃣  定位文件和行号
  3️⃣  查看代码上下文
  4️⃣  对比之前的版本

修复问题的 3 步:
  1️⃣  理解问题原因
  2️⃣  做出改动
  3️⃣  验证修复有效
⏰ 打印这页贴在办公室！ 💾 保存 DEBUGGING-CHEATSHEET.md 供以后参考