Clerk Swift iOS 原生集成指南：SwiftUI/UIKit 认证实现与快速开始

clerk-swift by clerk/skills

568 周安装量

30 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/clerk/skills --skill clerk-swift

iOS 开发 Swift

🇨🇳中文介绍

Clerk Swift（原生 iOS）

此技能通过读取已安装的包源码并镜像当前 ClerkKit/ClerkKitUI 的行为，在原生 Swift/iOS 项目中实现 Clerk。

激活规则

当满足以下任一条件时激活此技能：

用户明确要求 Swift、SwiftUI、UIKit 或原生 iOS Clerk 实现。
项目似乎是原生 iOS/Swift（例如 .xcodeproj、.xcworkspace、Package.swift、Swift 目标）。

当满足以下任一条件时不要激活此技能：

项目是 Expo。
项目是 React Native。

如果存在 Expo/React Native 信号，请路由到通用设置技能，而不是此技能。

快速开始

步骤	操作
1	确认项目类型是原生 Swift/iOS 且非 Expo/React Native
2	确定流程类型（`prebuilt` 或）并加载匹配的参考文件

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

源码驱动的模板

不要在此技能中硬编码实现示例。在实现之前检查当前已安装的包源码。

用例	已安装包中的事实来源
SDK 包产品、平台支持和依赖约束	`ClerkKit` 和 `ClerkKitUI` 的包清单和目标产品定义，以及包要求样式（up-to-next-major）
可发布密钥验证和前端 API 派生	Clerk 配置逻辑（搜索符号：`configure(publishableKey`、`frontendApiUrl`、`invalidPublishableKeyFormat`）
环境端点契约和字段语义	环境请求路径和请求构建，加上 `ClerkKitUI` 中用于控制的 `Environment` 字段使用（搜索符号：`/v1/environment`、`Request<Clerk.Environment>`、`ClerkKitUI` 中的 `Environment` 使用）
iOS 快速开始要求	已安装 `clerk-ios` 包 README 中的快速开始链接加上访问/读取的快速开始页面清单步骤（包括项目设置先决条件）
原生“使用 Apple 登录”实现	所选流程参考中的 Apple 能力和原生登录行为

执行关卡（不可跳过）

先决条件未满足前不进行实现编辑
- 在确认流程类型并获得有效的可发布密钥之前，不要编辑项目文件。
缺失流程或密钥必须触发提问
- 如果缺少流程选择，明确询问：预构建视图还是自定义流程。
- 如果可发布密钥缺失/是占位符/无效，明确要求一个真实的密钥。
- 在获得两个答案之前不要继续。
可发布密钥连接模式是强制的
- 在传递给 Clerk.configure 的应用配置中，直接使用开发者提供的可发布密钥。
- 除非明确请求，否则不要引入 plist/本地密钥/环境文件/构建设置的间接方式。
包安装/版本策略是强制的
- 如果 clerk-ios 未安装，使用最新的可用版本并采用“up-to-next-major”要求添加它。
- 除非开发者明确要求精确锁定，否则不要固定确切的包版本。
ClerkKitUI Environment 字段检查是强制的
- 安装包后，检查已安装的 ClerkKitUI 源码，并确定哪些 Environment 字段为所选流程控制认证行为。
- 在进行任何 /v1/environment 调用之前，构建一个代理内部的字段映射。
环境调用是强制的（两种流程）
- 仅在包安装和步骤 5 的字段映射检查之后，才直接进行 HTTP 调用到 /v1/environment。
- 使用与 ClerkKitUI 对齐的字段映射将响应传递到选定的参考工作流中：
  - 预构建：用它来确定 Apple 是否启用以及是否需要能力更改
  - 自定义：仅作为代理内部分析执行完整的规范化/矩阵处理（切勿在项目代码中持久化矩阵工件）
