常见错误与排错
按权限、模块、类型、Node 兼容和平台边界定位 Deno 错误
错误分类
| 症状 | 先检查 | 不要直接做 |
|---|---|---|
NotCapable / requires access | 报错中的资源和权限种类 | 加 -A |
| Module not found | specifier、imports、workspace、实际配置 | 删除 lockfile |
| npm 包找不到文件 | node_modules 模式、包 exports、安装脚本 | 改内部包路径 |
| 类型错误但能运行 | deno check 的模块图与 types | 忽略 CI |
| CI 可以、本地失败 | Deno 版本、OS/arch、缓存、环境 | 清空所有全局缓存 |
| 本地可以、部署失败 | 请求运行时、权限、只读文件系统、变量 | 假定平台等同本机 |
权限错误
error: Requires env access to "API_KEY"
先确认代码是否真的需要该变量，再用 --allow-env=API_KEY。若变量名来自用户输入，避免宽泛授权整个环境。
模块错误
deno info main.ts
deno install --reload --entrypoint main.ts
deno cache 在当前 CLI 已弃用，使用 deno install --entrypoint。--reload 会访问网络并改变本地缓存状态，只在确认需要重新解析后使用；不要在 CI 失败时无条件删除 deno.lock。
可复现报告
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 并匹配当前版本。