Windows 首次安装与常见错误

一、安装前准备

• Windows 10 或 Windows 11。
• Python 3.12 或更高版本，安装时勾选 Add Python to PATH。
• Node.js 18 或更高版本。
• 保持网络可用，首次运行需要下载 Python 和 Node.js 依赖。

二、正确下载与解压

1. 从 QFO 最新 Release 下载稳定版 ZIP。
2. 完整解压到独立文件夹，不要直接在压缩包预览窗口中运行。
3. 优先使用不含中文、空格和特殊符号的短路径，例如 D:\QFO。

三、常见错误与处理

现象	原因与处理
Python not found	重新安装 Python 3.12+，勾选 Add Python to PATH；安装后关闭并重新打开启动窗口。
Node.js not found	安装 Node.js 18+，完成后重新运行首次启动脚本。
依赖下载很慢或失败	通常是网络连接或软件源临时异常。保持项目文件不动，网络恢复后再次运行 run_first_time.bat。
双击后窗口立即关闭	确认文件已经完整解压；在文件夹地址栏输入 cmd，再运行脚本以保留错误信息。
页面打开但没有数据	安装已经完成。进入设置页填写自己的 Tushare Token，再到数据中台执行同步。
端口被占用	关闭此前启动的 QFO、Python 或 Node.js 窗口，然后重新启动；不要同时运行多份项目。

四、提交问题前准备

如果仍然失败，请记录 Windows 版本、Python 版本、Node.js 版本、项目解压路径、完整错误截图和启动日志。Token、API Key 等敏感信息必须遮挡或删除。