Windows 前端排障

Windows 上的前端问题常见于 Node 版本、路径分隔符、PowerShell 执行策略和依赖安装状态。

先检查 Node

node --version
npm --version

Jarvis 前端要求 Node 20.19+。版本过旧时，先升级 Node 再重装依赖。

重新安装依赖

cd frontend
npm ci --no-audit
npm run build

如果 npm ci 失败，确认 package-lock.json 没有被本地改坏，且网络能访问 npm registry。

PowerShell 脚本

Windows 启动脚本可能依赖 PowerShell 执行策略。若脚本无法执行，先用管理员策略或当前用户策略修复执行权限。

路径问题

常见问题：

• 混用 / 和 \；
• 盘符大小写导致路径归一化不一致；
• 在 WSL 和 Windows 原生路径之间切换；
• 工作区路径包含特殊字符。

尽量在同一种环境中完成安装、构建和启动。

静态资源旧

如果后端正常但 UI 看起来旧：

1. 重新构建 frontend/。
2. 硬刷新浏览器。
3. 检查 service worker 或缓存。
4. 确认浏览器连接的是当前 checkout 的端口。

桌面壳与 Web UI

桌面壳打包时会带上构建后的前端资源。只修改源码但不重新构建，安装包或 .app 中仍会显示旧 UI。

相关页面

• 快速开始
• 重启与健康检查
• 排障