qoder依赖安装失败的根本原因是jdk、maven、python或系统库版本不匹配，须统一使用temurin jdk 21 lts、python 3.8–3.10、openssl≥3.0.0，并清理maven本地仓库及代理锁文件。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Qoder依赖安装失败时，会出现mvn命令报错、qoder-cli doctor检测出红色ERROR、OneCode-RAD项目构建中断或CLI初始化静默退出等现象，根本原因在于JDK、Maven、Python或系统库版本与Qoder的硬性约束不匹配，而非单纯网络问题。
验证并锁定JDK 21 LTS运行时
Qoder当前全链路验证通过的唯一Java运行时是Temurin JDK 21 LTS，OpenJDK 17/21或Zulu 21均未覆盖全部注解处理器场景，会导致编译期ABI不兼容。
第一步：访问https://www.php.cn/link/e387385ebe0dbeefed3e8e9f3968aaba下载Temurin JDK 21 LTS安装包，【禁止使用Adoptium OpenJDK 17或Zulu 21】。
第二步：安装完成后，在终端执行java -XshowSettings:properties -version 2>&1 | grep "java.vendor"，输出必须含Eclipse Foundation字样，否则说明未生效。
第三步：执行java -version确认输出含"21.0."（如21.0.9），若仍显示旧版本，请检查PATH中java路径优先级，或使用sdk use java 21.0.9-tem强制切换。
重置Maven本地仓库并清理缓存
Maven本地仓库（~/.m2/repository）中残留的快照版本或损坏元数据会干扰依赖树解析，导致dependency resolution失败且错误提示模糊。
方法一：手动清空并重建
执行mv ~/.m2/repository ~/.m2/repository.bak备份原仓库→mkdir -p ~/.m2/repository创建空白目录→运行mvn clean dependency:purge-local-repository -DreResolve=false触发强制重拉。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
方法二：跳过缓存直接安装
在Qoder项目根目录下执行mvn -s settings.xml -Dmaven.repo.local=~/.m2/repository -DskipTests -Dmaven.test.skip=true -Pqoder-full install，该命令绕过本地缓存，强制从远程仓库拉取已验证BOM版本。
校验Python版本与系统加密库
Qoder CLI底层依赖Python 3.8–3.10区间版本，超出此范围将触发qoder-cli进程崩溃；同时openssl 1.1.1w过旧会导致HTTPS端点探测失败。
执行python --version，若输出为3.11+，必须用pyenv install 3.10.13 && pyenv global 3.10.13切换默认版本。
运行qoder-cli doctor --full-report，重点查看报告中红色ERROR项——若出现openssl版本警告，需升级系统openssl至≥3.0.0（Ubuntu执行sudo apt-get install openssl libssl-dev；macOS执行brew install openssl）。
禁用代理与清除锁文件
系统代理启用状态下，Qoder CLI会因模型端点探测超时而静默跳过GitHub PAT校验，导致后续依赖加载中断。
Linux/macOS用户在安装前执行export HTTP_PROXY="" && export HTTPS_PROXY=""；Windows用户在PowerShell中运行$env:HTTP_PROXY=""。
若安装卡在99%，极可能遗留.install.lock或qoder-installer.pi等锁文件。执行find /tmp ~/.qoder -name "*.lock" -delete → rm -f ~/.qoder/.install.lock → sudo rm -f /var/lock/qoder.*。
