跳转到内容
AI 编程入门手册

报错排查指令：先分类，再让 agent 做一个动作

这页适合安装失败、启动失败、构建失败、命令找不到、权限被拒绝等情况。

先别做什么

Section titled “先别做什么”
  • 不要直接复制 AI 给的一长串命令。
  • 不要删除 node_modules、锁文件、配置文件，除非你知道影响。
  • 不要把 API Key、Token、cookie、私人仓库地址贴出去。
  • 不要在重要项目里试不明脚本。

可复制提示词

Section titled “可复制提示词”
下面是我的报错。请不要直接让我复制一堆命令。


请先判断：
1. 报错属于环境、依赖、权限、网络、代码还是账号问题
2. 最可能的 3 个原因
3. 每个原因如何用低风险方式确认
4. 哪些命令只是查看信息
5. 哪些命令会修改系统或项目
6. 我下一步只应该做哪一个动作


我的系统：{Windows/macOS/Linux}
我使用的工具：{Codex / Claude Code}
我运行的命令：{粘贴命令}


报错内容：
{粘贴报错，删除 Token、API Key、cookie、私人路径和账号信息}

成功标志

Section titled “成功标志”
  • AI 先给出报错类型，而不是直接给命令。
  • 下一步只有一个动作。
  • 命令被标清楚：只读、会写文件、会联网、会改全局环境。
  • 你知道失败后怎么恢复。

真实报错样板：PowerShell 阻止脚本

Section titled “真实报错样板：PowerShell 阻止脚本”

新手在 Windows 上经常看到类似报错：

npm.ps1 cannot be loaded because running scripts is disabled on this system.

不要直接让 AI 给一串“修复命令”。先这样问：

下面是我的报错。请不要直接让我复制命令。


系统：Windows
工具：Codex 或 Claude Code
我运行的命令：npm run dev


报错内容：
npm.ps1 cannot be loaded because running scripts is disabled on this system.


请先输出：
1. 这是环境、依赖、权限、网络、代码还是账号问题
2. 为什么它不像代码 bug
3. 下一步只做一个低风险确认动作
4. 哪些修复动作会改变系统设置
5. 如果我不想改系统设置，有没有临时绕过方式

一个合格回答应该先判断这是 PowerShell 执行策略问题，属于环境或权限类问题；它应该提醒你区分“查看当前策略”和“修改策略”。它不应该一上来就要求你全局放开脚本策略。

看到下面这种回答就停：

请依次运行以下 8 条命令，然后删除 node_modules，重新安装依赖，再重启电脑。

原因：它没有分类，没有解释风险，还把多个修复动作混在一起。新手照做以后，最容易不知道是哪一步造成新问题。

真实报错样板：命令找不到

Section titled “真实报错样板：命令找不到”

如果报错是：

'npm' is not recognized as an internal or external command

重点不是让 AI 立刻重装 Node，而是先确认 3 件事：

  1. 这个终端能不能找到 Node。
  2. Node 是否已安装但 PATH 没生效。
  3. 当前打开的是不是安装前就已经存在的旧终端窗口。

给 agent 的下一句：

请只给我一个只读确认动作，用来判断是没有安装 Node，还是 PATH 没生效。不要让我删除文件、重装依赖或修改系统设置。

常见错误

Section titled “常见错误”
  • 只贴最后一行报错，缺少上文。
  • 不说明系统和工具。
  • 把密钥、cookie、私人路径一起贴出。
  • 同时尝试很多修复，最后不知道哪个动作造成新问题。

下一步

Section titled “下一步”

如果是 npm 或 node 找不到，看 npm 命令找不到。如果是 PowerShell 阻止脚本，看 PowerShell 执行策略。

来源与日期

Section titled “来源与日期”