npm link场景下node_modules变更时如何自动重启VSCode tsserver

触发场景 #

• 本地开发npm包时，通过npm link将/lib目录下的待发布包关联到/consumer目录的消费项目
• /lib目录执行build:watch命令，持续构建输出JS产物与.d.ts类型声明文件
• /consumer项目使用Vite等支持HMR的构建工具，业务代码修改后可正常触发热更新
• 修改/lib源码触发重新构建后，VSCode中TS Server持续提示已导入的链接模块导出不存在，编辑区出现大量红色类型报错，手动执行 TypeScript: Restart TS server 命令后报错可临时修复

问题根因 #

TS Server默认对node_modules目录采用快照缓存策略，不会追踪软链接指向的真实物理路径的文件变更，因此/lib目录下更新的类型声明文件不会被TS Server识别，仍使用旧缓存做类型校验。

配置方案 #

方案1：tsconfig.json 配置监听规则（推荐，无额外依赖） #

在消费项目/consumer的tsconfig.json中添加如下配置：

{
  "compilerOptions": {
    "preserveSymlinks": false
  },
  "watchOptions": {
    "watchFile": "useFsEvents",
    "watchDirectory": "useFsEvents",
    "fallbackPolling": "dynamicPriority",
    "synchronousWatchDirectory": true,
    "excludeDirectories": ["**/node_modules/**", "!**/node_modules/<你的链接包包名>/**"]
  }
}

配置说明：

• preserveSymlinks: false为TypeScript默认值，保留该配置可保证软链接模块的解析逻辑和Node.js原生逻辑一致
• watchOptions调整文件监听策略：默认排除node_modules下所有目录的监听，单独放行被链接的目标包目录，既避免全量监听node_modules导致CPU占用过高、VSCode卡顿，又能让TS Server实时感知链接包的类型文件变更
  配置完成后重启一次TS Server，后续修改链接包代码触发构建时，TS Server会自动刷新类型缓存，无需手动重启。

方案2：VSCode工作区配置（不影响项目公共配置） #

如果不想修改项目内的tsconfig.json影响其他协作者，可以在/consumer/.vscode/settings.json中添加工作区级配置：

{
  "typescript.tsserver.watchOptions": {
    "watchFile": "useFsEvents",
    "watchDirectory": "useFsEvents",
    "excludeDirectories": ["**/node_modules/**", "!**/node_modules/<你的链接包包名>/**"]
  }
}

该配置仅对当前本地VSCode工作区生效，不会提交到项目仓库影响其他开发者。

方案3：构建触发文件刷新（兼容4.0以下旧版本TypeScript） #

如果使用的TypeScript版本低于4.0，不支持watchOptions细粒度配置，可以通过变更触发文件的方式让TS Server自动刷新：

• 在/consumer目录下新建一个空的占位文件，命名为.ts-refresh
• 在/lib目录的build:watch构建完成回调中，执行命令更新该占位文件的修改时间：

  # Linux/macOS 环境
  touch /consumer/.ts-refresh
  

  # Windows 环境
  (Get-Item /consumer/.ts-refresh).LastWriteTime = Get-Date
  

TS Server监听到项目内文件变更后，会自动重新扫描所有依赖的类型声明，不会出现类型报错。

注意事项 #

• 上述配置中的<你的链接包包名>需要替换为实际通过npm link关联的包名，比如示例场景中替换为lib
• 不要直接删除excludeDirectories中对node_modules的全局排除规则，否则会导致TS Server监听文件数过多，引发性能问题

内容的提问来源于stack exchange，提问作者shuckster