# 开发环境配置

> 适用于 2026 iOS 部国庆考核。最后核对：2026-10-02。软件版本更新很快，遇到与本文不一致的界面或报错，保留截图在 QQ 群求助。

## 先看结论：我需要装什么？

第一题需要能运行 **Swift 命令行程序**，并能**在终端里输入**：不需要 Mac，也不需要 Xcode，但需要一台电脑，iPad 不行。第三题要做 iOS App，才需要 Xcode（Mac）或 Swift Playground（iPad）。

| 我的设备 | 第一题（命令行 Swift） | 第三题（SwiftUI App，选做） |
| --- | --- | --- |
| **Windows 电脑** | Swift 工具链 + VS Code（见下文 Windows 部分） | 无法开发 iOS App；可用 iPad 或借用 Mac |
| **Mac，Apple 芯片（M 系列），系统 macOS Tahoe 26.6 及以上** | Command Line Tools 或 Xcode 27 + VS Code / 终端 | Xcode 27 |
| **Mac，Intel 芯片或系统较旧** | Command Line Tools（能装上即可） | 按下表选择与系统匹配的旧版 Xcode |
| **iPad（iPadOS 18 及以上）** | **不适用**：Swift Playground 无法在控制台输入 | Swift Playground 可以写 SwiftUI App |
| **Linux** | 官方 Swift 工具链（swiftly）+ VS Code | 无法开发 iOS App |

第一题只用到数组、循环、判断、函数、`print` 和 `readLine()`，都属于 Swift 标准库，在 Windows、macOS、Linux 上结果一致。本文示例程序已在 Swift 6.4（Linux）实际运行通过。

## 通用：安装 VS Code 与 Swift 扩展

Windows、Mac、Linux 都可以用 VS Code 写代码：

