VSCode 运行 Swift 依赖系统工具链和正确配置：需安装并配置 sourcekit-lsp、定义 tasks.json 构建任务、在含 Package.swift 的根目录打开项目；Windows 必须通过 WSL2 使用官方 Linux Swift 工具链。
VSCode 本身不运行 Swift 代码，它只调用系统级 swift 工具链执行构建和运行；没装好工具链、没配对 sourcekit-lsp、没打开正确项目结构，点“运行”按钮或按快捷键都只会静默失败。
sourcekit-lsp 启动失败，补全/跳转全失效
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 - VSCode 设置里必须手动填
swift.path.sourceKitLSP，值为绝对路径，不能用~，也不能含空格或中文 - 填完后重启 VSCode 或重载窗口（
Cmd+Shift+P→Developer: Reload Window）
点“运行”没反应，或提示 No build task defined
VSCode 不像 Xcode 那样自动识别 Swift 项目，它需要你明确定义“怎么构建”。没有 tasks.json，swift build 根本不会触发，.build/debug/ 目录就不存在，后续一切运行、调试都无从谈起。
- 确保项目根目录有
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）或Ctrl+Shift+B（Windows/Linux）调出任务选择器，选 “build” 手动触发一次 - 构建成功后，
.build/debug/YourTargetName才生成，这时才能用swift run或配置launch.json调试
Windows 下死活跑不起来
Swift 官方不支持 Windows 原生工具链，所有“Windows 版 Swift 安装包”均已停止维护，无法通过 swift test 或 swift run 验证。你在 PowerShell 里看到 swift --version 成功，大概率只是包装脚本，背后没有真实运行时。
- 唯一可行路径是 WSL2 + Ubuntu（推荐 24.04）+ 官方 Linux Swift 包（从
swift.org/download下载swift-5.9-RELEASE-ubuntu24.04.tar.gz） - 解压到
/opt/swift，并在~/.bashrc中追加：export PATH="/opt/swift/usr/bin:$PATH"，再source ~/.bashrc - VSCode 必须通过
Remote - WSL扩展打开项目（Ctrl+Shift+P→Remote-WSL: New Window），然后File > Open Folder选 WSL2 内路径（如~/my-swift-app） - Windows 文件系统路径（如
C:\myproject）下打开项目，插件完全不会激活
格式化或调试失败但其他功能正常
格式化依赖 swiftformat 可执行文件，调试依赖 lldb 和带调试符号的二进制——这两件事和 sourcekit-lsp 是解耦的，各自出问题互不影响。
- 格式化失效：确认
which swiftformat输出路径（M1/M2 Mac 通常是/opt/homebrew/bin/swiftformat），在 VSCode 设置中填完整绝对路径，不能写swiftformat或用~ - 调试断点灰色：
launch.json的program字段必须指向.build/debug/YourTargetName（不是源码路径，也不是swift run命令） - macOS 调试可用，Linux 上
lldb支持尚不稳定，Windows 原生不支持；iOS App 开发请直接用 Xcode，VSCode 不处理 UIKit/SwiftUI/模拟器启动等任何平台层逻辑
最容易被忽略的是：VSCode 从不自动发现项目上下文。你双击一个 main.swift 文件，它就真只当文本开；必须用 Open Folder 打开含 Package.swift 的根目录，等右下角状态栏显示 “Building workspace” 完成，整个语言服务才算真正就位。
