必须通过 wsl 终端执行 code . 或使用 vscode 的“wsl: new window”命令启动，才能使后端进程运行在 wsl 中，确保 linux 权限、git hooks、调试器及路径语义正常工作；仅在 windows 中打开 /home/xxx/project 路径仍运行于 windows 上下文，导致 chmod 静默失败、hooks 不触发等问题。

直接在 Windows 上双击打开 VSCode，再点“打开文件夹”选 `/home/xxx/project` —— 这**不是**真正接入 WSL，所有操作仍在 Windows 层跑。必须让 VSCode 后端进程运行在 WSL 里，才能用上 Linux 权限、git hooks、调试器和真实路径语义。

code . 必须在 WSL 终端里执行

这是唯一能触发 Remote-WSL 完整上下文的方式。Windows 版 VSCode 进程默认绑定 Windows 用户空间，哪怕你打开的是 /home/user/app 这种路径，只要没从 WSL 启动，chmod 就会静默失败，git commit 不触发 hooks，node_modules 权限混乱也全由此而起。

• 先在 WSL 终端（如 Ubuntu）中 cd ~/projects/myapp
• 确保已注册 code 命令：在 Windows 端 VSCode 中按 Ctrl+Shift+P → 输入 Shell Command: Install 'code' command in PATH，然后执行 wsl --shutdown 重启 WSL
• 运行 code .，新窗口左下角出现绿色 WSL 图标，终端提示符变成 user@hostname:~$，才算成功
• 如果 which code 报错，手动加一行到 ~/.bashrc：export PATH="$PATH:/mnt/c/Users/xxx/AppData/Local/Programs/Microsoft VS Code/bin"（路径按你实际安装位置调整）

WSL: New Window 有时不生效的真正原因

这个命令依赖 VSCode 能检测到一个“可用且正在运行”的 WSL2 发行版。它不是插件没装的问题，而是环境状态不对。

Zynq Linux Hardware Debug

Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。

下载

• wsl -l -v 显示状态为 Stopped？很可能是 WSL2 内核过旧，需手动下载安装 wsl_update_x64.msi
• 发行版名不是 Ubuntu 或 Debian（比如叫 Ubuntu-22.04-custom），Remote-WSL 默认只扫描白名单名；可运行 wsl --set-default Ubuntu-22.04 修复
• VSCode 是从 Windows 资源管理器右键打开的，根本没加载 Remote-WSL 上下文；务必用 Ctrl+Shift+P → WSL: New Window 启动
• 插件被工作区禁用，或你装的是 Microsoft Store 版 VSCode（权限受限），请卸载后从官网下载 VSCodeUserSetup-x64.exe 重装

调试 C/C++ 时 “Unable to start debugging. Unexpected GDB output”

这不是 GDB 崩了，是路径或权限错位导致的典型报错。GDB 在 WSL 里运行，但你给的 program 路径如果指向 /mnt/c/，它会读取失败或拒绝加载符号表。

• "program" 必须填 WSL 绝对路径，如 "/home/user/myproj/build/app"，不能是 "./build/app"（相对路径在远程调试中不可靠）
• "cwd" 必须是 WSL 中真实存在的目录，且当前用户有执行权限
• 确认已安装 gdb：sudo apt install gdb，别指望 Windows 的 gdb.exe 能跨系统调用
• 项目代码必须放在 /home/xxx 下，/mnt/c/ 下的文件无法正确设置断点或读取符号表

终端里 Ctrl+C 不中断 Python 脚本

这是 WSL2 + VSCode 集成终端的信号转发缺陷，尤其在 zsh 下高频出现。不是你的脚本问题，也不是 stty 或 trap 能修的。

• 在 VSCode 设置里搜索 terminal.integrated.defaultProfile.linux
• 把它设为 bash（而非默认的 zsh 或空值）
• 重启集成终端，或执行 Ctrl+Shift+P → Terminal: Select Default Profile → bash
• 根本原因是 WSL2 的 zsh 在 VSCode 终端中对 pty 信号处理不够稳定；bash 更保守，兼容性更好

真正卡住人的地方，往往不是“怎么连”，而是“以为连上了”。WSL 图标出现在左下角 ≠ 后端进程已在 Linux 中运行——只有 code . 从 WSL 终端发起，或 WSL: New Window 成功唤起并显示对应发行版名，才代表调试器、终端、Git、文件权限全部走的是同一套 Linux 上下文。任何一步绕开这个入口，后续所有问题都会变成“玄学”。