参考文件纪律是强制的
- 一旦选定流程，仅遵循该流程参考文件进行实现和验证。
快速开始合规性是强制的
- 在已安装的 clerk-ios 包 README 中找到 iOS 快速开始 URL，追加 .md，然后访问并读取该 Markdown URL。
- 在完成之前，根据所有快速开始设置步骤审核项目。
- 如果缺少必需的快速开始设置，请在完成任务之前实现它。
- 这包括添加任何缺失的关联域条目以及快速开始中要求的任何其他应用能力。
- 明确执行快速开始步骤 添加关联域能力（https://clerk.com/docs/ios/getting-started/quickstart#add-associated-domain-capability），并确保关联域条目符合快速开始要求（webcredentials:{YOUR_FRONTEND_API_URL}）。
自定义流程 AuthView 结构对等性是强制的
- 对于 custom 流程，布局和流程结构必须在实质上接近 ClerkKitUI AuthView 的默认设置。
- 如果开发者没有明确请求不同的用户体验，不要引入与 AuthView 有重大结构/布局偏差的设计。
- 如果对自定义排序、控制或 Environment 使用/语义不确定/困惑，请参考已安装的 ClerkKitUI 行为并镜像它。

检测原生 iOS/Swift 与 Expo/React Native。
如果未明确提供流程类型，向用户询问 prebuilt 或 custom。
如果未明确提供可发布密钥，向用户询问。
在更改文件之前等待两个答案。
加载匹配的流程参考文件。
确保可发布密钥有效并直接在 Clerk.configure 中连接。
确保包安装/产品匹配所选流程，并且新添加时包要求遵循最新的“up-to-next-major”策略。
检查已安装的 ClerkKitUI 源码，以映射所选流程中用于控制/必需行为的 Environment 字段。
调用 /v1/environment 并通过步骤 8 的字段映射解释响应。
从已安装的 clerk-ios 包 README 中找到 iOS 快速开始 URL，追加 .md，然后访问并读取它。
根据访问的 Markdown 快速开始构建快速开始清单，检测缺失的必需设置，并在当前项目中应用缺失的设置。
确保快速开始关联域能力步骤完全应用（当缺失时添加 webcredentials:{YOUR_FRONTEND_API_URL}）。
使用选定的参考清单进行实现。
使用选定的参考清单加上共享关卡进行验证。

级别	问题	预防措施
CRITICAL	在实现前未询问缺失的流程选择	在编辑前询问 `prebuilt` 与 `custom` 并等待
CRITICAL	在实现前未询问缺失的可发布密钥	在编辑前询问密钥并等待
CRITICAL	在确认流程类型前开始实现	首先确认流程并加载匹配的参考
CRITICAL	未经请求使用 plist/本地/环境间接方式处理可发布密钥	默认直接在配置中连接密钥
CRITICAL	在实现前跳过 `/v1/environment` 调用	始终为预构建和自定义流程调用环境端点
CRITICAL	在包安装 + ClerkKitUI `Environment` 字段检查之前调用 `/v1/environment`	先安装 `clerk-ios`，检查 ClerkKitUI `Environment` 使用情况，然后调用端点
HIGH	默认安装带有精确/过时版本的 `clerk-ios`	如果缺失，使用“up-to-next-major”要求安装最新的可用版本
CRITICAL	跳过快速开始先决条件审核	访问/读取已安装 `clerk-ios` 包 README 中的快速开始 URL，并验证所有必需的设置步骤已完成
CRITICAL	检测到缺失的快速开始能力/域但未应用它们	在完成前添加所有缺失的必需快速开始能力和关联域
CRITICAL	跳过快速开始关联域能力步骤	执行快速开始 `添加关联域能力` 并确保 `webcredentials:{YOUR_FRONTEND_API_URL}` 存在
CRITICAL	将能力/必需字段矩阵写入应用代码	将矩阵保持在代理内部，仅在 UI/认证流程代码中应用最终行为
CRITICAL	自定义流程布局在未经明确请求的情况下偏离 `AuthView`	默认保持自定义屏幕在实质上接近 `AuthView` 结构和步骤组成
CRITICAL	将自定义认证折叠成单个全字段屏幕	遵循 `AuthView` 风格的多步骤推进和步骤特定的字段收集
CRITICAL	不确定时猜测自定义排序/控制/`Environment` 使用	参考已安装的 `ClerkKitUI` 行为并镜像它以进行最终实现
HIGH	将此技能用于 Expo/React Native	在实现前检测并路由到其他技能

