Prefire

快速开始 · 安装 · 用法 · AI Agent · 配置 · 文档

🔥 Prefire 是什么？

Prefire 可将你已有的 #Preview 代码块转换为测试、目录和图像，无需编写额外代码。

📸 快照测试 每个预览都会在你选择的设备上成为一个快照测试。在用户发现视觉回归之前，及时捕捉问题。 了解工作原理 →

📚 Playbook 交互式组件和用户故事目录，包含各种状态和渲染耗时。让文档保持鲜活。 查看 Playbook →

🤖 适用于 AI 的渲染结果 Claude Code、Cursor 和 Codex 可通过 MCP 服务，在任意 iPhone 或 iPad 上渲染预览，支持浅色或深色模式。 开始设置 →

🤖 正在使用 AI Agent？ 运行 brew install barredewe/prefire/prefire，然后在项目中运行 claude mcp add prefire -- prefire mcp。Agent 无需使用 Xcode Previews，即可在任意 iPhone 或 iPad 上以浅色或深色模式渲染 SwiftUI 预览。设置 →

🚀 主要功能

• 🧠 智能预览解析 — 支持 #Preview、@Previewable
• 📸 快照测试 — 根据预览自动生成测试（iOS、tvOS、macOS）
• 📚 Playbook 视图 — 自动生成交互式组件目录（iOS）
• 🏃 流程感知 — 通过多个预览步骤构建用户故事
• 🤖 适用于 AI — 使用 prefire render 和 MCP 服务为 Agent 将预览渲染为 PNG
• 🧩 支持 UIKit + AppKit — 支持 UIView/UIViewController 和 NSView/NSViewController
• ⚙️ SPM + Xcode 插件 — 可在 CLI、Xcode 构建阶段或 CI 中使用
• 🧠 快速缓存 — 基于指纹的 AST 和主体缓存可避免重复工作
• ✍️ Stencil 模板 — 使用自定义模板定制输出

为什么选择 Prefire？

• 🔥 节省时间 - 自动生成测试和文档
• 🔥 保持一致 - 确保预览和测试始终同步
• 🔥 提升质量 - 在用户发现视觉回归之前，及时捕捉问题
• 🔥 加强协作 - 与团队共享鲜活的文档

---

⚡ 快速开始

📦 示例项目见：Prefire 示例

1. 将 Prefire 添加到项目中

// Package.swift
dependencies: [
    .package(url: "https://github.com/BarredEwe/Prefire.git", from: "6.3.0"),
    .package(url: "https://github.com/pointfreeco/swift-snapshot-testing", from: "1.18.0"),
],
.testTarget(
    dependencies: [
      .product(name: "Prefire", package: "Prefire"),
      .product(name: "SnapshotTesting", package: "swift-snapshot-testing"),
    ],
    plugins: [
        .plugin(name: "PrefireTestsPlugin", package: "Prefire")
    ]
)

2. 编写 #Preview

#Preview {
    Button("Submit")
}

3. 运行测试

只需运行测试目标 🚀，Prefire 就会根据预览自动生成快照。

💡 如果测试目标为空，Prefire 仍会在构建期间生成文件和快照代码。

---

📦 安装

方式	操作
SPM 插件	在 Package.swift 中使用 PrefireTestsPlugin / PrefirePlaybookPlugin
Xcode 构建工具插件	将 PrefireTestsPlugin 添加到测试目标的构建阶段
CLI	brew install barredewe/prefire/prefire
Mint（Beta）	mint install BarredEwe/Prefire
GitHub Actions / CI	使用上述任一方式，参见故障排除

分步设置说明见安装指南。

要求

• Swift 6.0 或更高版本
• Xcode 16.0 或更高版本
• iOS 14 或更高版本；macOS 13 或更高版本（macOS：仅支持快照测试，参见配置）

---

🛠 用法

选择预览

Prefire 会自动查找所有 #Preview。对于 PreviewProvider，请添加 PrefireProvider 协议：

struct Text_Previews: PreviewProvider, PrefireProvider {
    static var previews: some View { ... }
}

使用 .prefireIgnored() 排除预览：

#Preview {
    Text("")
        .prefireIgnored()
}

如需选择性启用而非选择性排除，请在 .prefire.yml 中将 preview_default_enabled: false 设为 false，并使用 .prefireEnabled() 标记所需的预览：

#Preview {
    Text("")
        .prefireEnabled()
}

快照测试

当测试目标构建时，PrefireTestsPlugin 会将测试生成到 DerivedData 文件夹中。按常规方式运行测试目标即可。

调整单个快照的计时和精度：

#Preview {
    TestView()
        .snapshot(delay: 0.3, precision: 0.95, perceptualPrecision: 0.98)
}

对于需要加载或带有动画的预览，请使用等待功能，而不是猜测延迟时间：

.snapshot(waitForIdle: true)                     // until nothing changes on screen
.snapshot(waitUntil: { viewModel.isLoaded })     // until a condition is true

了解等待机制、其限制以及修饰符的组合方式：快照计时和精度。

快照使用 swift-snapshot-testing 进行比较。

Playbook（演示）视图

