适用版本 V3 WindowsmacOSLinux
本篇说明
按现象查找处理办法，每条都给出详细说明所在的篇目。找不到对应现象时，先运行 kh doctor 看环境，再看日志（图形界面在「系统日志」面板和 app.log：Windows 优先在程序目录旁的 logs 文件夹，写不进去时在 用户目录\KhQuant\logs，macOS 在 ~/Library/Logs/khQuant/，见 1.9；命令行直接显示在终端）。第 1 部分的通用问题见各篇的常见问题。
1 安装与启动
| 现象 | 原因和处理 | 详见 |
|---|
| Windows 双击图标很久没反应 | 「用户账户控制」窗口在等你确认（可能被挡住），点「是」。V3 每次启动都会弹 | 2.1 |
| 提示「看海量化已经在运行」 | 只能开一个主窗口，切到已打开的窗口 | 1.3 |
| 装了 V3 后 V2.1 不见了 | V2.1 和 V3 是同一个安装标识，会被原地升级。V2.2 使用独立安装标识，可以和 V3 共存 | 2.1 |
| Mac 提示「无法验证开发者」 | 提示里点「完成」（不要点「移到废纸篓」），再到「系统设置 → 隐私与安全性」点「仍要打开」 | 2.4 |
| Mac 点地球图标提示缺少命令行组件 | 先在终端运行 kh web，再点图标 | 2.4 |
| 工具栏指示灯一直是红的 | 「DuckDB数据路径未设置」：去「设置 → 数据设置」填；「DuckDB数据库为空」：下载数据 | 2.1 |
| 点「数据管理」提示先配置 DuckDB 数据路径 | 同上，先设置数据目录 | 2.1 |
2 kh 命令行
| 现象 | 原因和处理 | 详见 |
|---|
找不到 kh 命令 | Windows：安装时勾「添加 kh 命令到系统 PATH」，并新开终端；Mac：工具栏「安装CLI」；Linux：pipx ensurepath 后重开终端 | 2.1、2.4、2.5 |
ERR 尚未初始化，请先运行: kh init | 运行 kh init，或在图形界面保存一次设置 | 2.2 |
kh init 第 3 步报 FileNotFoundError … 'D:\\' | 3.4.1.9 及更早版本、电脑没有 D 盘时才会出现：升级到最新版，或重跑 kh init 手动填路径 | 2.2 |
unrecognized arguments: --json | 参数要写在子命令后面：kh result list --json | 附录 A |
ERR 配置文件不存在 | 文件名写错，或不在当前目录和策略目录里 | 2.2 |
kh data sync --schedule 报需要 schedule 库 | Linux：pipx inject khquant schedule | 2.3、2.5 |
pipx upgrade khquant 不起作用 | 用 pipx install --force 安装新版 wheel | 2.5 |
3 数据下载
| 现象 | 原因和处理 | 详见 |
|---|
tx：UNSUPPORTED_SYMBOL 或「无法开始下载」 | tx 不支持深市 ETF/LOF、可转债，从股票池里去掉或换数据源 | 2.3 |
tx：NO_CLOSED_SESSION | 当天数据 16:00 以后才有 | 2.3 |
tx：RETENTION_EXCEEDED | 分钟线超出保留期（1 分钟约 1 个月、5 分钟约半年），缩短区间或加 --allow-gaps | 2.3 |
tx：RAW_PRICE_CONFLICT | 库里已有原始价和 tx 不一致，用 --data-root 下到独立目录 | 2.3 |
VOLUME_UNIT_CONFLICT | 要写入的数据声明的成交量单位不是「手」或成交额单位不是「元」，拒绝写入；旧库单位标记缺失或不一致时不会报这个错，而是续写并在 stock_info 记 legacy_units_unverified | 2.3、1.4 |
同花顺：AUTH_FAILED 或「未配置同花顺 API Key」 | 检查 Key，重新保存并「测试连接」 | 2.3 |
| 同花顺下沪深 300 不对 | 代码要写 000300.SH | 2.3 |
| HTTP 桥接：无法连接 / 连接超时 | 服务端是否运行、是否 --host 0.0.0.0、防火墙是否放行 8001 | 2.3 |
HTTP 桥接：403 Client Error: Forbidden | API Key 不对，重新复制服务端的 Key | 2.3 |
miniQMT：CLIENT_NOT_CONNECTED / 显示「MiniQMT未连接」 | 启动并登录 miniQMT | 2.3 |
| 提示 DuckDB 文件被其他程序占用 | 关掉数据管理窗口、正在跑的回测或自己打开库的脚本；用「占用诊断」查看占用程序 | 1.4、1.11 |
| Mac 上没有「MiniQMT导入」「定时补充」 | 这两个只在 Windows 上有，用 HTTP 桥接或 kh data sync | 2.3 |
4 定时补数据
| 现象 | 原因和处理 | 详见 |
|---|
| 到点没执行 | 电脑睡眠/关机、没点「开始定时」、终端被关掉。错过的用 kh data scan --fix 补 | 2.3 |
| 定时补充窗口显示「不可用」 | 它只能用 miniQMT，先启动并登录 miniQMT；没有 miniQMT 请用 kh data sync | 2.3 |
| 定时补充窗口控件挤在一起 | 点最大化 | 2.3 |
| 用 tx 补的数据回测时缺复权价 | sync 和 scan --fix 用 tx 时只补不复权价，再运行一次 kh data download … --adj front | 2.3 |
5 回测
| 现象 | 原因和处理 | 详见 |
|---|
| 回测跑完一笔交易都没有，日志有「回测期间没有产生交易记录」 | 最常见：用 tx 下载时没加 --adj front，策略要的前复权价是空的。重新下载前复权数据 | 2.2 |
| 日线策略在分段载入（选了「省内存（分段）」，或「智能」在内存紧张时自动分段）后没有交易、没有结果 | V3.4.1.4 及更早版本的问题，升级到最新版 | 1.12 |
| 回测报「回测区间内 N 根K线全部取不到行情数据……无法进行回测」 | 股票池在回测区间内一条行情都没有：检查数据目录、周期和股票池，确认数据下载覆盖了回测区间（V3.4.1.5 起不再静默显示成功） | 1.12、1.4 |
命令行 kh tool parquet-cache build 报「拒绝访问」（PermissionError） | 没设 Parquet 缓存目录，默认建在安装目录里，命令行没有写权限。先在「回测性能」里设缓存目录，或 kh config set performance_parquet_cache_pack_root 目录 | 1.12 |
| 开始前提示「关键回测数据缺失」（命令行和网页的回测前检查；桌面版报「基准合约数据缺失」） | 基准或股票缺数据。用 tx 时自动补的沪深300 只有不复权价，前复权回测需要单独下 000300.SH --adj front | 2.3 |
ERR 股票数据不存在 | 这只股票没下载，kh data list 看库里有什么 | 2.2 |
| 回测提示「DuckDB数据源初始化失败」 | 先检查设置里的数据目录是否存在、是否填对；再看数据库是不是正在被写入（下载或定时补充），等写完再跑 | 1.12 |
| 同一个案例每次结果不同 | 案例参数是随机生成的，改成固定值 | 3.5、1.12 |
| 股票池都是 ETF 却按 T+1 运行 | 池里有不在 T+0 清单里的品种，整池按 T+1 | 3.5 |
| 卖出被拒「可用持仓不足」 | T+1 下当天买入的当天不能卖 | 3.5 |
khRequestNextDailyTrigger() 一直返回 False | 返回 False 有两种原因：触发方式不是日K线触发，或当天的日内触发上限已经用完（上限要大于 1）。请求只在 khHandlebar 里有效；在 khPreMarket 里调用虽然返回 True，也不会增加当天的回调，在 khPostMarket 里调用同样不会增加 | 3.5 |
| 个股分析点日 K 线打不开日内图 | 缺日线或 1 分钟数据 | 3.5 |
| 16GB 内存跑全 A 分钟线内存不够 | 缩小股票池或缩短区间 | 1.12 |
6 编辑器、包管理
以下内嵌编辑器与断点调试仅 Windows 版：macOS 没有「编辑器」按钮；Linux 没有图形界面，用你自己的编辑器改策略文件。包管理也只在 Windows 版。
| 现象 | 原因和处理 | 详见 |
|---|
| （仅 Windows）点「编辑器」提示「需要安装VSCode」 | 先安装 VS Code；已经装了的话，检查是不是开了两个主程序或 8765 端口被占用，重启软件 | 2.7 |
| （仅 Windows）编辑器开着时点「开始运行」回测不动 | 在等调试器连接。到 VS Code 里按 Ctrl+Shift+D，选「看海策略调试 - 附加到进程」按 F5；编辑器已关掉的，再点一次「编辑器」会自动连上。关掉编辑器、点「停止运行」都解不开 | 2.7 |
| （仅 Windows）VS Code 里没有高亮、不能调试 | 在内嵌 VS Code 里装 Python 扩展 | 2.7 |
| 包管理提示「外部 pip 调用失败」 | 看上面的输出：三次都是「命令启动失败」才是没装 Python（装 64 位 Python 并加入 PATH，重启软件）；是 pip 自己的报错就按那条报错处理 | 2.8 |
| 包管理显示安装成功但版本没变 | 升级要写 -U 包名 | 2.8 |
| 策略 import 第三方库报 ModuleNotFoundError | 策略第一行要是 from khQuantImport import *，第三方库写在它后面 | 2.8 |
7 Web 工作台
| 现象 | 原因和处理 | 详见 |
|---|
| 提示端口 8766 已被占用 | 关掉占用的程序，或 kh web --port 8800 | 2.6 |
| 预检提示「网页回测仅支持 DuckDB 数据源」 | 桌面版设置里把回测数据源改回 DuckDB | 2.6 |
| 手机打不开 | 地球图标启动的服务只限本机；用 kh web --host 0.0.0.0 或临时外网访问 | 2.6 |
| 「开启临时外网访问」按钮是灰的 | 灰色按钮只出现在运行服务的电脑本机上，原因是缺临时访问组件 cloudflared（页面会提示「当前安装缺少临时访问组件」；Linux 要自己装）。从别的电脑或手机访问时根本没有这个按钮，看到的是「正在通过临时安全链接访问」的提示，启停只能在服务器本机操作 | 2.6、2.5 |
| 反向代理后提示「无效的访问主机」 | 把域名加进 KHQUANT_WEB_ALLOWED_HOSTS | 2.6 |
8 结果与数据库
| 现象 | 原因和处理 | 详见 |
|---|
kh result list --strategy 后 show --id 看到别的结果 | 两边序号不一样，用文件夹名查看 | 2.2 |
结果显示「不完整」或收益为 - | 回测没有正常结束，删除后重跑 | 附录 A |
| V2 的回测历史在 V3 里看不到 | 两边结果目录不同，手动复制结果文件夹 | 附录 A |
| SQL 查询返回 0 行 0 列 | 语句写错或表不存在（比如没下过分钟线），界面不报错 | 1.4 |
| 成交量比行情软件小 100 倍 | 库里按「手」存 | 1.4 |
| Python 打开库报 File is already open | 软件正在写这个库，等写完；读库请用 read_only=True | 1.4 |
| 写完自定义指标后回测这些股票报「Failure while replaying WAL file」 | V3.4.1.4 及更早版本写入后留下的问题：「数据管理 → WAL修复」后，升级到最新版重新写入 | 3.5 |
kh data repair 后某只股票数据没了 | 修不好的库被移到数据目录下 _wal_repair_quarantine_时间 文件夹，原位置换成了空库；重新下载这只股票 | 附录 A |
9 AI 助手
| 现象 | 原因和处理 | 详见 |
|---|
| AI 找不到 kh | 同第 2 节「找不到 kh 命令」，改完重启 AI 工具 | 2.2 |
| Skill 没起作用 | 确认安装目录，重启 AI 工具；用 /khquant 或 $khquant 点名 | 2.2 |
本篇基于 V3.4.1.10 编写。