../clerk/SKILL.md 用于顶级 Clerk 路由
../setup/SKILL.md 用于非原生或跨框架设置
已安装的 clerk-ios 包 README.md（当前 iOS 快速开始链接的来源）
https://github.com/clerk/clerk-ios

🇺🇸English

Clerk Swift (Native iOS)

This skill implements Clerk in native Swift/iOS projects by reading installed package source and mirroring current ClerkKit/ClerkKitUI behavior.

Activation Rules

Activate this skill when either condition is true:

The user explicitly asks for Swift, SwiftUI, UIKit, or native iOS Clerk implementation.
The project appears to be native iOS/Swift (for example .xcodeproj, .xcworkspace, Package.swift, Swift targets).

Do not activate this skill when either condition is true:

The project is Expo.
The project is React Native.

If Expo/React Native signals are present, route to the general setup skill instead of this one.

Quick Start

Step	Action
1	Confirm project type is native Swift/iOS and not Expo/React Native
2	Determine flow type (`prebuilt` or `custom`) and load the matching reference file
3	Ensure a valid publishable key exists (or ask developer) and wire it directly in configuration
4	Ensure `clerk-ios` package is installed with correct products for selected flow; if missing, install latest available release using an up-to-next-major version requirement
5	Inspect installed `ClerkKitUI` source to identify which `Environment` fields drive feature/step gating
6	Call `/v1/environment` after step 5 and evaluate only against the `ClerkKitUI`-aligned field map
7	Find the iOS quickstart URL in the installed `clerk-ios` package README, append `.md`, then visit and read the markdown URL to compile a required-step checklist
8	Verify and complete all quickstart prerequisites for this project (for example associated domains and required capabilities)
9	Implement flow by following only the selected reference checklist

Decision Tree

User asks for Clerk in Swift/iOS
    |
    +-- Expo/React Native project detected?
    |     |
    |     +-- YES -> Do not use this skill
    |     |
    |     +-- NO -> Continue
    |
    +-- Existing auth UI detected?
    |     |
    |     +-- Prebuilt views detected -> Load references/prebuilt.md
    |     |
    |     +-- Custom flow detected -> Load references/custom.md
    |     |
    |     +-- New implementation -> Ask developer prebuilt/custom, then load matching reference
    |
    +-- Ensure publishable key and direct wiring
    |
    +-- Ensure clerk-ios is installed
    |
    +-- Inspect ClerkKitUI Environment field usage
    |
    +-- Call /v1/environment using that field map
    |
    +-- Visit/read quickstart URL from installed clerk-ios package README
    |
    +-- Verify all quickstart prerequisites are completed
    |
    +-- Implement using selected flow reference

Flow References

After flow type is known, load exactly one:

Prebuilt flow: references/prebuilt.md
Custom flow: references/custom.md

Do not blend the two references in a single implementation unless the developer explicitly asks for a hybrid approach.

Interaction Contract

Before any implementation edits, the agent must have both:

flow choice: prebuilt or custom
a real Clerk publishable key

If either value is missing from the user request/context:

ask the user for the missing value(s)
pause and wait for the answer
do not edit files or install dependencies yet

Only skip asking when the user has already explicitly provided the value in this conversation.

Source-Driven Templates

Do not hardcode implementation examples in this skill. Inspect current installed package source before implementing.