1. 从 [code.visualstudio.com](https://code.visualstudio.com/) 下载安装 VS Code。
2. 先按下文装好对应系统的 Swift 工具链。
3. 打开 VS Code，左侧点“扩展”，搜索 **Swift**，安装发布者为 **swiftlang** 的官方扩展（ID：`swiftlang.swift-vscode`）。
4. 新建一个文件夹，在 VS Code 中“打开文件夹”，新建 `main.swift`。**文件夹放在纯英文、无空格的路径下**，例如 Windows 的 `C:\swift\hello`、Mac 的 `~/swift/hello`。
5. 用菜单“终端 → 新建终端”，在下方终端里编译运行（命令见各系统部分）。

扩展主要为带 `Package.swift` 的项目提供完整功能；对单个 `main.swift`，它负责语法高亮和基础提示，**编译运行一律在终端里完成**，不用点 VS Code 的“运行”按钮。第一题要求文件名为 `main.swift`；文件夹里只放这一个 `.swift` 文件，一起编译多个文件时会报 `expressions are not allowed at the top level`。**第一题禁止使用 AI 写代码或排错**：如果 VS Code 装了 Copilot 等 AI 插件，做第一题时请关闭。

## Windows：Swift 工具链 + VS Code（首选）

按 [Swift 官方 Windows 安装说明](https://www.swift.org/install/windows/)（当前为 Swift 6.4）：

1. 以管理员身份打开“终端”或 PowerShell。
2. 安装依赖（Visual Studio 2022 的 C++ 组件和 Windows SDK，体积较大，需要一些时间）：

   ```powershell
   winget install --id Microsoft.VisualStudio.2022.Community --exact --force --custom "--add Microsoft.VisualStudio.Component.Windows11SDK.22621 --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.VC.Tools.ARM64" --source winget
   ```

3. 安装 Swift 工具链：

   ```powershell
   winget install --id Swift.Toolchain -e --source winget
   ```

4. **关闭并重新打开终端**（必要时重启电脑），运行 `swift --version`，看到版本号即安装成功。
   - 不想用 winget 时，也可以从 [Swift 官方下载页](https://www.swift.org/install/windows/) 下载安装包（`swift-6.4.0-RELEASE-windows10.exe`），但需要先按[手动安装说明](https://www.swift.org/install/windows/manual/)装好 Visual Studio 组件。
   - winget 会按电脑的架构自动选择安装包：常见的 Intel / AMD 电脑（x86_64）装 x64 版，骁龙等 ARM 芯片笔记本装 arm64 版，无需手动区分。只有手动下载安装包时才要选对版本，装错会在编译时报 `msvcrt.lib` 相关错误。
5. 在 VS Code 终端中进入 `main.swift` 所在文件夹，编译并运行：

   ```powershell
   cd C:\swift\hello
   swiftc main.swift -o main.exe
   .\main.exe
   ```

Windows 上请用 `swiftc` 先编译再运行，不要用 `swift main.swift` 直接运行（在 Windows 上不稳定）。

> 以上步骤来自 Swift 官方文档与官方论坛；Windows 实机效果以群内通知为准。

## Mac

先查看芯片和系统版本：左上角苹果菜单 →“关于本机”。

### 只做第一题：Command Line Tools（体积小）

在“终端”运行：

```bash
xcode-select --install
```

按弹窗提示安装（约 2 GB，同时会装好 `git`）。运行 `xcode-select -p` 能看到路径即已安装。完成后进入 `main.swift` 所在文件夹运行：

```bash
swift main.swift
```

也可以先编译再运行：`swiftc main.swift -o main && ./main`。

### 做第三题：Xcode

- **Apple 芯片 + macOS Tahoe 26.6 及以上**：从 Mac App Store 安装最新的 Xcode 27（Swift 6.4）。Xcode 27 只能在 Apple 芯片的 Mac 上安装。
- **Intel 芯片或系统较旧**：从 [Apple 开发者下载页](https://developer.apple.com/download/all/)（需登录 Apple 账号）下载与系统匹配的旧版本：

  | 你的 macOS | 可用的 Xcode | Swift |
  | --- | --- | --- |
  | Tahoe 26.2 及以上 | Xcode 26.6 | 6.3 |
  | Sequoia 15.6 及以上 | Xcode 26.3 | 6.2 |
  | Sonoma 14.5 及以上 | Xcode 16.2 | 6.0 |

  以上依据 [Apple Xcode 支持页](https://developer.apple.com/support/xcode/)。这些版本都足够完成国庆考核。
- Xcode 本体与 iOS 模拟器是**分开下载**的：第一次打开 Xcode 时按提示下载 iOS 平台组件。整体建议预留 **30 GB 以上**磁盘空间，大型下载不要等到截止前再开始。

## iPad：Swift Playground

**第一题不能用 iPad 完成**：第一题要求从控制台输入，而 Swift Playground 的控制台只能显示输出，不能输入。只有 iPad 的同学，请尽快在招新 QQ 群联系干部协调电脑。

Swift Playground 可以用来练习语法和做第三题：

1. 在 App Store 安装 **Swift Playground**（需要 iPadOS 18 及以上）。
2. 练习语法：在欢迎页点 **“新建 Playground”**，选择 **Book（游乐场书）**，写代码后点击 **“运行我的代码”**，在 **控制台**查看 `print` 的输出。
3. 做第三题：选择 **App** 模板，用 SwiftUI 开发。

## 在线运行器（仅作临时备用）

装好环境之前，可以用 [菜鸟教程在线运行](https://www.runoob.com/try/runcode.php?filename=HelloWorld&type=swift) 等网页临时练习语法。第一题提交的运行截图请使用上述本机环境，在线运行器仅供学习练习。

## 验证安装：运行第一个程序

把下面内容保存为 `main.swift` 并运行：

```swift
let items = ["校园卡", "钥匙", "水杯"]
var packed = ["校园卡"]
packed.append("钥匙")

print("需要带：\(items.joined(separator: "、"))，共 \(items.count) 件")
for item in items {
    if packed.contains(item) {
        print("✓ \(item)")
    } else {
        print("✗ 还缺 \(item)")
    }
}
```

看到下面的输出，环境就可以用了：

```text
需要带：校园卡、钥匙、水杯，共 3 件
✓ 校园卡
✓ 钥匙
✗ 还缺 水杯
```

这段代码只用来验证环境，不是第一题的答案。

### 再验证一下控制台输入

第一题要从控制台输入中文，建议同时验证这一点。把 `main.swift` 换成下面的内容，运行后输入“水杯”并回车：

```swift
print("请输入一个物品：", terminator: "")
if let text = readLine() {
    print("你输入的是：\(text)，共 \(text.count) 个字")
}
```

看到 `你输入的是：水杯，共 2 个字`，说明输入正常。如果显示乱码、问号或字数不对，见下方“常见报错”。

## 常见报错

| 报错或现象 | 原因与处理 |
| --- | --- |
| `'swiftc' 不是内部或外部命令`、`command not found: swift` | 装完没重开终端；重开终端或重启电脑。Mac 运行 `xcode-select --install` |
| 编译时报 `msvcrt.lib`、`link` 相关错误 | Visual Studio 组件缺失，或 ARM 电脑装了 x64 版本；重新运行第 2 步的 winget 命令 |
| `unable to load standard library for target …` | Windows 用户名带空格（Swift 默认装在用户目录下）；在群里求助，干部协助处理 |
| `'stdint.h' file not found` | 电脑装了多个 Visual Studio；在开始菜单打开“x64 Native Tools Command Prompt for VS 2022”再编译 |
| `xcrun: error: invalid active developer path` | Mac 系统升级后命令行工具失效；重新运行 `xcode-select --install` |
| 提示需要同意 Xcode 许可 | 运行 `sudo xcodebuild -license`，按提示同意 |
| `expressions are not allowed at the top level` | 同时编译了多个 `.swift` 文件；文件夹里只保留 `main.swift`，编译时只写这一个文件名 |
| `no such module 'SwiftUI'` 或 `'UIKit'` | 第一题不需要这些框架；删掉 `import` 那一行 |
| 输入中文后显示乱码、问号，或程序认不出输入的物品 | Windows 先运行 `chcp 65001` 再运行程序；建议使用 Windows 终端（Windows Terminal）或 VS Code 内置终端。仍不行时，按第一题题面的说明把物品名称换成英文或拼音 |
| 中文输出乱码 | 确认 `main.swift` 以 UTF-8 保存（VS Code 右下角显示 `UTF-8`）；Windows 可先运行 `chcp 65001` 再运行程序 |
| 提示找不到 `winget` | 在 Microsoft Store 安装或更新“应用安装程序”（App Installer） |
| 下载很慢或失败 | 换网络（如校园网）重试，尽早开始，不要拖到最后 |

## 求助时请提供

- 设备、系统版本、正在走哪条路线；
- 执行的命令或操作，以及**完整的报错截图**；
- 已经试过哪些办法。