0.1.3.Alpha.2，引入了 fs-ext@2.1.1 无预编译二进制，强制本地 MSVC 编译

[verneuil]

标题： npm install -g @deepseek-ai/dsh@alpha 在干净的 Windows 环境必败：fs-ext@2.1.1 无预编译二进制，强制本地 MSVC 编译

分类： Bug Report / Help

环境

• Windows 11（10.0.26200），x64
• Node.js v24.15.0，npm 11.x，node-gyp 12.2.0
• 未安装 Visual Studio / VS Build Tools（无 "Desktop development with C++" 工作负载）
• Python 3.14.6 已安装且被 node-gyp 正常识别（不是问题所在）
• 镜像源：registry.npmmirror.com

问题概述

npm install -g @deepseek-ai/dsh@alpha（0.1.3-alpha.2）在安装阶段以 exit code 1 失败并整体回滚。元凶是 fs-ext@2.1.1：这是一个原生插件，其 install 脚本无条件执行 node-gyp configure build，且不提供任何预编译二进制。在没有 Visual Studio Build Tools 的机器上编译必然失败，npm 随即回滚整个安装。同一台机器上安装 @latest（0.1.2-rc.1）成功，说明这是 alpha 线引入的回归。

依赖链（已逐包核对 registry 元数据）

@deepseek-ai/dsh@0.1.3-alpha.2                      (apps/cli)
└─ @deepseek-ai/dsh-base@0.1.3-alpha.2              (packages/bundle/base)
   └─ @deepseek-ai/dsh-session-persistence-jsonl@0.1.3-alpha.2
      └─ "fs-ext": "2.1.1"   （精确锁定版本）

• dsh-session-persistence-jsonl@0.1.2-rc.1（latest 线）只依赖 koffi@^3.1.0 和 schemastery——没有 fs-ext。是 alpha 对 JSONL 持久化后端的改造新引入了这个被精确锁定的 fs-ext 依赖。
• fs-ext@2.1.1 的 package.json："install": "node-gyp configure build"，基于 nan@^2.21.0。没有 prebuild-install、没有按平台分发的预编译产物，且整条依赖链上没有任何一环把它声明为 optionalDependencies——一个原生模块编译失败，就等于整个全局安装失败。

失败日志（节选）

npm error path ...\node_modules\@deepseek-ai\dsh\node_modules\fs-ext
npm error command failed
npm error command C:\WINDOWS\system32\cmd.exe /d /s /c node-gyp configure build
npm error gyp ERR! find VS ... Could not find any Visual Studio installation to use
npm error gyp ERR! stack Error: Could not find any Visual Studio installation to use

[frailove]

我让AI帮我修复了，目前可以成功构建，可以参考如下方案。 you can refer to the following solution:

Environment / 环境

• Windows 11, Node 24, pnpm 11

• No Visual Studio / Build Tools installed (clean contributor machine)

• Windows 11，Node 24，pnpm 11

• 未安装 Visual Studio / Build Tools（干净的开发者机器）

What happens / 现象

pnpm install fails hard: fs-ext@2.1.1 (added in c58097a) has no prebuilt
binaries and must be compiled with node-gyp, so every Windows contributor now
needs the full "Desktop development with C++" toolchain (cl.exe + Windows SDK)
just to install the repo — for a binding that is never invoked on this platform.

pnpm install 直接失败：fs-ext@2.1.1（引入于 c58097a）没有预编译二进制，
必须用 node-gyp 本地编译。这意味着每一位 Windows 贡献者都要装上完整的
“使用 C++ 的桌面开发”工具链（cl.exe + Windows SDK）才能完成安装——
而这个原生绑定在 Windows 平台上根本不会被调用。

Root cause / 根因

packages/session/session-persistence-jsonl/src/lease.ts imports
{ flock } from 'fs-ext' at module top level, but on win32 the lock is a named
kernel semaphore via koffi (win32.ts) — the flock() code path is POSIX-only.
So the import is the only thing dragging the native build onto Windows.

packages/session/session-persistence-jsonl/src/lease.ts 在模块顶层
import { flock } from 'fs-ext'，但 win32 上的锁是通过 koffi 实现的
命名内核信号量（见 win32.ts）——flock() 代码路径仅在 POSIX 上执行。
也就是说，把这个原生编译依赖拖到 Windows 上的，仅仅是一行顶层 import。

The browser worker deployment already stubs fs-ext for exactly this reason,
which confirms non-POSIX deployments don't need the binding.

浏览器 worker 部署正是出于这个原因把 fs-ext 桩掉了，这也印证了
非 POSIX 部署并不需要这个绑定。

Suggested fixes / 建议修法（任选其一）

1. Lazy-import fs-ext inside the POSIX branch of
   SessionWriteLease.acquire() / release() (await import('fs-ext')).
   On win32 the module is never loaded, and allowBuilds: fs-ext: false
   becomes safe for Windows contributors. Smallest possible change.

2. 在 POSIX 分支内改为动态导入 fs-ext（SessionWriteLease.acquire() /
   release() 中使用 await import('fs-ext')）。win32 上该模块永远不会被
   加载，Windows 贡献者就可以安全地设置 allowBuilds: fs-ext: false。
   这是改动最小的方案。

3. Alternatively, move fs-ext behind a POSIX-only platform package, following
   the existing native/landlock-run pattern (linux-only packages that
   cleanly skip on other platforms).

4. 或者，参照现有的 native/landlock-run 模式（仅 Linux 的包在其他平台上
   干净地跳过），把 fs-ext 收进一个仅 POSIX 的平台包里。

Optionally, CONTRIBUTING.md could also document "VS Build Tools" as a Windows
prerequisite for as long as the compile step exists.

另外，只要编译步骤还存在，CONTRIBUTING.md 也可以顺手补充说明
Windows 需要 "VS Build Tools" 作为前置条件。

[1151364285]

我使用第二种方案成功了 也简单

[zhengyuzi]

需要C++ 工具集。可以下载 Microsoft C++ （MSVC） 生成工具，在安装程序中， 选择使用 C++ 进行桌面开发以安装 C++ 工具集。

[eating-huang]

这个工具在哪里下载啊？

[eating-huang]

方案一：安装 Visual Studio 2022 生成工具（最彻底）
这是官方推荐的方案，一劳永逸解决所有原生模块编译问题。

步骤：

下载生成工具
访问 Visual Studio 2022 生成工具下载页，点击“下载生成工具”。

运行安装程序（vs_BuildTools.exe）

选择工作负载
在“工作负载”标签页中，务必勾选：

使用 C++ 的桌面开发（Desktop development with C++）

（可选）在“单个组件”中确认
确保包含：

Windows 10/11 SDK（通常自动勾选）

MSVC v143 工具集

点击安装，等待完成（可能需要 510 分钟，大小约 46 GB）

重启终端（或重新打开命令提示符 / PowerShell DeepSeek 告诉我的答案 仅供参考

[zhengyuzi]

2026版本不行的，要下载2022版本的，https://aka.ms/vs/17/release/vs_buildtools.exe