☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
DSH Desktop Windows NSIS 安装器深度解析：`yarn dist:win` 的原生 x64 打包链路与无签名验证门禁
2026/9/20 5:22:29 网站建设 项目流程

DSH Desktop Windows NSIS 安装器深度解析：yarn dist:win的原生 x64 打包链路与无签名验证门禁

【免费下载链接】deepseek-harness-desktop为 DeepSeek Harness (DSH) 插件生态打造的现代化桌面端解决方案。万物皆「插件」，桌面本身也是「插件」。项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness-desktop

DSH Desktop（dsh-plugin-desktop）为 DeepSeek Harness 插件生态提供了一整套跨平台桌面打包体系，其中 Windows x64 NSIS 安装器的构建由yarn dist:win命令承载。本文基于仓库中的架构决策记录（.agents/notes/implemented/architecture/2026-08-15-windows-local-nsis-installer.md），结合 dsh-plugin-desktop/scripts/package-win.ts、dsh-plugin-desktop/scripts/verify-win-installer.ts、dsh-plugin-desktop/scripts/verify-packaged-runtime.ts 等源码，完整还原从宿主门禁、打包前 gate、NSIS 配置、无签名纪律、运行时依赖准备到产物校验的整条链路，并说明其作为「本地安装 + 原生 smoke 测试」产物与正式 Authenticode 发布之间的边界。

一、这条命令解决什么问题

yarn dist:win是 DSH Desktop 提供的原生 Windows x64 打包命令：在原生 Windows x64 机器上，先运行一组 Windows 可安全执行的构建与测试 gate，再由 Electron Builder 生成一个带向导（assisted）的 NSIS 安装器，并对其产物做严格校验。

这个安装器面向两个明确目标：

  • 本地安装：支持当前用户安装（per-user）或提升权限后的所有用户安装（elevated all-users），支持自选安装目录，创建开始菜单与桌面快捷方式；
  • 原生 smoke 测试：安装器 UI、升级与卸载行为、Mica 材质、托盘终端、Windows ACL 沙箱、控制台窗口抑制等平台行为，需要在真实 Windows 机器上验证。

同时必须明确它的身份边界：这是一个未签名（unsigned）的测试产物，不建立 Authenticode 发布身份，也不建立 SmartScreen 信誉。官方签名发布走独立的签名命令与证书 preflight。

二、命令入口与整体调用链

在仓库根目录的 package.json 中，dist:win被定义为一条串行命令链：

"dist:win": "yarn aa:prepare-release && yarn workspace dsh-community-market build && yarn workspace dsh-plugin-desktop dist:win"

即依次执行：

  1. aa:prepare-release：准备 agents-anywhere 发布所需的 vendored 运行时；
  2. yarn workspace dsh-community-market build：构建插件市场；
  3. yarn workspace dsh-plugin-desktop dist:win：真正执行 Windows 打包，其脚本定义为node scripts/package-win.ts（见 dsh-plugin-desktop/package.json）。

在 Windows 上通过 Corepack 调用：

corepack.cmd yarn dist:win

Beta 通道对应dist:win:beta，指向dsh-plugin-desktop-beta工作区（package.json），同一套逻辑由 beta 工作区的 dsh-plugin-desktop-beta/scripts/package-win.ts 承载。

三、宿主门禁：只允许原生 Windows x64

scripts/package-win.ts 中的assertWindowsPackageHost对打包宿主做三道硬性检查，任何一项不满足都会直接抛错终止：

检查项要求失败原因
平台process.platform === 'win32'必须在原生 Windows 宿主构建
Node 架构process.arch === 'x64'仅支持 x64 Node
Node 版本major === 22 && minor >= 19或major === 24官方运行时必须自带 Corepack

Node 版本要求（22.19+ 或 24.x）不是随意约束——Corepack 随 Node 官方发行捆绑，打包脚本正是通过corepack yarn ...启动子进程（package-win.ts），因此要求 Node 自带 Corepack。这与 package.json 中engines: { "node": "^22.19.0 || >=24.0.0" }的声明一致。

四、打包前 Gate：check:win-package

在真正调用 Electron Builder 之前，packageWindowsArtifact会通过cmd.exe执行corepack yarn workspace dsh-plugin-desktop check:win-package（package-win.ts）。该 gate 的内容定义在 package.json：

