必须先在终端执行sourcekit-lsp --help验证可执行性，报command not found则说明路径未配置或工具链缺失，需修复PATH或确认Swift工具链安装；VSCode中须手动配置swift.path.sourceKitLSP为绝对路径，且项目必须以含Package.swift的文件夹形式打开。
VSCode 本身不运行 Swift 代码，它只调度系统级 swift 工具链；没装对、路径不对、项目结构不对，点“运行”按钮必然没反应——这不是插件问题，是底层执行链断了。
sourcekit-lsp --help 报 command not found 怎么办
这是最前置的失败点。VSCode 的 Swift 插件（比如 sschmid.Swift）不带任何二进制，全靠你本地的 sourcekit-lsp 进程提供语义支持。它挂了，补全、跳转、诊断全失效，只剩语法高亮。
- 先在终端直接运行
sourcekit-lsp --help：有帮助输出说明存在且可执行；报command not found就别调 VSCode 设置，先修环境 - 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 原生无
sourcekit-lsp—— 必须用 WSL2，且 VSCode 要通过Remote - WSL打开项目
VSCode 设置里 swift.path.sourceKitLSP 填什么
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，否则补全响应极慢甚至卡死
点“运行”没反应，或提示 No build task defined
VSCode 不像 Xcode 那样自动识别 Swift 项目。它需要你明确告诉它“怎么构建”，否则连 swift build 都不会触发。
- 确保项目根目录有
Package.swift（用swift package init --type=executable创建） - 在
.vscode/tasks.json里定义构建任务，例如：
{
"version": "2.0.0",
"tasks": [
{
"label": "build",
"type": "shell",
"command": "swift build",
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false
}
}
]
}- 按
Cmd+Shift+B（macOS）调出任务选择器，选 “build” 手动触发一次；成功后.build/debug/YourTarget才存在，后续才能调试 - 别依赖 CodeRunner 插件跑单文件——
swift run必须在 SPM 项目上下文中才有效，直接swift main.swift只适用于极简脚本，且无法 debug
Windows 下为什么死活配不起来
Swift 官方从不发布 Windows 原生工具链，所有“Windows Swift 安装包”均已停止维护。你在 PowerShell 中运行 swift --version 成功，大概率只是符号链接或包装脚本，背后没真正 Swift 运行时。
- 唯一可行路径是 WSL2 + Linux Swift 工具链：安装 WSL2，Ubuntu 24.04 推荐；下载
swift-5.9-RELEASE-ubuntu24.04.tar.gz，解压到/opt/swift - 配置
PATH：向~/.bashrc追加export PATH="/opt/swift/usr/bin:$PATH"，然后source ~/.bashrc - VSCode 必须通过
Remote - WSL打开项目——不能在 Windows 文件系统（如C:\myproject）里打开 Swift 项目并指望插件工作 - 验证：在 WSL2 终端中运行
swift --version和sourcekit-lsp --help，两者都应正常输出
最容易被忽略的是：VSCode 必须打开含 Package.swift 的文件夹，而不是单个 .swift 文件；sourcekit-lsp 启动后静默退出，90% 是因为这个原因。另外，launch.json 里的 program 字段必须指向 .build/debug/xxx 下的真实二进制，不是源码路径，也不是 swift run 命令。
