VSCode本身不运行Swift代码，仅调度命令，真正执行依赖系统级swift工具链；macOS可全流程支持，Windows原生不可用，唯一稳定路径是WSL2+Linux版Swift工具链。
VSCode 本身不运行 Swift 代码，它只调度命令；真正执行靠的是系统级 swift 工具链 —— macOS 能跑通全流程（编辑 → 构建 → 调试），Windows 原生支持仍是实验性，目前唯一稳定路径是 WSL2。
macOS 上 swift 命令在 VSCode 终端里报 command not found
这不是 VSCode 的问题，而是终端环境没加载 Xcode 自带的 Swift 路径。Xcode 安装后，swift 默认位于 /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift，但该路径不会自动进 shell 的 PATH，尤其 VSCode 从 Dock 启动时更常丢失 ~/.zshrc 配置。
- 先在系统终端里运行
which swift和swift --version，确认命令可用 - 如果系统终端能用、VSCode 集成终端不行，说明它没读取你的 shell 配置；可在 VSCode 设置中加环境变量：
"terminal.integrated.env.osx": { "PATH": "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:${env:PATH}" } - 更稳妥的做法：用
swiftenv管理多版本，或从swift.org下载独立 toolchain 安装到/Library/Developer/Toolchains/，再软链进/usr/local/bin
Windows 上点“运行”没反应，或提示 No build task defined
VSCode 不识别单个 .swift 文件为可运行上下文，也不自动触发构建 —— 它需要明确的 SPM 项目结构和 tasks.json 定义。Windows 原生安装的 Swift 工具链（哪怕 swift --version 成功）大概率只是包装脚本，背后没有完整运行时，swift run 和 sourcekit-lsp 必然失败。
- 必须用 WSL2（Ubuntu 24.04 推荐），在其中安装官方 Linux 版 Swift 工具链（如
swift-5.9-RELEASE-ubuntu24.04.tar.gz），解压到/opt/swift，并把/opt/swift/usr/bin加进~/.bashrc的PATH - VSCode 必须通过
Remote - WSL扩展打开项目（路径必须是 WSL2 内部路径，如~/myproject），不能打开 Windows 文件系统路径（如C:\myproject） - 项目根目录必须有
Package.swift（用swift package init --type=executable创建），然后在.vscode/tasks.json中定义构建任务："command": "swift build"，否则按Cmd+Shift+B或Ctrl+Shift+B都无效
sourcekit-lsp 启动失败，补全/跳转全失效
VSCode 的 Swift 插件（如 sschmid.Swift）不自带语言服务器，它只转发请求给系统级 sourcekit-lsp 进程 —— 这个二进制不可执行，插件就退化为纯文本编辑器。
- 先在终端里直接运行
sourcekit-lsp --help：macOS 上常见路径是/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/sourcekit-lsp，WSL2 上是/opt/swift/usr/bin/sourcekit-lsp；失败则说明路径错、权限不足或工具链不完整 - VSCode 设置中必须显式填写
swift.path.sourceKitLSP（不是留空，也不是依赖自动发现），例如：/Library/Developer/Toolchains/swift-5.9-RELEASE.xctoolchain/usr/bin/sourcekit-lsp - 打开项目必须是含
Package.swift的文件夹（用File > Open Folder），不能双击打开单个main.swift；否则sourcekit-lsp会静默退出并报no workspace
调试断点灰色、变量显示 <error type></error>
调试失败几乎都源于构建产物路径与 launch.json 不匹配，或构建未成功生成可执行文件。
-
launch.json中的program字段必须指向真实存在的二进制，通常是.build/debug/YourTargetName（macOS）或.build/x86_64-unknown-linux-gnu/debug/YourTargetName（WSL2） - 务必配置
preLaunchTask指向build任务，并确保该任务执行成功（即.build/debug/目录已生成） - 不要用
swiftc main.swift编译单文件去调试 —— CodeLLDB 只支持 SPM 构建出的带调试符号的二进制，且需对应平台的 LLDB 版本
最易被忽略的一点：WSL2 下 VSCode 的 PATH 继承不可靠，即使你在终端里 source ~/.bashrc 生效了，VSCode Remote 启动时仍可能丢掉它；每次更新工具链路径后，都要重启 VSCode 窗口并确认右下角状态栏显示 “WSL: Ubuntu”。
