VSCode写Swift核心卡点是sourcekit-lsp能否运行：终端执行sourcekit-lsp --help有输出才有效，否则补全、跳转、诊断全失效；必须手动配置VSCode中swift.path.sourceKitLSP为绝对路径，打开含Package.swift的SwiftPM根目录，调试需用debug模式构建并正确指向.build/debug/二进制。
VSCode 写 Swift 不是装个插件就能用，核心卡点永远在 sourcekit-lsp 能不能真正跑起来——它一挂，补全、跳转、诊断全失效，VSCode 就只剩语法高亮。
sourcekit-lsp 命令行跑不通，VSCode 配置再对也白搭
VSCode 的 Swift 插件（比如 sschmid.Swift）不带任何编译器或语言服务，只负责转发请求。它连不上 sourcekit-lsp 进程，就等于没后端。
- 先在终端执行
sourcekit-lsp --help：有帮助输出才说明二进制存在且可执行；报command not found就别调 VSCode 设置，先修 PATH 或路径本身 - macOS 常见路径：
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/sourcekit-lsp（需先sudo xcode-select -s /Applications/Xcode.app）；或 Homebrew 安装的路径如/opt/homebrew/bin/sourcekit-lsp - Linux/WSL2：解压官方包后通常在
/opt/swift/usr/bin/sourcekit-lsp；记得把该目录加进~/.bashrc的PATH，并source ~/.bashrc - Windows 原生无解——官方不提供 Windows 版
sourcekit-lsp，必须走 WSL2，且 VSCode 要通过Remote - WSL打开项目，否则插件根本加载不了
VSCode 设置里必须手动填 sourcekit-lsp 路径，不能留空
VSCode 不会自动发现 sourcekit-lsp，尤其在 WSL2 或非标准安装路径下，环境变量继承不可靠，自动探测大概率失败。
- 打开设置（
Cmd+,/Ctrl+,），搜swift.path.sourceKitLSP，填绝对路径，例如：/opt/swift/usr/bin/sourcekit-lsp - 别用
~代换，VSCode 解析可能出错；路径中不能有空格或中文 - 如果用了多个 Swift 工具链（比如同时装了 Xcode 和独立 toolchain），确保填的路径和你终端里
swift --version对应的那套一致 - 顺手关掉设置项
Editor: Suggest: Snippets Prevent Quick Suggestions，否则补全响应极慢甚至卡死
打开项目必须是 SwiftPM 根目录，不是 .swift 文件
sourcekit-lsp 启动后静默退出、提示 no workspace 或 unable to resolve package，90% 是因为双击打开了单个 main.swift，而不是用 File > Open Folder 打开含 Package.swift 的文件夹。
- 终端进空目录，运行
swift package init --type=executable初始化标准结构 - VSCode 必须打开这个根目录（即包含
Package.swift、Sources/、Tests/的文件夹），不是里面某个子目录 - 首次打开后右下角会显示
Building workspace，这是swift build --generate-diagnostics在后台运行；等它完成，符号索引才真正可用 - 别指望
.xcodeproj或.swiftpm被识别——Swift 插件只认Package.swift和 SPM 元数据
调试失败基本都卡在构建模式或 launch.json 路径上
断点灰色、变量显示 <error type></error>、控制台报 no debug adapter，本质是调试器找不到带调试符号的二进制。
- 构建必须用
swift build --configuration debug（默认就是 debug，但脚本或 CI 可能覆盖）；release模式会优化掉符号，断点必然无效 -
.vscode/launch.json中program字段必须指向真实可执行文件，例如："${workspaceFolder}/.build/debug/MyApp"，不能是源码路径，也不能写成swift run MyApp - macOS 可调试命令行程序；Linux 上
lldb支持不稳定，需额外装匹配版本（如lldb-16）并配置"lldb.executable": "/usr/bin/lldb-16"；Windows（WSL2）调试支持仍属实验性，不建议强依赖 - 调试前手动运行一次
swift build，确认.build/debug/下已有对应二进制，避免 launch.json 指向空目录
最常被忽略的是：修改 Package.swift 或添加新依赖后，sourcekit-lsp 不会自动重载，必须手动运行 swift package resolve，否则补全和跳转会延迟甚至错乱。这不是 VSCode 的 bug，是 SPM 构建元数据未更新导致的底层行为。
