# 常见错误与排错

## 错误分类

| 症状 | 先检查 | 不要直接做 |
| --- | --- | --- |
| `NotCapable` / requires access | 报错中的资源和权限种类 | 加 `-A` |
| Module not found | specifier、imports、workspace、实际配置 | 删除 lockfile |
| npm 包找不到文件 | node_modules 模式、包 exports、安装脚本 | 改内部包路径 |
| 类型错误但能运行 | `deno check` 的模块图与 types | 忽略 CI |
| CI 可以、本地失败 | Deno 版本、OS/arch、缓存、环境 | 清空所有全局缓存 |
| 本地可以、部署失败 | 请求运行时、权限、只读文件系统、变量 | 假定平台等同本机 |

## 权限错误

```text
error: Requires env access to "API_KEY"
```

先确认代码是否真的需要该变量，再用 `--allow-env=API_KEY`。若变量名来自用户输入，避免宽泛授权整个环境。

## 模块错误

```bash
deno info main.ts
deno install --reload --entrypoint main.ts
```

`deno cache` 在当前 CLI 已弃用，使用 `deno install --entrypoint`。`--reload` 会访问网络并改变本地缓存状态，只在确认需要重新解析后使用；不要在 CI 失败时无条件删除 `deno.lock`。

## 可复现报告

```text
Deno: <deno --version output>
Platform: <os/arch>
Command: <exact command, secrets removed>
Expected: <observable behavior>
Actual: <exit code + first relevant error>
Config: <effective deno.json path>
Minimal reproduction: <path or repository>
```

需要确认是否为运行时缺陷时，查询 [denoland/deno issues](https://github.com/denoland/deno/issues) 并匹配当前版本。