WebStorm
编辑器能跳转，不等于项目已经导入正确
WebStorm 打开一个目录后，很快就能给 JavaScript 和 TypeScript 着色、补全并跳转。这个反馈容易制造错觉：既然源码看起来正常，项目模型就应该没有问题。等到运行测试，才发现 IDE 调用了系统里的另一套 Node.js；在 monorepo 中打开了某个 package，根目录的 workspace 和 lockfile 没被识别；终端使用 pnpm，运行配置却通过全局 npm 启动。三个入口都能“运行一些东西”，但执行的不是同一份工程。
WebStorm 适合把 JavaScript/TypeScript 项目的导航、重构、测试和调试集中到一个工作面。它不是 Node.js 发行器，也不应该替仓库选择包管理器。项目事实应先由 package.json、lockfile、workspace 声明、tsconfig.json 和测试配置给出，IDE 再消费这些输入。只要这个顺序倒过来，本机索引就可能比 CI 更“聪明”，同时也更难复现。
安装入口、更新责任和许可要一起选
个人开发机通常从 JetBrains Toolbox App 安装稳定通道的 WebStorm。Toolbox 能并存多个版本并保留上一实例，适合先用代表仓库验证升级；代价是多份安装和缓存占用磁盘。团队已有软件分发系统时，可以使用官方 standalone 安装包，把下载、校验、部署和卸载交给终端管理。Linux snap 会自动更新，适合个人快速使用，不适合要求严格冻结 IDE build 的基线。
安装完成先看 Help | About，记录产品 build、IDE runtime、操作系统和 CPU 架构。接着在订阅管理入口确认账号与许可来源，在 Settings | HTTP Proxy 验证代理，在插件页核对批准插件。截图不保留账号、激活信息、内部代理地址或服务器证书。WebStorm 的个人非商业许可、试用和商业订阅有不同使用条件；公司业务不能因为项目尚未收费就把个人许可当作组织席位。动态条款应回到 WebStorm 注册说明复核。
升级时不要同时变更 Node.js、包管理器、TypeScript 和 IDE。先保留旧实例，用同一仓库分别完成安装依赖、类型检查、测试、运行和断点；新版本通过后再扩大范围。若升级失败，优先回到旧 IDE 实例，仓库与 lockfile 保持不动。清空全部 JetBrains system 目录会带走索引、Local History 和日志，这不是普通回滚动作。
项目根决定 WebStorm 能看见哪份工程
WebStorm 项目结构把当前项目的内容根、资源根、测试源和排除目录组织成分析范围。对单包项目，包含 package.json 和 lockfile 的目录通常就是入口。对 npm、pnpm 或 Yarn workspace，应该打开定义 workspace 的根目录，而不是只打开正在编辑的子包。否则跨包引用、根脚本、共享 TypeScript 配置和统一测试命令可能被拆成互不相关的本地文件。
打开仓库前先在外部终端确认真实根目录：
git rev-parse --show-toplevel
node --version
node -p "process.execPath"
Get-ChildItem package.json,pnpm-lock.yaml,package-lock.json,yarn.lock -ErrorAction SilentlyContinue这些输出回答的是仓库、Node 二进制和依赖主源分别在哪里。WebStorm 内置终端再运行一次，相同项目应得到同一仓库根和可解释的 Node 路径。路径不必逐字符相同，例如项目可能明确使用 WSL 或容器 runtime；但差异必须来自受支持的运行模型，不能来自偶然的 PATH 顺序。
WebStorm 的 Excluded 目录只影响 IDE 分析与部分搜索，不等于删除文件，也不等于构建工具会忽略它。node_modules、构建输出和生成目录通常可作为派生状态排除；源码生成目录若参与类型检查或调试，必须让仓库任务先生成，再按项目模型标记为 generated source。为了让红线消失而排除业务目录，只是把模型错误藏起来。
Node.js 与包管理器是两条独立选择链
在 Settings | Languages & Frameworks | JavaScript Runtime 中选择 Node.js runtime。这里应落到项目声明支持的版本和架构，不能只看下拉框里哪个名字最顺眼。外部终端、IDE 终端、Run Configuration 和测试工具窗口都要输出 process.execPath 与 process.version，才能证明它们没有分别使用系统 Node、版本管理器 shim 和远端 Node。
包管理器由 lockfile 与团队基线决定。仓库只有 pnpm-lock.yaml 时，不要让 IDE 自动用 npm 修复依赖；项目使用 Corepack 或 packageManager 字段时，也要核对当前 Node 发行线是否仍提供对应入口。Node.js 25 版本起 Corepack 不再随 Node.js 分发，所以“Node 自带 Corepack”不能作为长期假设。团队应把包管理器安装或启用步骤写进 bootstrap，并在 WebStorm 里选择同一可执行文件。
依赖安装的第一证据来自冻结模式，而不是 IDE 自动下载成功：
corepack pnpm --version
corepack pnpm install --frozen-lockfile
corepack pnpm run typecheck
corepack pnpm test如果仓库规定 npm 或 Yarn，就使用对应的 clean/frozen 安装命令。预期结果是 lockfile 不被改写、脚本退出码为 0，WebStorm 的测试窗口能够调用同一项目依赖。内网 registry、企业 CA 或代理失败时，保留请求目标、客户端版本和错误类别；不要关闭 TLS，也不要把 token 写进 .idea、.npmrc 示例或运行配置。
用一个错误工作目录证明运行配置确实受控
WebStorm 的 npm、Node.js、Jest、Vitest 等运行配置都会携带工作目录。下面的实验故意让脚本从错误目录启动，避免“能启动”替代“从正确项目启动”。
$lab = Join-Path $env:TEMP "webstorm-cwd-lab"
Remove-Item -Recurse -Force $lab -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path (Join-Path $lab "src") | Out-Null
@'
{"name":"webstorm-cwd-lab","private":true,"scripts":{"verify":"node src/check.js"}}
'@ | Set-Content -Encoding utf8 (Join-Path $lab "package.json")
@'
const fs = require("node:fs");
const path = require("node:path");
if (!fs.existsSync(path.join(process.cwd(), "package.json"))) {
console.error("project-root-missing");
process.exit(2);
}
console.log(`node=${process.execPath}`);
console.log(`cwd=${process.cwd()}`);
'@ | Set-Content -Encoding utf8 (Join-Path $lab "src/check.js")
Push-Location $lab
node .\src\check.js
Pop-Location
Push-Location (Join-Path $lab "src")
node .\check.js
$negativeExit = $LASTEXITCODE
Pop-Location
"negative_exit=$negativeExit"
Remove-Item -Recurse -Force $lab第一次应打印 Node 绝对路径与实验根目录；第二次输出 project-root-missing，退出码为 2。在 WebStorm 新建 Node.js 运行配置时，把 JavaScript 文件指向 src/check.js，工作目录先设为 src 复现失败，再改回 $PROJECT_DIR$。如果 IDE 内反例仍成功，说明配置调用了另一条脚本、父进程改变了目录，或运行前任务隐藏地补了环境。
共享运行配置只能保存相对路径、项目宏、非敏感参数和仓库任务。真实 token、Cookie、内部 URL、个人用户目录与密钥路径留在本机密钥工具或未提交环境文件。提交 .run 或 .idea/runConfigurations 前应逐字段审查，并在另一台干净机器复跑。
调试链要绑定到目标进程与源码映射
Node 调试不是让编辑器“理解代码”，而是 WebStorm 启动或附加到一个启用了 Inspector 的目标进程。最小验证应在项目入口设置断点，通过仓库脚本启动 Debug，确认断点命中、调用栈属于预期文件、环境变量来自预期层，停止后目标进程和监听端口都消失。
TypeScript 或打包后代码还要经过 source map。断点显示为空心时，先确认运行的实际 JavaScript 文件、source map 是否生成、映射里的源码路径能否对应本地内容根，再检查 bundler 的 devtool 配置。不要通过复制产物到源码目录或手改断点位置掩盖路径映射错误。浏览器调试还会经过 CDP target，Node Inspector 与浏览器 target 不是同一协议端点；复杂链路应结合任务、运行与调试配置逐层取证。
测试工具窗口同样应回到仓库脚本。Jest/Vitest 配置、Node 参数、工作目录和环境文件一旦只存在于个人 IDE，CI 就无法复现。团队可以共享“运行当前测试”或固定入口的配置，但最终验收仍运行 package script 并检查退出码。
Workspace Trust 和插件不能替彼此兜底
打开陌生仓库时，先把项目当作未受信输入。配置文件、npm lifecycle、IDE task、文件 watcher 和插件都可能执行代码。WebStorm 的项目信任机制可以延迟一部分项目活动，但它不是恶意插件沙箱。插件与 IDE 进程拥有接近当前用户的文件、环境变量、网络和外部进程能力，安装前仍要审查发布者、来源、签名、兼容范围、数据处理和回滚版本。
JetBrains 的 Required Plugins 能提醒项目缺少插件，不是组织 allowlist，也不限制插件权限。企业基线应通过受控插件仓库、批准清单和终端策略管理；AI 插件还要额外核对源码、提示词、遥测与区域边界，具体工具转入 AI 编码工具家族，而不是塞进 WebStorm 主文。
Settings Sync 或 Backup and Sync 适合恢复个人快捷键、主题和部分插件状态。团队项目事实仍通过仓库评审：EditorConfig、formatter 版本、TypeScript 配置、任务脚本和不含秘密的运行配置可共享；窗口布局、最近文件、本地历史、账号、证书和数据源不应作为团队模板。
索引问题先比较模型，再决定是否清缓存
WebStorm 能构建索引，不代表索引是事实源。切换大分支、升级 TypeScript、改变 workspace 或生成目录后，导航可能暂时与 CLI 不一致。先重新加载 package manager 和项目模型，确认内容根、排除目录、Node runtime 与 TypeScript 版本；再用一个具体符号比较“IDE 定义跳转”和 tsc --noEmit 的结论。只有输入完全一致而派生状态仍错误，才重建索引。
“终端成功，IDE 报模块不存在”通常来自不同 Node、错误工作目录、package manager 不一致、子目录打开方式或运行配置覆盖环境。“IDE 成功，CI 失败”则常由全局包、未提交生成文件、个人 NODE_OPTIONS 或自动下载的工具掩盖。两类故障都应先输出版本、路径、cwd 与脚本，再讨论缓存。
清理顺序从项目派生物开始：关闭相关进程，按仓库说明删除可重建依赖或输出，重新冻结安装并运行测试。WebStorm system/cache 目录放在更后面；Local History 不是备份，清理前必须确认未提交编辑已进入 Git 或另有恢复入口。卸载时分别处理 IDE 实例、配置、system/cache 和项目依赖缓存，不能用递归删除所有 JetBrains 与 Node 目录的脚本省事。
团队支持的是证据链，不是个人手感
WebStorm 成为团队支持入口，需要一份代表仓库验证：安装渠道与 build 可追溯，商业许可分配明确，Node 与包管理器路径符合项目声明，冻结安装不改 lockfile，类型检查和测试通过，断点命中，停止后无残留进程，批准插件可重建，旧版本能够回退。每一项都指向真实命令、配置或管理员记录，不以截图中的绿色图标代替。
monorepo 还要测量项目分析时间、索引磁盘、文件 watcher 和语言服务内存。优化时先缩小真实内容根、排除生成物、按 package 分配任务，再考虑调大内存；把半个仓库排除或关闭检查，可能换来速度，也可能让重构与引用分析失真。
如果团队只需要轻量编辑、已有成熟命令行工具链并且扩展治理更适合 VS Code，WebStorm 的订阅与平台维护成本未必值得。反过来，若 JavaScript/TypeScript 项目高度依赖结构化重构、统一测试调试和 JetBrains 平台能力，WebStorm 可以减少多扩展组合的漂移。退出条件也要提前写清：仓库在没有 WebStorm 时仍能安装、构建、测试和格式化；取消席位或更换 IDE 不会带走项目事实。