三步跑通 WebTorrent Desktop：流媒体种子下载与边下边播指南
项目地址: https://gitcode.com/gh_mirrors/we/webtorrent-desktop WebTorrent Desktop 是一款支持 Mac、Windows 和 Linux 的流媒体种子下载播放器：把 .torrent 文件拖进去，不用等下载完成就能边下边播。这篇文章带你把它跑起来，顺手把常见的环境坑和界面问题一次排掉。
📦 跑起来之前：下载渠道、Node 版本与依赖安装
如果你只想用它，从官方发布渠道下载对应平台的安装包最省事：Windows 上右键查看文件属性里的数字签名，macOS 上确认应用能直接打开，就能判断包没被篡改。习惯命令行的话，Homebrew 用户一条 brew install --cask webtorrent 就能装好。
想自己跑源码或改点东西，先克隆仓库：git clone https://gitcode.com/gh_mirrors/we/webtorrent-desktop，进入目录执行 npm install。这里有个容易踩的坑：package.json 声明了引擎要求，Node 需要 16 或 18 系列（^16.0.0 || ^18.0.0），版本不对时安装依赖大概率报错。装完用 npm start 启动；日常开发推荐 npm run watch，代码一改动应用就自动重启，不用手动刷新。
🖥️ 界面显示异常排查：三个高频现象
Mac 上窗口显示不全怎么办
窗口内容被裁掉一块、或控件叠在一起，多数出在非 Retina 显示器或系统缩放比例异常上。先手动拖一下窗口大小，不少错乱会随之缓解；还不行就更新显卡驱动和系统，再用 npm run watch 在开发模式下复现，确认到底是环境还是代码的问题。窗口创建逻辑集中在 src/main/windows/main.js，定位报错从这里入手最快。
Windows 低分辨率下界面被裁剪怎么解决
1366x768 或更低的屏幕上界面被截断，通常和系统显示缩放有关。把"缩放与布局"调回 100% 再启动试试；如果只有播放页异常，切一次全屏再退出，窗口尺寸会被重新计算，相关逻辑可以看 src/main/windows/index.js。
改完代码界面没变化怎么排查
先确认你跑的是 npm run watch 而不是 npm start——后者不会自动重启。renderer 层的改动偶尔需要完全退出应用再启动，只关窗口是不够的。
🧪 想提 PR？先搞懂集成测试的截图基线机制
npm test 会先跑 standard 风格检查和依赖检查（depcheck），这是最基础的一道关。真正的大头是 npm run test-integration：它用 Spectron 加 Tape 自动点开应用、点击按钮，每一步都截图，再和参考图逐像素对比，用例入口在 test/index.js。
集成测试截图不一致怎么排查
UI 有改动时几条用例失败是预期行为，先别急。把失败的参考截图删掉，重新跑 npm run test-integration，测试会按新界面重新生成基线。生成后逐张对比一遍，确认变化确实是你改出来的，而不是字体、图标之类的意外偏移。
集成测试环境的硬性要求
macOS 需要 Retina 屏，分辨率要与 2018 款 MacBook Pro 13 寸一致；Windows 需要 Win10 加 1366x768 屏幕。测试运行期间把鼠标停在屏幕边缘别动，键盘也别碰，任何一次误触都会让截图对不上。
💬 卡住了，去哪找帮助
提 issue 前先去 issues 区搜一下，同样的分辨率或驱动问题大概率有人踩过。没有现成答案，就贴出操作系统版本、屏幕分辨率和完整报错；社区讨论区里也能翻到不少打包与自动更新的实战经验。
打开 issue 入口，把系统版本、分辨率和 npm start 的报错原样贴上去。这比一句"界面有问题"能让维护者快十倍定位。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
