sourcekit-lsp启动失败导致VSCode丧失补全、跳转等语言功能；需确认其可执行性（sourcekit-lsp --help）、显式配置绝对路径至swift.path.sourceKitLSP、打开含Package.swift的根目录，并确保swift与sourcekit-lsp来自同一工具链。
sourcekit-lsp 启动失败导致无提示、无跳转
VSCode 的 Swift 插件（如 Swift for VS Code）本身不带语言服务，全靠 sourcekit-lsp 进程提供语义分析。它一挂，编辑器就退化成纯文本编辑器——补全消失、Cmd+Click 报 “No definition found”，连语法错误都不标红。
常见现象包括：打开项目后右下角状态栏不显示 “Building workspace”，或刚打开就闪退；终端里运行 sourcekit-lsp --help 报 command not found 或 cannot open shared object file。
- 确认
sourcekit-lsp在 PATH 中：执行which sourcekit-lsp，若为空，说明 Swift 工具链未正确安装或路径没进 shell 配置 - VSCode 设置里必须手动填
swift.path.sourceKitLSP，值为绝对路径（例如/opt/swift/usr/bin/sourcekit-lsp），不能用~，也不能依赖自动探测 - 确保你用的是官方
.tar.gz包解压安装的 Swift（非 Snap），否则沙盒会阻断sourcekit-lsp访问系统库 - 首次打开项目时，务必用
File > Open Folder打开含Package.swift的根目录，不是单个.swift文件
Linux 下 swift build 或 swift test 报 “unable to load standard library”
这是典型的动态链接失败，和 macOS 不同，Linux 没有系统级 Swift 运行时注册机制。swift --version 能跑，只说明二进制可执行；但 swift build 需要加载 libswiftCore.so 等共享库，而 ldd 默认找不到它们。
错误常出现在 VSCode 集成终端里，即使你在 shell 中设了 LD_LIBRARY_PATH，VSCode 启动时可能没继承该变量。
- 先查 Swift 安装路径：
swift --version输出后，运行swift --show-sdk-path，再结合路径推导库位置，通常是/opt/swift/usr/lib/swift/linux - 在
~/.bashrc或~/.profile中添加：export LD_LIBRARY_PATH="/opt/swift/usr/lib/swift/linux:$LD_LIBRARY_PATH"，然后source ~/.bashrc - VSCode 启动前需从已 source 过的终端启动（如
code .），否则集成终端仍无该变量；远程开发时更需在 WSL2 或远程服务器的 shell 配置中统一设置 - 避免混用多个 Swift 版本：如果同时装了 Homebrew 和官方包，确保
swift和sourcekit-lsp来自同一套工具链
调试时断点不命中、变量显示 <error type></error>
VSCode 无法直接调试 Swift 源码，它依赖 LLDB 加载调试符号（dSYM 或 DWARF），而 Swift 默认构建的 release 产物不含完整调试信息，且 Linux 上的 LLDB 版本必须与 Swift 工具链 ABI 兼容。
现象包括：断点灰色不可用、hover 变量显示 error、控制台报 “no debug adapter” 或 “Failed to launch”。
- 构建必须用
swift build --configuration debug（默认就是 debug，但 CI 脚本或自定义 task 可能覆盖） -
launch.json中program字段必须指向.build/debug/your-executable-name，不能写swift run命令或源码路径 - Ubuntu/Debian 系需安装匹配版本的 LLDB：Swift 5.9 推荐
lldb-16或lldb-18，运行sudo apt install lldb-16，并在设置中指定"lldb.executable": "/usr/bin/lldb-16" - 确保
CodeLLDB扩展已启用，且项目根目录下有.vscode/launch.json，内容包含"type": "lldb"和正确cwd
修改 Package.swift 后提示延迟或类型解析错乱
sourcekit-lsp 不监听文件系统变化，也不会自动重载 SwiftPM 配置。它完全依赖 .build 目录下的元数据（如 .build/checkouts、.build/dependencies）来解析 import 和模块依赖。
改完 Package.swift（比如加了个 dependency 或改了 Swift 版本），VSCode 不会立刻更新提示，甚至出现 “Cannot find ‘SomeType’ in scope” 这类误报。
- 必须手动触发
swift package resolve，让 SwiftPM 重新拉取依赖并生成新元数据 - 推荐在终端执行该命令后，点击 VSCode 右下角 “Restart Language Server” 按钮（或按
Cmd+Shift+P> “SourceKit-LSP: Restart”） - 不要删
.build目录后直接等自动重建——VSCode 不会主动触发swift build，得手动运行一次构建任务或等编辑器后台静默构建完成 - 若项目含
plugins（如swift-format），确保插件也已 resolve，否则sourcekit-lsp可能因插件缺失而降级功能
export LD_LIBRARY_PATH 了，但双击图标启动 VSCode，它根本看不到这个变量；又比如你设了正确的 sourcekit-lsp 路径，但 swift --version 指向另一套旧工具链，LSP 就会静默失败。这些细节不报错，却让整个开发流瘫痪。 
