任务、运行与调试
项目刚开始时，大家常用 IDE 的绿色三角形启动服务。等仓库里有前端、后端、代码生成和容器依赖后，同一个按钮可能先执行构建任务，再启动两个进程，最后附加浏览器。此时“点一下能跑”已经不够：断点为什么是灰色，环境变量从哪里来，停止按钮会杀掉哪个进程，远端调试端口是否暴露，都必须能够解释。
先记住一句话：task 处理工作，run 创建业务进程，debug 在 run 的基础上建立可观测、可控制的调试会话。 三者可以串联，但不是同一个对象。
先建立可解释的运行基线
不要从复制别人仓库里的 launch.json 开始。先让代表项目在终端独立运行，并记录运行时版本、构建命令、入口文件、工作目录、监听地址、退出信号和健康检查。IDE 只是把这组事实映射成界面和配置；终端入口都不稳定时，调试按钮只会把真正的错误包在更多日志下面。
跨 IDE 协作时，应选择同一条代表链路做交叉验证。例如 JVM 项目可以在 JetBrains IDE 与 VS Code 或 Eclipse 中分别建立入口，Node 项目可以在 VS Code 与另一款支持相应工作负载的 IDE 中复现。验收对象不是配置文件语法相同，而是同一 commit、同一工作目录、同一参数和同一健康检查得到一致行为。
实验环境只绑定回环地址和测试端口。调试参数不能原样带入生产实例，真实 token、数据库密码、证书私钥和内网地址也不能进入共享配置。远程调试协议通常具有读取状态、执行表达式甚至改变进程行为的能力，暴露调试端口相当于暴露控制入口。
先把 task、run 和 debug 分开
task 是对命令或工具的编排。编译、代码生成、lint、启动 watch 进程都可以是 task。它关心命令、参数、工作目录、输入输出、依赖顺序、后台任务何时“就绪”，不天然知道断点、线程和变量。VS Code 的 tasks.json 是显式任务模型；JetBrains 的 Before Launch、External Tool、Maven/Gradle 配置，Visual Studio 的构建任务，Eclipse 的 builder 或 external tools 都能承担相近职责，但持久化格式不同。
run 是按照一组启动属性创建目标进程：可执行文件、参数、工作目录、环境变量、运行时和目标环境。它应该在不接调试器时也能证明业务行为正确。若只有 Debug 能启动，Run 一启动就失败，通常说明调试配置偷偷承担了本应属于项目启动契约的工作。
debug 则在启动或连接目标后，增加断点、暂停、单步、调用栈、变量求值等控制面。IDE 的调试 UI 往往通过某个调试适配器，再连接语言运行时或原生调试器。调试器能改变时序，也可能执行表达式和修改变量，所以“Debug 成功”不能替代普通 Run 和测试验证。
一个稳健的顺序是：
终端命令可运行
-> task 可重复准备构建或 watch
-> run 使用同一入口得到相同行为
-> debug 命中断点且退出语义符合预期第一次跑通：用 Node 建立最小证据
下面用 Node 做最小实验，因为它能同时展示 task、run、Inspector 和 source map 接线。新建测试目录并准备 app.js：
const http = require("node:http");
const port = Number(process.env.APP_PORT || 3000);
const server = http.createServer((request, response) => {
const message = `ok:${request.url}`;
response.end(message);
});
server.listen(port, "127.0.0.1", () => {
console.log(`ready:http://127.0.0.1:${port}`);
});
process.on("SIGTERM", () => server.close(() => process.exit(0)));先在终端运行：
$env:APP_PORT = "3100"
node .\app.js另开终端访问：
Invoke-WebRequest http://127.0.0.1:3100/health | Select-Object -ExpandProperty Content预期得到 ok:/health，服务终端出现 ready:http://127.0.0.1:3100。这一步只证明 run 契约成立。按 Ctrl+C 后再次访问应连接失败，说明清理完成且端口没有残留。
在 VS Code 中，可把相同入口写成 .vscode/tasks.json：
{
"version": "2.0.0",
"tasks": [
{
"label": "serve:demo",
"type": "process",
"command": "node",
"args": ["app.js"],
"options": {
"cwd": "${workspaceFolder}",
"env": { "APP_PORT": "3100" }
},
"isBackground": true,
"problemMatcher": {
"owner": "demo",
"pattern": { "regexp": "^(never-match)$", "message": 1 },
"background": {
"activeOnStart": true,
"beginsPattern": ".*",
"endsPattern": "ready:http://127\\.0\\.0\\.1:3100"
}
}
}
]
}这里使用 process，减少 shell quoting 差异；isBackground 表示任务不会立即退出，background.endsPattern 告诉依赖它的调试配置“服务已经就绪”。如果后台 task 没有就绪判据，IDE 可能永远等待，也可能在服务真正监听前启动浏览器。
最小 launch 配置放在 .vscode/launch.json：
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch demo",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"env": { "APP_PORT": "3100" },
"skipFiles": ["<node_internals>/**"]
}
]
}在 const message 一行设断点并发起请求。预期断点变为已验证状态，请求暂停，Variables 中能看到 request.url；继续执行后客户端收到 ok:/health。停止调试后再次访问应失败，因为这是由调试器 launch 的目标。
完成实验后删除测试目录中的 .vscode 配置和 app.js，并确认 3100 端口未被占用。Windows 可用 Get-NetTCPConnection -LocalPort 3100 -ErrorAction SilentlyContinue 检查；没有输出才表示本机未发现该端口的 TCP 监听或连接残留。
launch 与 attach：差别在所有权，不只是菜单
launch 表示调试侧负责创建目标，通常也负责传入参数、环境变量和工作目录。停止会话时，用户通常期待目标随会话结束。attach 表示目标已经由终端、服务管理器、容器或另一套编排启动，调试侧只接入；断开时默认不应杀死这个外部目标。
这个区别在远程环境尤其重要。你 attach 到共享开发服务后点“停止”，合理结果是调试连接断开，服务继续响应；若适配器把断开解释成杀进程，就会影响其他使用者。反过来，launch 出来的临时浏览器或测试进程若只断开不清理，会留下端口、profile 和子进程。
DAP 的会话结束语义把 terminate 和 disconnect 设计成不同请求，并允许适配器声明能力。典型语义是：launch 目标先尝试优雅终止，attach 目标断开后继续运行；但具体能力由适配器决定。因此团队不能只写“点红方块”，而要为每个配置记录：谁启动目标、停止是否杀目标、子进程是否一起结束、失败时如何手工清理。
调试器真正连接了什么
多数现代编辑器把调试 UI 与具体调试器解耦。IDE 发出设置断点、读取线程、继续和求值等高层请求；Debug Adapter 把这些请求翻译给 JVM、V8、浏览器或原生调试器。DAP 解决的是“工具和适配器怎么说话”，并不替代 JDWP、Inspector 或 CDP。
这张图也解释了常见误判：DAP 连接成功只证明 IDE 能和适配器通信；端口已通只证明传输层可达；断点命中还要求运行时代码、源码版本和路径映射一致。
JVM：JDWP 端口是控制面，不是普通业务端口
JDWP 是 Java Platform Debugger Architecture 的一层，常见 socket transport 名为 dt_socket。本地测试可这样启动 JVM：
java "-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=127.0.0.1:5005" -jar .\app.jarserver=y 表示目标 JVM 监听调试器连接；suspend=y 表示在调试器接入前暂停启动；address=127.0.0.1:5005 把监听限制在回环地址。IDE 创建 Remote JVM Debug / Attach 配置后连接 127.0.0.1:5005。预期 IDE 显示已连接，JVM 继续执行，断点能绑定到实际加载类。
不要把网上常见的 address=*:5005 原样用于共享或生产网络。JDWP 连接可控制进程和求值，应该经 SSH 隧道、容器端口转发或受控开发网络访问。若必须远程调试，先让远端只监听回环地址，再建立本地转发；转发结束后关闭隧道并撤掉调试参数。
断点灰色时，依次检查：类是否真的加载、IDE 源码对应的 commit 是否与运行制品一致、调试信息是否被剥离、路径和模块是否选对。只证明 Test-NetConnection -ComputerName 127.0.0.1 -Port 5005 成功，不足以证明源码匹配。
Node：Inspector 是 WebSocket 会话
Node.js 调试器文档区分了三种启动语义：--inspect 会立即执行程序，--inspect-brk 在首行等待，--inspect-wait 则等待客户端接入后再执行。最小 attach 实验可运行：
node --inspect-brk=127.0.0.1:9229 .\app.js控制台应打印包含随机会话标识的 ws://127.0.0.1:9229/... 地址。IDE attach 到 9229 后继续执行，再访问 HTTP 端口验证断点。断开调试后，应单独检查 Node 进程是否仍在；attach 模式下它通常仍由启动终端负责终止。
Inspector 不应监听不受信任网卡。它支持远程执行和运行时检查，暴露风险与 JDWP 类似。容器中也不要为了“连得上”就直接发布到所有接口；优先用受控隧道把本地 127.0.0.1 映射到目标侧回环端口。
浏览器：IDE 连接的是 CDP target
Chromium 调试不是简单连接一个 JavaScript 进程。CDP 先发现 page、worker、service worker 等 target，再附加到目标会话。VS Code 内置 JavaScript 调试器可以 launch 新浏览器，也可以 attach 到以远程调试模式启动的实例。
单独调试实例应使用临时 profile，避免接管日常浏览器中的账号和 Cookie。示意命令如下：
chrome.exe --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-debug-profile"调试结束后先关闭该浏览器实例，再删除专用 profile。不要复用日常 profile，也不要把 CDP 端口暴露到局域网。CDP 的 tip-of-tree 协议会变化且不承诺向后兼容；团队应让浏览器、IDE 和调试适配器版本进入同一升级批次。
source map 与路径映射：断点灰色时先走完整链路
浏览器或 Node 实际执行的是打包后的文件，IDE 展示的是 TypeScript、JSX 或仓库源码。source map 负责“生成位置到原始位置”的映射，path mapping 负责“运行时看到的路径到 IDE 本地路径”的映射。两者缺一都可能出现断点未验证、停在生成文件或同名文件错绑。
排查时按顺序取证：
确认目标实际加载了哪个 URL、脚本或类，不要先猜源码目录。打开生成文件，确认存在可访问的 source map 引用。检查 map 中的 sources、sourceRoot 和构建时路径。
再配置 webRoot、outFiles、sourceMapPathOverrides，或具体适配器提供的 local/remote path mapping。清除旧断点并重启会话，确认断点从空心/灰色变为已验证。
如果 source map 发布到生产环境，它可能暴露源码路径或源码内容；若不公开 map，就要为受控调试和错误平台保留私有制品。Chrome DevTools 默认禁止从远程文件路径加载资源，放开这一选项有安全代价，不能作为常规修复。
环境变量：共享名字，不共享秘密
可提交配置适合保存变量名、无敏感默认值和占位符，例如端口、profile 名称、日志级别。真实密码、token、证书私钥、生产连接串应来自本机环境、受控 .env、密码库或 CI/远程工作区的 secret 注入。
{
"env": {
"APP_ENV": "local",
"APP_PORT": "3100",
"API_TOKEN": "${env:API_TOKEN}"
}
}提交前检查两件事：配置文件里是否出现真实值，调试控制台和诊断日志是否回显了真实值。即使 .env 已被 .gitignore 排除，也要提供 .env.example 说明变量契约，并让缺少变量时快速失败。
JetBrains 可把永久 Run/Debug Configuration 存为项目文件；Eclipse 可把本地 launch 转成项目中的 Shared .launch；Visual Studio 的 launchSettings.json 或 open-folder launch.vs.json 也有共享入口；VS Code 使用 tasks.json 与 launch.json。共享前必须删除绝对路径、个人解释器位置和机器端口，把它们改为项目相对路径、宏、环境变量或本机覆盖。
跨 IDE 验证：共享运行契约，不复制配置语法
跨 IDE 验收不要求同一个 JSON 被四套产品读取，而要求同一个目标得到同一组证据。选择仓库里一条代表链路，在两种 IDE 中分别重建配置：
用同一 wrapper 和同一工作目录启动。传入相同的非敏感参数与环境变量名。请求同一个健康检查，记录相同响应。
在同一 commit 的同一源码行命中断点。记录实际协议、目标 PID、监听地址和映射后的源码路径。分别执行断开和停止，确认目标进程是否仍在。
在干净 clone 中重建，不依赖个人 IDE 缓存。
JVM 项目可在 VS Code 与 JetBrains/Eclipse 间交叉验证 JDWP attach；Node 项目可在 VS Code 与 JetBrains 间验证 Inspector；.NET/C++ 项目由 Visual Studio 作为主验证端，再用 CLI 证明 run 契约。产品能力不对等时，不为了“全 IDE 通过”引入不成熟适配器。
真实项目接入：从一键按钮退回可解释链路
以“前端 watch + 后端服务 + 浏览器调试”为例，团队配置应明确四个阶段：构建任务生成可调试制品；后台任务启动服务并以日志或健康检查宣告 ready；调试器 launch/attach 后端；浏览器配置等待 URL 可用后连接页面 target。每个阶段都有独立日志和清理动作。
不要把数据库迁移、生产数据修复或长时间基础设施启动藏在 preLaunchTask。这些动作失败会让调试器看似卡住，而且停止会话时无法判断是否应该回滚。适合自动执行的是幂等、快速、可取消的准备动作；有破坏性的动作需要显式命令与二次确认。
提效的重点也不是增加更多配置，而是减少漂移：统一 wrapper，固定相对工作目录，为后台任务提供 readiness，给复合配置命名，保留最小 launch/attach 两条基线。临时排障参数放个人配置，验证有效后再审查是否进入团队模板。
故障闭环：按会话层次排，不先删配置
调试器连不上端口
现象通常是 connection refused 或 timeout。先在目标侧确认进程和监听地址，再从 IDE 所在位置检查网络可达性。refused 多半是未监听、进程已退或地址族错误；timeout 更像防火墙、隧道、容器映射或路由问题。修复后重新连接，并检查临时转发是否在结束时关闭。
已连接但断点不命中
先确认请求真的走到目标进程，再看断点是否已验证。核对 commit、制品时间、加载路径、source map、类调试信息和 path mapping。若断点绑定到同名旧文件，清缓存只能暂时遮住模型错误；应修正构建输出和映射来源。
preLaunchTask 一直转圈
检查后台任务是否有正确的 begins/ends pattern，日志文本是否变化，以及 task 是否在错误工作目录启动。先单独运行 task，看到 ready 证据后再接回 debug。不要用固定 sleep 代替 readiness，它在慢机器和 CI 上一定会漂移。
停止后端口仍被占用
记录目标 PID 和父子关系，判断它是 attach 目标、shell 派生进程、watcher 还是调试适配器遗漏的子进程。先用正常信号结束，再定向强制清理；不要按端口模糊批量杀进程。修复配置后重复“启动 -> 停止 -> 端口为空”验证。
断开导致共享服务退出
这是生命周期所有权错误。把配置改为 attach，并检查适配器是否支持 terminateDebuggee=false 一类能力；若产品无法保证语义，就禁止从 IDE 管理共享目标生命周期，只允许通过服务 owner 的控制面启动和停止。
架构取舍：本地 launch、远程 attach 还是临时环境
本地 launch 反馈最快、清理简单，适合单进程和大多数日常开发；代价是开发机运行时与目标环境可能漂移。容器或远程 launch 提高环境一致性，但路径、文件同步、网络和子进程所有权更复杂。attach 适合已经由 Compose、测试环境或服务管理器启动的目标，能保留真实启动方式，但必须治理端口和多人争用。
生产调试默认不应开放。更稳妥的顺序是日志、指标、trace、dump 和可重放测试；只有明确审批、最小权限、短时隧道、审计和回收条件都具备时，才考虑在线 attach。调试器暂停线程、执行表达式和读取内存都可能扩大事故，不能把“只看看”当作无副作用。
团队治理与落地工程深水区
团队应为每条共享配置指定 owner，记录适用 IDE/适配器版本、运行时版本、端口来源、变量契约、目标所有者、终止语义和最后验证日期。配置审查不能只看 JSON 是否能解析，还要实际做断点、请求、断开、停止和残留检查。
远程端口采用默认拒绝：只监听回环地址，通过短时隧道访问，不在镜像和部署清单里长期发布 JDWP、Inspector 或 CDP。隧道、临时浏览器 profile、调试 JVM 参数和测试 secret 都必须有清理动作。
共享配置只表达团队契约，个人机器差异放本地覆盖。任何需要真实凭证才能启动的配置，都只提交变量名和获取说明。诊断包在上传前检查环境变量、命令行、URL query、工作目录和进程列表，因为这些位置经常泄露秘密。
升级 IDE 或适配器时，先在代表仓库验证协议连接、source map、子进程和终止行为，再逐步推广。回滚不仅是安装旧扩展，还包括恢复旧配置 schema；因此配置变更要与最低 IDE/适配器版本一起评审。
终端 Run 不依赖 IDE 也能成功，并有明确预期结果。task 有正确工作目录、退出码和后台 readiness，不使用固定 sleep 冒充就绪。launch 与 attach 的目标所有权、断开和终止语义已实测。
JDWP、Inspector、CDP 只监听受控地址，临时隧道可回收。source map 和路径映射指向当前 commit 的真实制品。共享配置没有绝对个人路径、真实 secret、生产 URL 和长期开放端口。
至少两种适用 IDE 完成同一运行契约的交叉验证。停止后检查目标、子进程、端口、临时 profile 和日志残留。