Use Case	Source of Truth in Installed Package
SDK package products, platform support, and dependency constraints	Package manifest and target product definitions for `ClerkKit` and `ClerkKitUI`, plus package requirement style (up-to-next-major)
Publishable key validation and frontend API derivation	Clerk configuration logic (search symbols: `configure(publishableKey`, `frontendApiUrl`, `invalidPublishableKeyFormat`)
Environment endpoint contract and field semantics	Environment request path and request construction plus `ClerkKitUI` `Environment` field usage for gating (search symbols: , , usage in )

Execution Gates (Do Not Skip)

No implementation edits before prerequisites

Do not edit project files until flow type is confirmed and a valid publishable key is available.

Missing flow or key must trigger a question

If flow choice is missing, explicitly ask: prebuilt views or custom flow.
If publishable key is missing/placeholder/invalid, explicitly ask for a real key.
Do not continue until both answers are provided.

Publishable key wiring mode is mandatory

Use the developer-provided publishable key plainly in app configuration passed to Clerk.configure.
Do not introduce plist/local-secrets/env-file/build-setting indirection unless explicitly requested.

Package install/version policy is mandatory

If clerk-ios is not installed, add it using the latest available release with an up-to-next-major requirement.
Do not pin an exact package version unless the developer explicitly asks for exact pinning.

ClerkKitUI Environment field inspection is mandatory

After package install, inspect installed ClerkKitUI source and identify which Environment fields gate auth behavior for the selected flow.
Build an agent-internal field map before any /v1/environment call.

Environment call is mandatory (both flows)

Make a direct HTTP call to /v1/environment only after package install and step 5 field-map inspection.
Pass the response into the selected reference workflow using the ClerkKitUI-aligned field map:
- prebuilt: use it to determine whether Apple is enabled and capability changes are needed
- custom: perform full normalization/matrix handling as agent-internal analysis only (never persist matrix artifacts in project code)

Reference-file discipline is mandatory

Once flow is selected, follow only that flow reference file for implementation and verification.

Quickstart compliance is mandatory

Find the iOS quickstart URL in the installed clerk-ios package README, append .md, then visit and read that markdown URL.
Audit the project against all quickstart setup steps before finishing.
If required quickstart setup is missing, implement it before completing the task.
This includes adding any missing Associated Domains entries and any other required app capabilities from the quickstart.
Explicitly execute the quickstart step Add associated domain capability (https://clerk.com/docs/ios/getting-started/quickstart#add-associated-domain-capability) and ensure the associated-domain entry matches quickstart requirements (webcredentials:{YOUR_FRONTEND_API_URL}).

Custom-flow AuthView structure parity is mandatory

For custom flow, layout and flow structure must remain materially close to ClerkKitUI AuthView defaults.
If the developer did not explicitly request a different UX, do not introduce major structural/layout deviations from AuthView.
If unsure/confused about custom sequencing, gating, or Environment usage/semantics, defer to installed ClerkKitUI behavior and mirror it.

Workflow

Detect native iOS/Swift vs Expo/React Native.
If flow type is not explicitly provided, ask user for prebuilt or custom.
If publishable key is not explicitly provided, ask user for it.
Wait for both answers before changing files.
Load matching flow reference file.
Ensure publishable key is valid and directly wired in Clerk.configure.
Ensure package install/products match selected flow and package requirement follows latest up-to-next-major policy when newly added.
Inspect installed ClerkKitUI source to map Environment fields used for gating/required behavior in the selected flow.
Call /v1/environment and interpret response through the step 8 field map.
Find iOS quickstart URL from installed clerk-ios package README, append .md, then visit and read it.

Common Pitfalls

Level	Issue	Prevention
CRITICAL	Not asking for missing flow choice before implementation	Ask for `prebuilt` vs `custom` and wait before edits
CRITICAL	Not asking for missing publishable key before implementation	Ask for key and wait before edits
CRITICAL	Starting implementation before flow type is confirmed	Confirm flow first and load matching reference
CRITICAL	Using plist/local/env indirection for publishable key without request	Wire key directly in configuration by default
CRITICAL	Skipping `/v1/environment` call before implementation	Always call environment endpoint for both prebuilt and custom flows
CRITICAL