"check:win-package": "yarn workspace dsh-community-market build && yarn run build && yarn run typecheck && vitest run tests/package.spec.ts tests/package-win.spec.ts tests/desktop-installer-quit.spec.ts tests/installer-nsh.spec.ts tests/update-checker.spec.ts tests/update-download.spec.ts tests/verify-win-installer.spec.ts tests/verify-win-portable.spec.ts tests/verify-packaged-runtime.spec.ts tests/windows-pwsh-sandbox.spec.ts tests/windows-volume-diagnostics.spec.ts tests/window-options.spec.ts tests/safe-mode.spec.ts && yarn run verify:closure"

它由四部分构成：

  1. 构建：yarn run build依次执行 Windows/macOS 图标生成、tsdown打包、native-ui 的 Vite 构建、以及所有 TypeScript 声明文件的tsc输出；
  2. 全部 TypeScript compiler face：typecheck对tsconfig.json、tsconfig.client.json、tsconfig.native-ui.json、tsconfig.tests.json、tsconfig.tests.client.json五个工程做--noEmit检查（package.json）；
  3. Windows 聚焦测试：只运行与打包、NSIS、安装器退出、更新下载、PE 产物校验、PWSh 沙箱、窗口选项、Safe Mode 相关的测试套件，而非完整跨平台 suite。设计文档特别说明：完整跨平台 suite 仍由 CI 持有，因为其中部分 POSIX 执行测试（如真实登录 shell 测试）不是 Windows 程序，不应阻塞原生 Windows 打包；
  4. runtime-closure 验证：yarn run verify:closure由 scripts/verify-runtime-closure.mjs 驱动，校验全部 first-party 包（如@deepseek-ai/dsh-*系列）在dsh-plugin-desktop的依赖中构成一个封闭可达的运行时图，防止出现缺失的一阶依赖导致打包出的运行时无法启动。

如果环境变量DSH_PACKAGE_CHECK_ALREADY_RAN=1，则跳过该 preflight（package-win.ts），避免重复执行。

五、NSIS 安装器配置逐项解析

安装器的行为完全由 dsh-plugin-desktop/package.json 中 Electron Builder 的build段控制。Windows 目标与 NSIS 段的核心配置如下：

"win": { "asar": false, "compression": "normal", "target": [{ "target": "nsis", "arch": ["x64"] }], "icon": "build/app-icon.ico" }, "nsis": { "include": "installer.nsh", "installerIcon": "build/app-icon.ico", "license": "THIRD_PARTY_NOTICES.md", "oneClick": false, "perMachine": false, "allowElevation": true, "allowToChangeInstallationDirectory": true, "createDesktopShortcut": true, "createStartMenuShortcut": true, "differentialPackage": false, "shortcutName": "DSH Desktop", "uninstallerIcon": "build/app-icon.ico", "useZip": false, "artifactName": "DSH-Desktop-${version}-${arch}-Setup.${ext}" }
配置项值含义
oneClickfalse关闭一键安装，使用**带向导（assisted）**的交互式安装流程
perMachinefalse默认按当前用户安装
allowElevationtrue允许用户选择提升权限，执行所有用户（all-users）安装
allowToChangeInstallationDirectorytrue安装向导中允许更改安装目录
createDesktopShortcut/createStartMenuShortcuttrue创建桌面与开始菜单快捷方式
differentialPackagefalse关闭差异包，仅生成完整安装器
shortcutNameDSH Desktop快捷方式名称
artifactNameDSH-Desktop-${version}-${arch}-Setup.${ext}安装器产物命名模板
compressionnormalNSIS 使用正常压缩档
asarfalse应用以物理目录形式随包发布（配合 Electron Fuses 的onlyLoadAppFromAsar=false）

安装器把 THIRD_PARTY_NOTICES.md 作为许可证展示文件（license字段），使用build/app-icon.ico作为安装器与卸载器图标，并通过include: "installer.nsh"注入自定义 NSIS 脚本（见下文第七节）。

升级身份的稳定性：安装器的升级身份锚定在稳定的应用标识appId: "ai.deepseek.dsh.desktop"（package.json）上，NSIS 的升级/覆盖安装正是基于该 appId 判定「同一产品的新版本」，因此设计文档强调 appId 保持稳定是 NSIS 升级身份不丢失的前提。

