SourceKit-LSP 配置失败导致 VSCode 丧失跳转、补全、诊断功能，根本原因是 language server 未连上；需手动配置 swift.sourcekit-lsp.path 为绝对路径，并确保 Swift 工具链已安装、项目以文件夹形式打开且已成功构建。
SourceKit-LSP 配置失败，VSCode 就只是个带语法高亮的文本编辑器——跳转、补全、诊断全挂，不是插件没装好，而是 language server 根本没连上。
sourcekit-lsp --help 报 command not found 怎么办
这一步卡住，后面所有配置都白搭。VSCode 的 Swift 插件（比如 sschmid.Swift）不自带 sourcekit-lsp，它只负责转发请求；真正干活的是你系统里那个二进制。
- 先确认 Swift 工具链已安装：
swift --version和swift build --version都要有输出 - 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：解压官方 Swift 包后，通常在
/opt/swift/usr/bin/sourcekit-lsp；记得把该目录加进~/.bashrc的PATH并source ~/.bashrc - Windows 原生不支持，必须用 WSL2，且 VSCode 必须通过
Remote - WSL扩展启动项目，否则PATH不继承
VSCode 里 swift.path.sourceKitLSP 必须手动填绝对路径
自动探测在 macOS、WSL2 或多工具链环境下基本不可靠，留空或填错路径等于没配。
- 打开设置（
Cmd+,/Ctrl+,），搜索swift.sourcekit-lsp.path，填入完整绝对路径，例如：/Library/Developer/Toolchains/swift-5.9-RELEASE.xctoolchain/usr/bin/sourcekit-lsp - 别用
~代换，VSCode 解析可能出错；路径中不能有空格或中文 - 如果同时装了 Xcode 和独立 toolchain，确保填的路径和终端里
swift --version输出的版本一致 - 顺手关掉设置项
Editor: Suggest: Snippets Prevent Quick Suggestions，否则补全响应极慢甚至卡死
打开单个 .swift 文件 vs 打开含 Package.swift 的文件夹
sourcekit-lsp 启动后静默退出、提示 no workspace 或 unable to resolve package，90% 是因为双击打开了一个 main.swift，而不是用 File > Open Folder 打开 SwiftPM 项目根目录。
- 终端进空目录，运行
swift package init --type=executable初始化标准结构 - VSCode 必须打开这个根目录（即包含
Package.swift、Sources/、Tests/的文件夹） - 首次打开后，等右下角状态栏出现
Building workspace并完成——这步会触发swift build --generate-diagnostics，生成.build/debug/dependencies等必要元数据 - 如果项目是 Xcode 工程（
.xcodeproj），VSCode 无法复用其索引，必须转为 SwiftPM 结构，或提前运行xcodebuild -resolvePackageDependencies
改完 Package.swift 后补全延迟或失效
sourcekit-lsp 不会自动重载项目配置，它依赖 swift package resolve 生成的 .build 元数据。手动改完 Package.swift，不触发解析，LSP 就继续用旧缓存。
- 终端进项目根目录，运行
swift package resolve（或swift package update）刷新依赖 - VSCode 右下角状态栏若显示
SourceKit-LSP Active但补全仍不对，可尝试命令面板执行Swift: Restart Language Server - Linux 下还需注意
LD_LIBRARY_PATH：运行swift build前，先执行export LD_LIBRARY_PATH="/path/to/swift/usr/lib/swift/linux:$LD_LIBRARY_PATH"，否则swift test可能报unable to load standard library
最常被忽略的点是：sourcekit-lsp 跑起来了，但项目没构建过，或者构建失败了——LSP 会静默降级，看起来“能用”，实际跳转指向错误位置、诊断漏报。务必确认 .build/debug/ 目录存在且非空。
