一行命令开发启动
在仓库根目录运行:
pnpm dev首次运行会安装项目依赖、准备 Electron、补齐当前平台的 native、构建远程网络辅助程序和机器人运行时,然后进入桌面开发及热更新流程。发布版模式不预下载大装扮索引,应用按实际需要获取;本地源码模式仍准备自己的配套资源。桌面界面与内置 Web 分别运行 Vite 开发服务,主进程和预加载持续增量构建。从 apps/desktop 运行 pnpm dev 也进入相同流程。
装扮商城、任意气泡/字体/头像挂件覆盖、通话背景选择、独立装扮素材保存及商城表情包密钥工具默认不开放。开发时可显式运行:
pnpm dev -- --enable-dress-tools必须同时满足开发运行环境、非打包宿主和该启动参数;正式宿主即使带同名参数也不开放。开关不写入用户偏好,不会随配置同步或备份恢复而开启。相关装扮操作与商城表情密钥恢复由宿主判断,网页和 Remote 不自行启用。它不是移除发布包实现的构建裁剪机制。
普通模式保留消息原有装扮还原、本地已缓存表情与自定义聊天背景。已有装扮覆盖配置与资源保留,普通模式不启用气泡、字体和头像挂件的任意覆盖;重新以开发参数启动后仍可继续使用原配置。关键词功能和声音复刻不受本开关影响。
修改后如何生效
| 修改范围 | 开发行为 |
|---|---|
| 桌面 React 组件与样式 | Vite/React 热更新;兼容的组件修改保留状态 |
| Remote/浏览器界面与样式 | 通过原宿主地址转发 Web 开发服务与 HMR,通常无需刷新页面 |
| 主进程及其引用的共享业务代码 | 构建成功后显示横幅,点击「重启应用」后重启 Electron,不重跑依赖、native 和宿主准备 |
| preload 预加载脚本 | 构建成功后显示横幅,点击「重载界面」后刷新桌面渲染页面 |
| 界面中不能直接热更新的改动 | 显示横幅,点击「重载界面」后完整刷新当前开发界面 |
| native、Electron 宿主、签名和启动器配置 | 完全退出开发版后重新运行 pnpm dev |
主进程和预加载监听会合并短时间内的连续改动。需要应用的更新只保留一条横幅,后续成功构建原位合并;关闭后同一批更新不再弹出,热更新连接重连也不重复提示。点击时统一应用最新成功构建,同时需要重启应用和刷新界面时只重启一次。后续构建中或构建失败时暂不能应用,修正成功后恢复操作。关闭横幅不会应用更新,可在合适时机手动重启开发版。
点击「重启应用」仍会中断当前宿主连接与在途操作,不等于后端模块热替换;兼容的 React 与样式修改继续直接热更新,不额外弹横幅。首次切换到这套开发链路需要重新运行一次 pnpm dev。启动器、Vite 配置、native 与宿主配置的变化仍按完整退出后重新启动处理,不属于横幅接管范围。
主进程和预加载只在实际写出成功产物后重载;语法错误等构建失败保留旧进程/页面,修正后自动继续。当前 electron-vite 6 的 closeBundle 在失败构建后仍会调用,开发配置通过独立适配修正;升级 electron-vite 时若内部监听接口变化会明确报错,须运行 node --test scripts/prepare-dev-electron.test.mjs 核对真实成功、失败和修正路径。编译成功但运行时抛错不属于这项保护。
Web 开发服务只监听本机环回随机端口,由桌面 Vite 进程持有,Electron 自动重启不重建它。Remote 配对、本机 Web 登录、业务 HTTP 与 WebSocket 订阅继续使用原入口;源码模块与热更新连接同样经过原入口认证。关闭桌面开发服务会关闭内置 Web 开发服务。桌面和 Web 使用独立预构建缓存,不互相覆盖。React Refresh 所需的内联引导只在代理的开发 HTML 放行,正式页不变。
开发 Web 的源码映射通过 Vite 的独立 .map 地址按需获取,不再以 Base64 内联到每个运行模块中;打开调试器仍可读取原始源码。原宿主代理为文本代码提供 gzip,源码保留 ETag 条件验证,带版本标识的预构建依赖沿用不可变缓存,均限制为浏览器私有缓存;HTML 与失败响应仍不缓存。
少量 react-icons 图标统一从渲染层 lib/reactIcons.ts 导出,Web 开发服务只预构建该入口实际选用的图标并复用现有 React,不发送整套图标库;图形和属性仍来自原始依赖,不手抄 SVG。正式构建继续使用原有裁剪流程,不运行开发预构建插件。新增同类图标时维护该入口,避免绕回整库导入。
旧版 Remote 连接开发页时,通过原有字符串阶段接口持续显示资源完成项数、确认的编码下载字节与缓存项数,兼容 WebKit 状态码未知但确有接收字节的回执;恢复检查等实际阶段标题保留,资源回报不中断。只有 iPhone WebView 的网络回执或原生代理提供明确网络来源时才累计下载量,来源未知的项单独提示,不拿解压大小猜测。开发模块按需发现,没有固定总量,因此不显示虚构的总大小或百分比;正式静态页仍使用既有资源清单与比例进度。开发模式仍保留热更新与部分完整依赖导出,冷加载可能大于正式构建。
正式构建不启动开发服务、不监听源码,继续生成并提供静态 Web 产物。定向真实浏览器验证使用 node apps/desktop/test/browser/run-development-web.mjs;可通过 WEQ_PLAYWRIGHT_IMPORT、WEQ_BROWSER_EXECUTABLE 复用已有 Playwright 与浏览器,验证 Remote 认证、React/CSS 热更新及计数、草稿和页面实例保留。
基础环境
- Node.js 至少 22.12.0,pnpm 使用根清单锁定的版本。
- 首次或网络助手源码变化时需要 Go,版本遵循仓库
tools/remote-network/go.mod。 - 默认使用发布版 native,不要求 Rust 或 native 私有仓访问。本地源码模式需要对应平台的 Rust/Cargo、系统编译依赖及完整 native 源码和装扮原始输入。
启动器自动准备项目依赖与项目构建,不安装系统工具链。本地 native 源码检查、构建准备、编译或新产物验证与安装失败时,优先检查并复用已有可用构建继续启动,同时提示本次源码改动未生效;没有可用构建、安装恢复未完成或其他准备步骤失败时停止,保留错误输出和非零退出码。Ctrl+C 仍直接退出,不触发回退。
来源配置
共享默认值在 weq.dev.json。本机覆盖写到根目录 weq.dev.local.json,该文件不入库。
默认配置:
{
"native": { "mode": "release", "jobs": 2 },
"userDataDir": ".dev-profile"
}参与 native 开发时,本机配置改为:
{
"native": {
"mode": "local",
"source": "../nt_helper",
"jobs": 2
}
}路径相对 WeQ 仓库根目录解析,与运行命令时的工作目录无关,也接受绝对路径。
| 配置 | 行为 |
|---|---|
native.mode: release | 使用 native/pinned.json 指定的明确发布版本,不自动跟随 latest |
native.mode: local | 检查配置源码的构建输入,变化时自动编译、验证并安装,不再等待回车确认 |
native.source | 本地 native 仓库路径,local 模式必填 |
native.jobs | Cargo 构建任务数,默认 2 |
userDataDir | 默认 .dev-profile,隔离开发数据;设为 null 则使用应用原有默认用户目录 |
WEQ_NATIVE_MODE、WEQ_NATIVE_SOURCE 可覆盖 native 模式与源码目录。发布版模式沿用现有 NT_HELPER_RELEASE_REPO、NT_HELPER_RELEASE_BASE_URL、NT_HELPER_VERSION 和代理配置;版本覆盖必须是明确 tag。Electron 镜像沿用 ELECTRON_MIRROR 等安装器配置,启动器不写死镜像、用户路径或包管理器安装位置。
native 来源由配置明确决定:本地更新失败不会下载发布版,但可以复用仓库中已安装的本地或发布版构建;回退前按原来源校验文件哈希、有效期及真实加载,本地构建还须校验配套装扮。编译期间输入变化时不安装本次产物;新产物验证或安装失败时先保留或恢复旧文件,再验证旧构建是否可用,恢复未完成时停止。回退不更新源码指纹或安装记录,下次启动仍会尝试编译最新源码。发布版过期不会自动改取 latest。若项目版本锚已过期,应按原生产物分发说明验证并升级锚点,重新下载同一版本不能延长有效期。
缓存与安装
- 项目依赖按工作区清单、锁文件、安装元数据、Node/pnpm 环境和直接依赖实际文件检查。需要补齐时执行
pnpm install --frozen-lockfile --prefer-offline --prod=false,确保开发依赖也安装,不改锁文件。 - 文档站
docs/是独立 workspace,使用自己的配置、锁文件和依赖目录;文档依赖缺失或清单变化不触发应用依赖安装。需要预览文档时,在主仓根目录先运行pnpm docs:install,再运行pnpm docs:dev;检查、构建和预览产物分别用pnpm docs:check、pnpm docs:build和pnpm docs:preview。 - native 同时检查来源、平台、安装文件哈希及真实加载结果;本地源码模式额外验证三类装扮资源可查询。发布版模式不要求
.dat,普通启动不会每次联网获取发布清单。 - 本地指纹包含源码、依赖清单、vendor、Cargo 配置及被 Git 忽略的三类装扮原始资源。普通文档、target 产物变化不触发编译。按当前平台显式选择 Rust target 及
.dll、.so或.dylib。 - 本地 native 使用启动器随命令传入的独立
weq-devprofile:继承 release 的运行检查行为,主库保留二级优化,关闭 LTO、使用 16 个代码生成单元并启用增量编译;依赖保留三级优化且不积累增量缓存。配置位于 dev-native.cargo.toml,不改写 native 源码仓库的正式 release 配置。产物与增量缓存位于 Cargo target 的当前平台weq-dev目录,首次切换需要建立一次新缓存,之后源码未变直接复用已安装构建,源码变化复用 Cargo 增量结果。构建配置及 Cargo profile/增量环境覆盖纳入来源指纹,旧 release 记录不会误判为新开发构建。 - 本地装扮沿用发布流程的独立
nt-helper-dress-pack工具,在 Cargo target 下维护一套经来源和哈希校验的缓存;只有原始资源、打包工具或其构建定义变化时才重新加工。普通 native 源码及提交变化复用已有装扮和对应密钥,native 编译设置NT_HELPER_PACK_DRESS=0,不再在构建脚本中重复压缩,也不改写源码资源目录的.dat。首次建立该缓存仍需加工一次。 - 本次安装的 native(本地源码模式另含三份
.dat)在暂存区验证后成套替换;失败时恢复已经替换的文件,不删除旧索引。安装来源保存在不入库的native/.installed.json,不改pinned.json,不自动安装系统权限助手。 - 网络助手按 Go 源码和产物哈希缓存;机器人运行时按 esbuild 的实际输入清单与产物哈希缓存。Electron 开发宿主继续复用已有完整性与签名检查。
- 内置 Web 开发模式按需转换源码,不再等待一次性静态 Web 构建,也不依赖已有
apps/web/dist/public或.weq-dev/web-build.json。正式构建始终重新生成静态 Web。 - 同一仓库的启动及同一 native 源码的编译分别加进程锁。正常退出会释放;已记录的进程退出后可恢复其遗留锁。不会终止其他开发进程。
macOS 的独立开发宿主使用 WeQ Dev 名称、app.weq.desktop.dev 应用标识和 WeQ 应用图标,系统通知不再沿用 Electron 默认身份;不修改依赖中的 Electron 原件,也不改变配置指定的用户数据目录。宿主签名、源应用元数据、权限或 Logo 变化时自动重建缓存。宿主更新需要先完全退出开发版,再运行 pnpm dev,只刷新页面或热更新不会替换正在运行的应用包。首次使用独立开发标识时,macOS 可能重新询问通知授权。
日志与命令
准备阶段和应用使用同一份终端行头实现,统一时间、级别、来源和颜色。时间沿用应用现行北京时间格式。默认只展示关键阶段结果,不按固定行数截断:已就绪检查合并为「运行环境就绪」,初始主进程和预加载构建合并完成摘要;日志初始化、托盘、窗口、账号监视、空关键词规则和正常依赖预打包提示不再逐项刷屏。应用的结构化文件日志仍保留原始事件与详情。
后续主进程/预加载成功构建各记一条结果与耗时,不重复输出开始;构建超过 3 秒才提示正在进行,之后每 15 秒报告一次。外部工具执行期间每 15 秒报告进度;正常收起 Rust 依赖、工具命令与产物清单,失败时展开有界的最近工具输出。同一端 100ms 内的热更新合并为文件数,只表示已推送,不冒称页面已更新。主进程重启时收起首屏前重复的版本、账号打开与 MCP 启动记录,实际首屏就绪后报告重启耗时;此后的切号和服务变化仍正常显示。
构建失败立即保留诊断与定位,并区分尚无成功产物或继续运行上次成功构建;修正后明确报告恢复,不能用 closeBundle 调用冒充成功。真实警告首次显示,同轮重复项汇总次数;开发服务中的重复警告每 30 秒重新计数,下一轮构建也重新报告。Rust 诊断作为同一条记录的续行输出,已展示正文的警告不重复输出 Cargo 数量汇总;已识别的无效动态导入警告按构建汇总模块名,未知输出和告警不直接丢弃。已有应用日志不重复添加行头。
设置 WEQ_LOG_LEVEL=debug 可查看完整构建输出、命令及导入引用链。NO_COLOR 禁用颜色,Ctrl+C 清理本次启动的子进程并显示正常停止,不报启动失败。「运行环境就绪」只表示准备流程结束;native 编译失败而复用旧构建时明确显示「本次源码改动未生效」,仅准备环境时明确标注未启动应用。「应用已就绪」在实际首屏完成绘制后记录并附总耗时,不以 Electron ready 或主进程打包完成代替;启动阶段出现异常时改为「界面已就绪(启动存在异常,见前文)」,不掩盖账号或可选服务失败。本次调整不新增重试、不改变构建和回退策略。
开发模式的尺寸监听告警仍按 WARN 限频计数,并附带最近 100ms 内最多六次回调的创建堆栈和目标尺寸;DEBUG 终端显示调用目标与堆栈,结构化日志保留有界回调记录。诊断只读取浏览器已经交付的尺寸,不额外测量布局,不改变回调调度;正式模式不安装诊断。定向浏览器回归使用 node apps/desktop/test/browser/run-resize-observers.mjs 与 node apps/desktop/test/browser/run-timeline.mjs,同时检查无尺寸告警、绘制前阅读锚点和可见行增高不重叠。
已知 macOS 输入法系统诊断默认收起,DEBUG 保留原文并标为 DEBUG,包括 error messaging the mach port for IMKCFRunLoopWakeUpReliable。Electron 上游记录曾确认该诊断来自 macOS SDK 变化,不影响应用行为;这里仅修正日志展示,不宣称修复系统输入法。过滤只匹配完整系统诊断正文,相似异常、附加故障说明与其他错误仍正常输出。
pnpm dev --prepare-only # 补齐环境和构建后退出,不启动应用
pnpm dev -- --user-data-dir=/custom/dev # 显式覆盖本次开发数据目录
pnpm dev --help # 查看入口说明,不安装或构建无桌面环境的机器可使用 --prepare-only 验证准备流程;真正启动仍需要系统提供 Electron 所需的图形环境和动态库。启动器的合成回归测试不依赖 native 私有源码、QQ 数据或网络下载,CI 为 Windows、Linux 和 macOS 分别安排测试。
应用启动画面
环境准备结束后,桌面窗口在首次绘制后显示;入口 HTML 自带 Logo、主题快照与进度条,不依赖业务模块加载。全流程使用同一份单调递增的阶段进度:资源加载 5%、恢复检查 10%、环境检查 20%、账号打开 35%、首屏身份预载 55%–80%、工作区模块加载 80%、实际绘制 90%、首屏绘制完成 100%。这些是固定工作权重,不表示剩余时间;有真实计数时按阶段区间推进,迟到回调不会倒退进度。
工作区挂载时进度条收为顶部细线,不遮挡可操作界面;首屏完成绘制后到达 100% 并移除,不等待完整联系人目录、通知或在线状态。账号选择和诊断页同样在实际界面就绪后结束启动。
首屏只加载必要界面与轻量宿主;转发窗口正文在首次打开时加载,等待期间仍可关闭,已关闭窗口不会在加载完成后重新出现。确认进入账号的身份预热及切号阶段会并行预载主界面代码,不提前挂载工作区或发起其中的业务查询,也不等待代码预载来阻塞账号预热。
本轮自动进入目标有效时,初始窗口直接使用工作区尺寸;没有目标或跳过自动进入时使用账号选择尺寸,自动进入失败则回到账号选择。窗口创建和后续布局统一使用内容区尺寸,并在隐藏时完成初始布局,重复布局通知不重置用户调整。
定向回归:pnpm --filter @weq/desktop exec vitest run test/startup_window.test.ts test/startup_account.test.ts test/startup_surface.test.ts test/startup_theme.test.ts test/startup_progress.test.ts test/window_layout.test.ts。实际绘制检查使用 node apps/desktop/test/browser/run-startup-flow.mjs;可用 WEQ_PLAYWRIGHT_IMPORT、WEQ_BROWSER_EXECUTABLE 指定已有浏览器依赖,WEQ_STARTUP_ELECTRON=1 同时验证隔离 Electron 窗口,不打开真实账号。
