跳到正文

← 全部工具

面向 iOS 和 Mac 开发者的免费工具

Xcode 和 Swift 项目起步文件

选好你的项目用到什么，就得到三份可以放进新仓库的文件：Xcode 和 Swift 的 .gitignore、新 Swift 包的 Package.swift，以及 Shared、Debug、Release 三个 .xcconfig。每一段上方都有一句理由，不想要的可以直接删掉。文件在你的浏览器里生成，不会上传。

忽略规则依据 github/gitignore（CC0-1.0）；Package.swift 的写法依据 Swift 的 PackageDescription（tools 版本 5.7 到 6.4）；构建设置名称来自 Apple 的 Build Settings reference。核对日期 2026-11-01。生成文件里的注释是英文。

选项

把文件写进忽略列表不等于密钥安全。它只能阻止以后再提交：曾经提交过的文件会留在历史里，公开仓库里出现过的密钥要当作已经泄露。把密钥放在项目文件夹之外，提交过的密钥要作废重发。

预览

.gitignore

# .gitignore for Xcode and Swift projects
# Based on github/gitignore (Swift.gitignore, Global/Xcode.gitignore, Global/macOS.gitignore), licence CC0-1.0.
# Source: https://github.com/github/gitignore, checked 2026-11-01. Blocks marked "added" are not in those files.

# Your own window layout, breakpoints and open files. They differ on every Mac, so committing them only causes merge conflicts.
# xcuserdata/ is in Swift.gitignore; *.xcuserstate is added (older projects kept it outside xcuserdata).
xcuserdata/
*.xcuserstate

# Build output. Xcode keeps DerivedData outside the project unless you moved it; ignore it in case you did. Added.
DerivedData/
build/

# Archives and debug symbols you export for upload. Large, and rebuilt from the source. From Swift.gitignore.
*.ipa
*.dSYM.zip
*.dSYM

# Header maps and Playground scratch files that Xcode regenerates. From Swift.gitignore.
*.hmap
timeline.xctimeline
playground.xcworkspace

# .build/ is where swift build puts downloaded packages and build output. From Swift.gitignore.
# .swiftpm/ is local state that Xcode and SwiftPM write; Swift.gitignore lists it only as a comment, so this line is added.
.build/
.swiftpm/

# Package.resolved is not ignored on purpose. Commit it in an app so every build uses the same dependency versions.
# A library usually ignores it, because the apps that use the library choose their own versions.

# Finder folder settings that macOS drops into every folder. From Global/macOS.gitignore.
.DS_Store

# Keys and local settings: App Store Connect API keys (.p8), signing certificates (.p12), .env files. Added.
# Ignoring only stops new commits. A file that is already committed stays in the history, and anyone with the repository can read it.
# Keep keys out of the project folder, and revoke any key that was ever committed.
*.p8
*.p12
.env
.env.*

Git 已经在跟踪的文件，加进这里以后仍会被跟踪。需要停止跟踪时运行一次 git rm -r --cached <路径>。

它不做什么

  • •它不创建 Xcode 项目，也不创建包里的文件夹和 Swift 文件，只列出要建的文件夹。要完整的包骨架，用 swift package init。
  • •它不了解你的项目。生成的 .gitignore 只是起点：逐段看一遍，再运行 git status 看 Git 还在跟踪什么。
  • •它不检查依赖的网址或版本是否存在，也不替你运行 swift build。依赖只写成 from: 版本（不支持分支、固定版本或 traits）。
  • •它不能让密钥离开你的仓库。忽略规则只能阻止以后再提交，提交过一次的密钥会留在历史里。
  • •生成文件里的注释是英文；设置名和 API 名从不翻译。

常见问题

要不要提交 Package.resolved？
App 要提交：它把每个依赖固定在你测试过的版本，队友和构建服务器拿到的代码一样。库通常不提交：使用你的库的 App 会自己解析版本，你的这个文件不会被用到。.gitignore 标签页可以任选其一。
我把文件加进了 .gitignore，Git 还是显示有改动，为什么？
忽略规则只对 Git 还没跟踪的文件生效。运行一次 git rm -r --cached 路径/文件 再提交，文件会留在你的磁盘上，但离开仓库。它仍在旧提交里；如果里面有密钥，要当作已经泄露并更换。
swift-tools-version 选哪个？
选包含你所用全部功能的最旧版本，因为它就是能打开这个包的最旧 Swift。.iOS(.v18)、.macOS(.v26) 这类写法分别从 tools 6.0 和 6.2 开始存在，本页只列出所选 tools 版本认识的写法。tools 6.0 及以后默认按 Swift 6 语言模式编译，除非你保持 Swift 5 模式。
新包用 Swift Testing 还是 XCTest？
Swift Testing（import Testing、@Test）是较新的单元测试写法，需要 Swift 6 工具链。UI 测试和性能测试仍然要用 XCTest，两者可以放在同一个测试 target 里。清单里的 .testTarget 写法相同，只有测试文件不同。
.xcconfig 里怎么写网址？
// 在一行的任何位置都会开始注释，所以 API_URL = https://example.com 读出来是 https:。写成 API_URL = https:/$()/example.com：空的 $() 在文件里把两个斜杠隔开，Xcode 读到的是 https://example.com。本页的 .xcconfig 标签页会替你这样写。
怎样在 Xcode 里使用这些 .xcconfig？
把三个文件放进项目文件夹，选中项目（不是 target），打开 Info 标签页，在 Configurations 下给 Debug 选 Debug.xcconfig，给 Release 选 Release.xcconfig。在 target 的 Build Settings 里手填的值优先于文件，需要让文件生效时把那里的值清掉。

相关工具