六、无签名纪律：剥离证书变量但不禁用资源编辑

由于这是一个未签名的本地测试安装器，打包脚本执行严格的「无签名纪律」：

1. 环境变量消毒。withoutWindowsSigningSecrets（package-win.ts）把以下 6 个证书发现/密钥变量从环境里全部删除：

CSC_IDENTITY_AUTO_DISCOVERY CSC_KEY_PASSWORD CSC_LINK CSC_NAME WIN_CSC_KEY_PASSWORD WIN_CSC_LINK

删除是对大小写不敏感的（key.toUpperCase()后匹配），杜绝任何残留证书变量被 Electron Builder 意外拾取。

2. Electron Builder 命令行开关（package-win.ts）：

electron-builder --win nsis --x64 --publish never --config.win.signExecutable=false --config.npmRebuild=false --config.electronFuses.onlyLoadAppFromAsar=false
  • --publish never：禁用一切发布动作；
  • --config.win.signExecutable=false：禁用可执行文件签名，但不禁用 Windows 资源编辑——图标、版本信息等资源仍会写入 PE 文件，这正是设计文档强调「禁用签名但保留资源编辑」的落点；
  • --config.npmRebuild=false：禁用 Electron Builder 的通用原生模块重建（见下文）；
  • 同时环境变量中显式设置CSC_IDENTITY_AUTO_DISCOVERY=false，双保险阻止证书自动发现。

3. Electron Fuses 配合。--config.electronFuses.onlyLoadAppFromAsar=false与 package.json 中的electronFuses（onlyLoadAppFromAsar: false、runAsNode: true、resetAdHocDarwinSignature: true、enableEmbeddedAsarIntegrityValidation: false）保持一致，应用以物理目录形态运行，并保留 RunAsNode 能力供打包后 smoke 使用。

七、运行时依赖：为什么不需要 Python 和 Visual Studio C++ Build Tools

Windows 安装器构建对工具链的关键简化在于node-pty直接使用 Windows x64 Node-API 预编译二进制。verify-packaged-runtime.ts中的REQUIRED_WINDOWS_X64_NODE_PTY_ENTRIES（scripts/verify-packaged-runtime.ts）明确要求以下物理文件必须随包存在：

node_modules/@vscode/ripgrep-win32-x64/bin/rg.exe node_modules/node-pty/prebuilds/win32-x64/conpty.node node_modules/node-pty/prebuilds/win32-x64/conpty_console_list.node node_modules/node-pty/prebuilds/win32-x64/conpty/OpenConsole.exe node_modules/node-pty/prebuilds/win32-x64/conpty/conpty.dll

这些是 node-pty 针对 Windows x64 的 Node-API 预编译产物（含 ConPTY 控制台基础设施）。因此整个安装器构建不依赖 Python 或 Visual Studio C++ Build Tools，避免了 Windows 上最棘手的原生工具链问题。

唯一需要「准备」的原生模块是fs-ext：prepareRuntime调用prepareFsExtForElectron({ platform: 'win32', arch: 'x64', ... })（package-win.ts），其实现位于 scripts/prepare-fs-ext.ts，为 Electron ABI（abi148）准备对应的fs-ext绑定文件（Windows 上为fs-ext/prebuilds/win32-x64/electron.abi148.node）。打包脚本通过 scripts/electron-builder-environment.ts 注入DSH_ELECTRON_BUILDER_TRAVERSAL_ONLY=1，约束 Electron Builder 只做有界的物理遍历收集依赖，避免 Yarn Berry collector 递归展开整个外层工作区。

八、afterPack 钩子：打包前最后一道运行时完整性验证

