附录
排错索引
把报错里的关键词在本页搜索（Ctrl + F 或 Command + F），找到原因和解决办法。查不到时，把完整报错（删掉其中的 Key 和密码）交给 AI 分析。
终端与安装
| 看到的报错 | 原因 | 解决 | 课 |
|---|
无法将“xxx”项识别为 cmdlet… / command not found | 程序没装好，或者终端还没刷新 PATH | 先重开终端；再按第 4 课排查 PATH | 4 |
因为在此系统上禁止运行脚本 | PowerShell 默认不允许运行脚本，npm 是脚本 | Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned | 5 |
EACCES: permission denied（npm） | macOS 上 npm 想写入系统目录 | 把 npm 全局目录改到家目录，不要用 sudo | 5 |
The token '&&' is not a valid statement separator | Windows PowerShell 5.1 不支持 &&，这条命令是写给 CMD 或其他 Shell 的 | 换用页面上给 PowerShell 的那条命令 | 4 |
curl 报参数错误（Windows） | PowerShell 里的 curl 是别的命令的别名 | 写成 curl.exe | 10 |
下载卡住、timed out、无法连接 | 网络访问不到下载地址 | 换用 npm 加国内镜像 | 5 |
| 中文显示成乱码 | 文件编码和打开它的程序不一致 | 用记事本确认内容；让 AI 检查编码设置 | 3、11 |
API 与 AI 助手
| 看到的报错 | 原因 | 解决 | 课 |
|---|
401 / Unauthorized | Key 不对、复制不完整或已失效 | 重新复制 Key，注意空格和引号 | 6 |
429 / 额度不足 | 余额用完或请求太频繁 | 到账户后台查看 | 6 |
404（调用 API 时） | 地址写错，常见是多写了 /v1 | Base URL 用 https://api.zairouter.com | 13 |
提示没有设置 XAI_API_KEY | 当前终端里没有这个环境变量 | 检查长度；setx 或改 .zshrc 后要重开终端 | 6 |
| Codex 要求登录 ChatGPT | 配置文件没生效 | 用 cat 检查 ~/.codex/config.toml 的内容和位置 | 6 |
| Claude Code 要求登录 Claude 账号 | 没有读到 ANTHROPIC_AUTH_TOKEN | 重开终端，检查变量长度 | A |
Claude Code 底部显示 auto mode on | 默认权限模式没改成手动 | 检查 ~/.claude/settings.json | A |
grok models 报 401 | 配置文件里的 Key 为空 | 确认 XAI_API_KEY 已设置，重新生成配置 | B |
| AI 一直退回规则版 | 页面上的说明会写明原因 | 按说明检查 Key、网络或每日上限 | 13、22 |
Git
| 看到的报错 | 原因 | 解决 | 课 |
|---|
Please tell me who you are | 没设置名字和邮箱 | git config --global user.name/user.email | 8 |
LF will be replaced by CRLF | Windows 和 macOS 换行符不同 | 只是提示，可以忽略 | 8 |
| 困在一个看不懂的编辑器里 | 忘了写 -m，Git 打开了 Vim | 按 Esc，输入 :q! 回车 | 8、17 |
屏幕底部出现 : 或 (END) | 输出太长，进入了翻页模式 | 按 q 退出 | 8 |
本地运行
| 看到的报错 | 原因 | 解决 | 课 |
|---|
EADDRINUSE / address already in use | 端口被占用 | 关掉另一个还在运行的服务器，或者换端口 | 11 |
| 改了代码网页没变化 | 服务器还在运行旧代码 | Ctrl + C 停止，重新 npm start | 12 |
| 点按钮没反应 | 网页脚本出错 | F12 打开控制台看红色报错，交给 AI | 12 |
SSH 与服务器
| 看到的报错 | 原因 | 解决 | 课 |
|---|
Connection timed out | IP 不对、服务器没开或防火墙没开 22 | 检查控制台 | 15 |
Permission denied (publickey) | 密钥没装好或用户名不对 | 用控制台网页终端检查 authorized_keys | 15 |
REMOTE HOST IDENTIFICATION HAS CHANGED | 服务器指纹变了 | 刚重装过就 ssh-keygen -R IP；否则先确认 IP | 15 |
| 输入密码时屏幕没反应 | 密码输入本来就不显示 | 输完直接回车 | 15 |
E45: 'readonly' option is set（Vim） | 没有权限修改这个文件 | :q! 退出，用 sudo vim 重新打开 | 17 |
| 按键后屏幕出现奇怪字符（Vim） | 在普通模式里打字了 | Esc、u 撤销，按 i 再输入 | 17 |
Docker
| 看到的报错 | 原因 | 解决 | 课 |
|---|
permission denied ... Docker daemon socket | 没加入 docker 组或没重新登录 | sudo usermod -aG docker $USER 后退出重登 | 18 |
COPY failed | 文件名不对或在错误的文件夹里构建 | 在 ~/weekly-report 里运行 docker build | 19 |
| AI 退回规则版，提示 401（容器里） | .env 里有多余空格，或者 docker run --env-file 时值加了引号 | 等号两边不留空格，值不加引号 | 17、19 |
denied: requested access to the resource is denied | 镜像名里的用户名不对或没登录 | docker login，检查镜像名 | 20 |
pull access denied | 镜像名写错或仓库私有 | 和 Docker Hub 上的名字对照 | 21 |
yaml: line X | YAML 缩进不对 | 用空格不用 Tab，同级对齐 | 21 |
状态一直是 Restarting | 程序启动就出错 | docker compose logs app 看报错 | 21 |
改了 .env 没生效 | 容器创建时才读取 .env | docker compose up -d --force-recreate | 22 |
| 网站还是旧版本 | compose.yaml 没改版本号或浏览器缓存 | 检查 docker compose ps 的镜像，强制刷新 | 25 |
Cloudflare 与上线
| 看到的报错 | 原因 | 解决 | 课 |
|---|
| 域名一直是 Pending | NS 还没生效 | 检查注册商处的 NS，耐心等待 | 23 |
| 521 Web server is down | Caddy 没运行 | docker compose ps、logs caddy | 24 |
| 522 Connection timed out | 防火墙没开 80/443 | 在控制台添加规则 | 24 |
| 525 SSL handshake failed | 域名或证书配置不对 | 检查 Caddyfile 的域名和证书文件 | 24 |
| 526 Invalid SSL certificate | Cloudflare 校验源站证书失败 | 检查证书有效期、域名和 Caddy 加载的文件，必要时重新申请源站证书 | 24 |
| 重定向次数过多 | SSL 模式是 Flexible | 改为 Full (strict) | 24 |
| 502 Bad Gateway（使用隧道时） | 隧道找不到周报助手 | Public Hostname 的 URL 填 app:3000 | E2 |