名称: midnight-tooling:midnight-debugging 描述: 当遇到Midnight错误时使用，例如“compact: command not found”、“ERR_UNSUPPORTED_DIR_IMPORT”、版本不匹配、证明服务器故障、“@midnight-ntwrk”包错误或编译失败。

Midnight环境调试

用于识别和解决常见Midnight开发工具链问题的专家知识。

诊断方法

遇到Midnight相关错误时，请遵循以下系统方法：

识别错误类别（见下方错误类别）
检查缓存新鲜度 - 如果需要版本信息，请运行/midnight:sync-releases
运行诊断 - 使用/midnight:doctor进行全面检查
应用针对性修复 - 使用本技能中的解决方案
验证修复 - 运行/midnight:check进行确认

进行全面诊断：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/doctor.py

错误类别

1. PATH和安装错误

症状：compact: command not found

诊断：

# 检查compact是否存在于某处
ls -la ~/.compact/bin/compact 2>/dev/null || echo "不在默认位置"

# 检查PATH
echo $PATH | tr ':' '
' | grep -i compact

解决方案：

原因	修复方法
未安装	运行Compact安装程序（见midnight-setup技能）
不在PATH中	将`export PATH="$HOME/.compact/bin:$PATH"`添加到shell配置文件
错误的shell配置文件	编辑`~/.zshrc`（macOS）或`~/.bashrc`（Linux）
配置文件未加载	打开新终端窗口

2. 版本不匹配错误

症状：

提及版本不兼容的运行时错误
更新一个组件后构建失败
pragma language_version不匹配

诊断：

# 检查当前版本
compact compile --version
npm list @midnight-ntwrk/compact-runtime
npm list @midnight-ntwrk/ledger

关键规则：所有Midnight组件必须根据支持矩阵使用兼容版本。

解决方案：

检查兼容性矩阵，查看缓存的发行说明或运行/midnight:versions

在package.json中使用精确版本（不使用^或~）：

{
  "dependencies": {
    "@midnight-ntwrk/compact-runtime": "0.9.0",
    "@midnight-ntwrk/ledger": "4.0.0"
  }
}

版本更改后执行干净安装：

rm -rf node_modules package-lock.json
npm ci

编译器更新后重新编译合约：

rm -rf contract/*.cjs contract/*.prover contract/*.verifier
compact compile src/contract.compact contract/

详细版本故障排除请参阅references/version-mismatch-guide.md。

3. Node.js导入错误

症状：ERR_UNSUPPORTED_DIR_IMPORT

原因：

Node版本切换后终端环境过时
缓存的模块引用
错误的Node.js版本处于活动状态

解决方案：

打开新的终端窗口（不仅仅是加载配置文件）
清除模块缓存：
```
rm -rf node_modules/.cache
```

验证正确的Node版本：

node --version  # 应为18+
nvm use 18      # 如果使用nvm

重新安装node_modules：
```
rm -rf node_modules
npm install
```

4. 证明服务器问题

症状：

端口6300连接被拒绝
钱包无法生成证明
“证明服务器无响应”

诊断：

# 检查是否正在运行
docker ps | grep proof-server

# 检查端口是否可用
lsof -i :6300

# 检查Docker是否正在运行
docker info

解决方案：

问题	修复方法
未运行	`docker run -p 6300:6300 midnightnetwork/proof-server -- midnight-proof-server --network testnet`
端口被占用	停止其他进程：`kill $(lsof -t -i:6300)`或使用不同端口
Docker未运行	启动Docker Desktop
镜像未拉取	`docker pull midnightnetwork/proof-server:latest`
错误的网络	确保`--network testnet`与您的目标匹配

5. 编译错误

症状：

合约编译失败
Compact代码中的类型错误
电路生成错误

诊断：

# 检查编译器版本是否与pragma匹配
compact compile --version

# 在合约文件中检查pragma：
# pragma language_version 0.18;

常见问题：

错误	原因	修复方法
Pragma不匹配	合约声明了不同的版本	更新pragma或切换编译器版本
类型错误	语言特性已更改	检查发行说明中的破坏性更改
电路太大	复杂计算	简化逻辑或拆分为多个交易

6. 包安装错误

症状：

npm install对于@midnight-ntwrk包失败
对等依赖冲突
注册表错误

解决方案：

检查npm注册表访问：

npm view @midnight-ntwrk/compact-runtime

清除npm缓存：
```
npm cache clean --force
```
使用精确版本以避免对等冲突
不要混合锁文件 - 仅使用package-lock.json（npm）或bun.lock（Bun）

快速诊断命令

检查	命令
所有工具版本	`/midnight:check`
全面诊断	`/midnight:doctor`
当前与最新版本	`/midnight:versions`
组件变更日志	`/midnight:changelog compact`

错误消息参考

有关错误消息及其解决方案的完整目录，请参阅references/common-errors.md。

何时寻求额外帮助

如果标准故障排除无法解决问题：

查看Midnight常见问题解答
查看获取帮助部分
加入Midnight开发者社区频道