Electron Builder 的afterPack钩子指向 scripts/verify-packaged-runtime.ts（package.json），在应用归档完成、签名开始之前执行verifyPackagedRuntime：

  1. 应用归档验证：校验app.asar（或 ASAR-disabled 布局下的物理resources/app）包含全部必需条目，包括 DSH CLI 运行时文件（@deepseek-ai/dsh/lib/*.js）、PTC preset 输入、pnpm/bin/pnpm.mjs、open/index.js、web 前端index.html等（REQUIRED_PACKAGED_RUNTIME_ENTRIES）；
  2. 物理运行时树验证：app.asar.unpacked（smart-unpack）的物理文件必须与 ASAR 头的unpacked标记精确一致，不允许出现「头外物理文件」「头内未标记」「标记却缺失」三类不一致（verifySelectiveUnpackedRuntime）；
  3. Windows x64 node-pty prebuilds 验证：上面第五节列出的 5 个 Windows 物理条目必须存在；
  4. smart-unpack 预算：物理载荷受预算约束——总量不超过 1500 个文件 / 128 MiB，pnpm 的 smart-unpack 不超过 32 个文件 / 32 MiB（verify-packaged-runtime.ts）；
  5. 架构门禁：Windows 平台的arch必须是 x64（context.arch !== 1即抛错，见 verify-packaged-runtime.ts）。

任何缺失都会让afterPack以 promise 拒绝的形式在 NSIS 打包之前失败，保证进入 NSIS 阶段的应用运行时是完整、封闭的。

九、产物验证第二道 gate：精确版本名 + PE 头校验

NSIS 安装器生成后，打包脚本运行node scripts/verify-win-installer.ts（package-win.ts），verifyWindowsInstaller（scripts/verify-win-installer.ts）执行第二道产物门禁：

  1. 精确版本化路径：版本不是写死的，而是从dsh-plugin-desktop/package.json实时读取（readVersion），然后定位两个文件——
    • 安装器：dist/DSH-Desktop-${version}-x64-Setup.exe
    • 解包应用：dist/win-unpacked/DSH Desktop.exe因此旧版本遗留的安装器无法满足这道 gate——文件名里嵌入了版本号，版本不匹配即校验失败；
  2. 非空常规文件：statSync确认两个文件都是大小 ≥ 68 字节的常规文件（verify-win-installer.ts）；
  3. PE 头校验：读取 DOS 头，确认前两个字节为MZ，再按0x3c处的 PE 偏移读取 4 字节签名，必须等于PE\0\0（assertPortableExecutable，见 verify-win-installer.ts）。

通过后控制台输出Windows installer verification passed: <installerPath>。对应的聚焦测试见 tests/verify-win-installer.spec.ts 与 tests/package-win.spec.ts。

十、安装/升级时的进程交接：installer.nsh 的优雅退出

NSIS 自定义脚本 dsh-plugin-desktop/build/installer.nsh 通过customCheckAppRunning宏处理「应用正在运行时升级安装」的场景，这是升级可靠性的关键一环：

  1. 先通过FIND_PROCESS "DSH Desktop.exe"精确匹配应用进程——注意是应用可执行文件名，而不是$INSTDIR下所有辅助程序，这保留了 #469 修复：无关的 helper 进程永远不会阻塞升级；
  2. 若进程在运行，优先执行优雅退出交接："$INSTDIR\DSH Desktop.exe" --dsh-installer-quit，通过 Electron 的单实例通道让应用自行有序关闭（对应 desktop-installer-quit.ts 实现的 orderly shutdown 路径；2.0.2 及更早版本忽略该参数，因此保留 scoped builder 回退）；
  3. 之后进入等待循环：每 500ms 检查一次进程是否退出，最多等待 30 秒（$R1 < 60次 × 500ms），以容忍慢磁盘、杀软钩子和较大的物理运行时；
  4. 超时后走 scoped 强制关闭路径：弹出提示框征得用户同意，再用KILL_PROCESS按精确可执行名终止进程并持续确认退出。

这套「先优雅、后强制、全程精确匹配进程名」的策略，保证了覆盖安装（upgrade）不会因残留进程失败，同时不会误杀无关进程。相关行为由 tests/installer-nsh.spec.ts 与 tests/desktop-installer-quit.spec.ts 覆盖。

另外，卸载应用时安装器保留 DSH 用户数据（profile 与用户目录不随卸载删除），这是设计文档明确承诺的卸载行为。

十一、原生发布边界：哪些行为仍必须回到 Windows 机器验证

设计文档划出了一条清晰的「原生发布边界」：Windows 打包必须在原生 Windows x64 依赖安装上进行，这样 Koffi 及其他平台相关包才能解析为 Windows 变体（koffi在 package.json 中直接依赖）。在这个前提下，以下行为仍属于Windows 机器验证 gate，不会因为本地生成了 NSIS 安装器就被视为通过：

  • 安装器 UI 的实际显示与交互；
  • 升级与卸载行为（含被安装/卸载的应用在目标机器上的表现）；
  • Mica 材质渲染；
  • 托盘终端（tray terminal）功能；
  • Windows ACL 沙箱（windows-acl-runner.ts）的实际权限行为；
  • 控制台窗口抑制；
  • Authenticode 签名与 SmartScreen 信誉。

与此同时，dist:win产物是未签名的：它不会建立 Authenticode/publisher 身份，也不会积累 SmartScreen 信誉；更新交接（update handoff）只校验下载容器而非发布者身份。因此，正式发布链路要求独立的签名命令走专用证书 preflight——校验安装器、卸载器与应用三者的签名，而不是削弱这个未签名命令的纪律。

十二、相关源码与测试索引

围绕本文主题，可以在仓库中继续深入阅读以下文件：

  • 架构决策记录：.agents/notes/implemented/architecture/2026-08-15-windows-local-nsis-installer.md
  • 打包脚本：scripts/package-win.ts、scripts/package-win-portable.ts
  • 产物校验：scripts/verify-win-installer.ts、scripts/verify-packaged-runtime.ts
  • 运行时封闭图：scripts/runtime-closure.mjs、scripts/verify-runtime-closure.mjs
  • NSIS 自定义逻辑：build/installer.nsh、src/desktop-installer-quit.ts
  • 构建配置：dsh-plugin-desktop/package.json 的build/nsis段
  • 聚焦测试：tests/package-win.spec.ts、tests/verify-win-installer.spec.ts、tests/installer-nsh.spec.ts、tests/desktop-installer-quit.spec.ts、tests/verify-packaged-runtime.spec.ts
  • 使用说明：dsh-plugin-desktop/README.md（及 dsh-plugin-desktop/README.zh.md）中的dist:win章节

十三、小结：一句话记住这条链路

yarn dist:win=宿主门禁（Windows + x64 + Node 22.19+/24.x）→check:win-package构建与聚焦测试 gate → runtime-closure 校验 → 证书变量剥离与signExecutable=false→ 原生依赖准备（node-pty prebuilds + fs-ext ABI 绑定）→ Electron Builder NSIS 打包 → afterPack 运行时完整性验证 → 精确版本名 + MZ/PE 头产物校验。

它是一条「为本地安装与原生 smoke 测试而设计」的完整闭环：不依赖 Python/VS Build Tools、不接触任何签名材料、不发布、不建立 Authenticode 身份，但每一步都通过源码级校验确保产物可用——这正是它作为发布前回归防线与未来签名命令前置基础的价值所在。

【免费下载链接】deepseek-harness-desktop为 DeepSeek Harness (DSH) 插件生态打造的现代化桌面端解决方案。万物皆「插件」，桌面本身也是「插件」。项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness-desktop

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

CANN ops-math 数学算子 Erfc（互补误差函数）：aclnnErfc 与 aclnnInplaceErfc 双段式接口使用指南
2026/9/20 5:22:11 网站建设

CANN ops-math 数学算子 Erfc（互补误差函数）：aclnnErfc 与 aclnnInplaceErfc 双段式接口使用指南

CANN ops-math 数学算子 Erfc&#xff08;互补误差函数&#xff09;&#xff1a;aclnnErfc 与 aclnnInplaceErfc 双段式接口使用指南 【免费下载链接】ops-math 本项目是CANN提供的数学类基础计算算子库&#xff0c;实现网络在NPU上加速计算。 项目地址: https://gitcode.com…...

阅读更多 →
国产MQTT协议栈替代实战：从Mosquitto迁移的合规与选型指南
2026/9/20 5:21:25 网站建设

国产MQTT协议栈替代实战：从Mosquitto迁移的合规与选型指南

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …...

阅读更多 →
戴森球计划工厂蓝图怎么选？FactoryBluePrints 从开荒到终局的完整路线图
2026/9/20 5:21:15 网站建设

戴森球计划工厂蓝图怎么选？FactoryBluePrints 从开荒到终局的完整路线图

戴森球计划工厂蓝图怎么选&#xff1f;FactoryBluePrints 从开荒到终局的完整路线图 【免费下载链接】kubeedge Kubernetes Native Edge Computing Framework (project under CNCF) 项目地址: https://gitcode.com/GitHub_Trending/ku/kubeedge FactoryBluePrints 是戴森…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询