能直接在VSCode里调试K3s集群Pod，前提是容器暴露调试端口、VSCode连上集群且调试器穿透到进程；K3s轻量特性使端口转发和权限问题更敏感，需确保kubectl/kubeconfig就绪、容器配置语言特定调试参数、VSCode通过端口转发+launch.json attach调试，而debugd架构在K3s中因containerd限制基本不可用。
能直接在 VSCode 里调试 K3s 集群里的 Pod，前提是容器启动时暴露了调试端口、VSCode 能连上集群、且调试器能穿透到容器进程——三者缺一不可。K3s 本身不改变调试逻辑，但它的轻量特性会让端口转发和权限问题更敏感。
确认 kubectl 和 kubeconfig 已就绪
VSCode Kubernetes 插件启动时硬检查 kubectl 和 ~/.kube/config，不认 KUBECONFIG 环境变量拼接，也不 fallback 到其他路径。
- 终端运行
kubectl version --client，必须返回版本号（≥1.18）；否则插件直接报错退出 - 运行
kubectl config current-context，输出必须是你的 K3s 上下文名（如k3s或default） - 运行
kubectl get nodes -A，必须成功返回节点列表；若报Unable to connect to the server，插件必然连不上 -
ls -l ~/.kube/config确保当前用户有读权限；Windows 上注意文件是否被标记为“来自互联网”而被拦截
让 Pod 容器支持远程调试
容器得自己开调试通道，K3s 不帮你做这件事。不同语言的启动参数差异大，别复用旧配置。
- Java：在 Deployment YAML 的
env中加JAVA_TOOL_OPTIONS: "-Xdebug -agentlib:jdwp=transport=dt_socket,address=0.0.0.0:5005,server=y,suspend=n"，并确保containerPort: 5005已声明 - Node.js：启动命令改成
node --inspect=0.0.0.0:9229 app.js，YAML 中对应加ports和securityContext（避免因非 root 用户无法绑定端口） - Go：用
dlv exec启动二进制，并暴露dlv的 gRPC 端口（默认 2345），注意镜像里得预装delve - 所有语言都需确认容器内有
sh或bash，否则Exec into Container会失败
VSCode 端口转发 + launch.json 配置
VSCode 2026 改用 Unix Domain Socket 调试，但 K3s 场景仍普遍依赖传统端口转发——因为 debugd 守护进程默认不启用，且 K3s 的 containerd-shim 对其支持不稳定。
- 右键 Pod →
Forward Port，把容器调试端口映射到本地（如5005 → 5005） - 在项目根目录建
.vscode/launch.json，写明type（java/node/go）、port（填本地映射端口）、host（填localhost） - Java 示例配置中
vmArgs不要重复写-agentlib，那部分已在容器里生效，VSCode 只负责 attach - Node.js 的
address必须是0.0.0.0，不能是127.0.0.1，否则容器内无法被转发流量访问
常见卡点与绕过方式
最常卡在“资源树为空”或“右键没菜单”，本质都是连接未真正建立，不是插件坏了。
- 插件右下角状态栏没显示
k8s-context: k3s？说明没执行过Kubernetes: Connect to Cluster命令——仅切 context 不触发连接 - 点了
Connect to Cluster还是转圈？检查kubectl auth can-i list pods -A是否返回yes；K3s 默认 RBAC 较宽松，但若手动改过ServiceAccount权限，可能被拒 - 端口转发后调试连不上？用
kubectl port-forward pod/<pod-name> 5005:5005</pod-name>手动跑一次，看是否报error: unable to forward port—— 常见于容器进程未监听或防火墙拦截 - 断点命中但变量全
undefined？Java 需确认 jar 包含调试符号（maven-compiler-plugin开debug）；Node.js 需源码和 sourcemap 在同一容器路径下
K3s 的 containerd 默认不挂载 /run/containerd 到容器，所以 VSCode 2026 新的 debugd 架构在 K3s 上基本不可用；老老实实用端口转发+attach 模式，反而最稳。
