sourcekit-lsp 未正确配置导致 VSCode 缺失跳转、补全、诊断功能；需确保其可执行、显式配置路径、打开含 Package.swift 的文件夹，并在 macOS 下手写 launch.json 调试。
sourcekit-lsp 没跑起来，VSCode 就只是个带语法高亮的文本编辑器——装插件、开文件、写代码，这三步都对，但缺了语言服务器，跳转、补全、诊断全失效。
确认 sourcekit-lsp 能在终端直接执行
VSCode 的 Swift 插件（比如 sschmid.Swift）不自带编译器或语言服务，它只负责把请求转发给系统级的 sourcekit-lsp 进程。这个二进制必须能被终端识别，否则插件连连接都建立不了。
- macOS：若用
brew install --cask swift，路径常为/opt/homebrew/bin/sourcekit-lsp；若用 Xcode 自带工具链，先运行sudo xcode-select -s /Applications/Xcode.app，再查/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/sourcekit-lsp - Linux：解压官方 Swift 包后，
sourcekit-lsp通常在/opt/swift/usr/bin/sourcekit-lsp；运行sourcekit-lsp --help应输出帮助信息 - WSL2（Windows）：必须用 Ubuntu 镜像（如
swift:5.9-jammy），且 VSCode 要通过Remote - WSL扩展启动，否则 PATH 不继承 - 如果
sourcekit-lsp --help报 “command not found”，别急着调 VSCode 配置，先修复系统环境变量 —— 把对应usr/bin目录加进$PATH，并验证swift --version和swift build --version都有输出
swift.path.sourceKitLSP 必须显式配置，不能留空
VSCode 设置中必须显式填入 swift.path.sourceKitLSP，尤其在 WSL2 或自定义安装路径下，自动发现基本不可靠。
- 打开 VSCode 设置（
Cmd+,/Ctrl+,），搜索swift.sourcekit-lsp.path，填入绝对路径，例如：/Library/Developer/Toolchains/swift-5.9-RELEASE.xctoolchain/usr/bin/sourcekit-lsp - 务必关闭设置项
Editor: Suggest: Snippets Prevent Quick Suggestions，否则补全响应极慢甚至卡死 - 如果打开
.swift文件后无语法高亮或跳转失效，先在终端手动运行sourcekit-lsp --help—— 失败说明路径错或权限不足（常见于 macOS 上 SIP 限制或 Linux 上未设可执行位）
必须用 Open Folder 打开含 Package.swift 的根目录
sourcekit-lsp 启动后会静默退出，或者提示 “no workspace”“unable to resolve package”，大概率是因为你双击打开了一个 main.swift，而不是用 VSCode 的 File > Open Folder 打开含 Package.swift 的文件夹。
- 终端进入空文件夹，运行
swift package init --type=executable（或--type=library），确保生成标准结构：Package.swift、Sources/、Tests/ - 在 VSCode 中用
File > Open Folder打开该根目录（不是单个文件），首次打开时右下角状态栏会显示 “Building workspace” —— 这是swift build --generate-diagnostics在后台运行，等它完成，符号索引才真正可用 - 不要指望
.xcodeproj或.swiftpm能被识别 —— Swift 插件只认 SwiftPM 元数据；iOS App 项目若想获得基础支持，需在根目录手动放一个最小化Package.swift（仅声明 name 和 targets），但这无法解决 UIKit/CocoaPods 依赖的跳转问题
调试仅限 macOS 命令行程序，launch.json 必须手写
VSCode 不能直接调试 iOS App，更没法在 iPhone 上运行；Linux 上 lldb 支持不稳定，Windows 不支持；只有 macOS 下的纯 Swift 可执行文件（--type=executable）可调试，且依赖正确构建和 launch.json 配置。
- 构建必须用
swift build --configuration debug（release模式会优化掉符号，断点必然无效） - 在
.vscode/launch.json中显式指定program字段，例如："program": "${workspaceFolder}/.build/debug/MyApp"—— VSCode 不会自动识别 target 名称，也不能用swift run命令代替路径 - 若断点灰色、变量显示
<error type></error>，先检查.build/debug/下是否存在对应二进制，再确认swift --show-sdk-path输出是否指向 Xcode SDK（错误指向 Command Line Tools 会导致调试符号加载失败）
sourcekit-lsp 的静默失败、Package.swift 的结构强依赖、launch.json 的路径硬编码 —— 这三个点最容易被跳过，但任一缺失都会导致整个环境“看起来能用，实际不能用”。