使用 PlaybookView 将所有预览显示为交互式目录：

• isComponent: true 会列出所有视图
• isComponent: false 会按 UserStory 分组

import Prefire 

struct ContentView: View {
    var body: some View {
        PlaybookView(isComponent: true, previewModels: PreviewModels.models)
    }
}

如需避免在发布构建中包含预览和 PreviewModels，请参见从发布构建中排除预览。

流程

使用 .previewUserStory 将预览连接成一个流程。Playbook 会按顺序将它们一起显示：

static var previews: some View {
    PrefireView()
        .previewUserStory(.auth)
}

static var previews: some View {
    AuthView()
        .previewUserStory(.auth)
}

状态

如果一个预览包含多个 View，请标记每个视图的 State：

static var previews: some View {
    TestView("Default")

    TestView("Loading")
        .previewState(.loading)
}

参数化预览

Prefire 会将原生 SwiftUI 参数化预览的每个参数展开为独立的快照和 Playbook 预览：

#Preview("TextView", traits: .sizeThatFitsLayout, arguments: ["- A", "- B", "- C"]) { suffix in
    Text("1 \(suffix)")
}

---

🧰 API

功能	修饰符
纳入快照	.prefireEnabled()
从快照中排除	.prefireIgnored()
在流程中分组	.previewUserStory(.auth)
标记 UI 状态	.previewState(.error)
自定义快照	.snapshot(delay: 0.3, precision: 0.95)
等待预览稳定	.snapshot(waitForIdle: true, timeout: 2.0)
等待条件满足	.snapshot(waitUntil: { viewModel.isLoaded })
参数化预览	#Preview(..., arguments: values)

---

💡 CLI 用法

# Generate snapshot tests
prefire tests

# Generate playbook models
prefire playbook

运行 prefire tests --help 或 prefire playbook --help 以查看更多选项。

---

🤖 让 AI Agent 查看 SwiftUI

Prefire 会在快照测试中重新构建预览，并在你选择的设备上渲染，因此可以将预览作为图像展示给 AI Agent；而 Xcode Previews 在 Xcode 之外无法可靠地做到这一点。

# Render previews to PNG + JSON
prefire render "Sign in" --device "iPhone 16 Pro" --color-scheme dark

# An HTML board of the last render, grouped by user story
prefire board

在包含 .prefire.yml 的文件夹中，将 MCP 服务添加到你的 Agent：

Agent	安装方式
Claude Code	claude mcp add prefire -- prefire mcp，或安装带有技能的插件：/plugin marketplace add BarredEwe/Prefire，然后运行 /plugin install prefire@prefire
Cursor
Codex	codex mcp add prefire -- prefire mcp
VS Code	code --add-mcp '{"name":"prefire","command":"prefire","args":["mcp"]}'

然后，Agent 会调用 list_previews、render_previews 和 build_board。在 .prefire.yml 的 render_configuration 中设置要构建的 scheme；请参阅 AI 指南。为什么不使用 Xcode 自带的 RenderPreview？Prefire 无需运行中的 Xcode，即可在一次构建中渲染多个预览，并使用你指定的设备、颜色方案和 Dynamic Type，还能在 CI 中运行。

---

🗂 配置：.prefire.yml

test_configuration:
  target: MyApp

playbook_configuration:
  preview_default_enabled: true

所有选项都列在配置指南中。若要更改生成的代码，请参阅 Templates。

---

🧠 工作原理

1. 🔍 解析所有源文件 — 查找 #Preview 和 PreviewProvider 块，以及 .prefireEnabled() / .prefireIgnored() 修饰符
2. 📂 缓存 Types 和 PreviewBodies — 以文件修改日期和输入内容的 SHA-256 值作为键；如果内容没有变化，就不会重新解析
3. 🔢 生成快照测试 — 使用 Stencil 模板，并遵循 .prefire.yml 中的设置
4. 📘 生成 Playbook 模型 — 按 UserStory 和 State 分组，生成 PreviewModels.generated.swift

---

🩺 故障排除

问题	解决方法
Playbook 中的预览无法使用 NavigationView	根据 Playbook 需求改用其他视图或布局
插件在 CI 上无法运行	defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES
Xcode 无法在自定义路径中生成测试	禁用插件沙盒：defaults write com.apple.dt.Xcode IDEPackageSupportDisablePluginExecutionSandbox -bool YES

---

🐱 作者的其他作品

Mewmori 是一只住在 Mac 桌面上的像素猫。 它会读取屏幕上的内容，对此说点什么，并在不同会话之间记住你。 一个 2B 模型通过 llama.cpp 在本机运行，因此屏幕文本、聊天记录和记忆都保留在你的 Mac 上。

使用 Swift、AppKit + SwiftUI 编写，大小为 29 MB。免费；只有皮肤需要付费。

🤝 参与贡献

欢迎贡献！开发环境设置、测试和内部架构详见 CONTRIBUTING.md。

⭐ Star 历史

如果 Prefire 为你节省了时间，请为它点个 Star：这有助于其他 iOS 开发者发现它。

📄 许可证

Prefire 基于 Apache License 2.0 发布。详情请参阅 LICENSE。