Raycast API：如何构建自定义扩展插件（2026 开发者指南）

Raycast 与其他 macOS 启动器（如 Spotlight 或 Alfred）的区别之一是其扩展生态系统。Raycast 商店拥有超过 1,000 个社区构建的扩展，几乎可以满足所有需求。但如果您需要定制化的东西呢？Raycast API 让您可以使用 React 和 TypeScript——大多数开发者已经熟悉的技术栈——构建自己的扩展。

在本指南中，我将介绍在 2026 年构建、测试和发布 Raycast 扩展所需了解的一切。无论您是想为团队创建内部工具、自动化重复工作流，还是为开源商店做贡献，这都是您的起点。如果您还在探索 Raycast 能做什么，请查看当前 Raycast Pro 优惠以解锁与自定义扩展配合良好的 AI 功能。

使用 Raycast API 可以构建什么

Raycast API 让您可以访问完整的启动器 UI 和系统集成层。扩展可以：

• 显示列表和网格 — 可搜索、可过滤的项目列表（仓库、任务、书签、任何内容）
• 显示详情视图 — 带有元数据侧边栏的富 Markdown 渲染内容
• 渲染表单 — 用于数据输入的输入字段、下拉菜单、日期选择器、文件选择器
• 执行操作 — 打开 URL、复制文本、运行 Shell 命令、触发 API 调用
• 集成到菜单栏 — 持久状态指示器和快速访问菜单
• 存储偏好设置和数据 — 用于设置、缓存和用户数据的本地存储
• 访问系统 API — 剪贴板、通知、选中的 Finder 文件、最前面的应用程序

使用该 API 构建的流行扩展包括 GitHub 扩展、Jira 集成、Notion 快速捕获、Spotify 控制器和数百个更多。您可以在最佳 Raycast 扩展汇总中浏览所有内容。

技术栈：React + TypeScript

如果您构建过 React Web 应用，Raycast 开发体验会立即感觉熟悉。扩展使用 TypeScript（或 JavaScript，虽然强烈推荐 TypeScript）编写，并使用 @raycast/api 包提供的 React 组件。

与 Web React 的关键区别：您不是在渲染到 DOM。Raycast 提供自己的 UI 组件——List、Detail、Form、Grid、ActionPanel——它们在 Raycast 窗口内原生渲染。这意味着您可以获得一致的样式、键盘导航和流畅的性能，而无需编写任何 CSS。

以下是显示列表的最简扩展：

import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="Hello World" subtitle="我的第一个扩展" />
      <List.Item title="另一个项目" subtitle="带有图标" icon="star.png" />
    </List>
  );
}

就这些。没有 webpack 配置，没有 CSS，没有需要设置的构建工具。Raycast 自动处理渲染、键盘导航和搜索过滤。

入门：您的第一个扩展

前提条件

• 在您的 Mac 上安装 Raycast（免费版足够用于开发）
• Node.js 版本 16 或更高
• 代码编辑器（推荐 VS Code——Raycast 有官方 VS Code 开发扩展）

第一步：创建扩展

打开 Raycast 并运行"创建扩展"命令。这会启动一个交互式向导，您可以选择：

• 扩展名称和描述
• 模板（List、Detail、Form 或空白）
• 将创建项目的目录

或者，使用 CLI：

npx create-raycast-extension my-extension

这会创建一个包含 TypeScript 配置、package.json 和示例命令的完整项目。

第二步：了解项目结构

Raycast 扩展项目如下所示：

my-extension/
  src/
    index.tsx          # 您的主要命令
    other-command.tsx   # 额外的命令
  assets/              # 图标和图像
  package.json         # 依赖和 Raycast 元数据
  tsconfig.json        # TypeScript 配置

package.json 在 raycast 键下包含 Raycast 特定的元数据：扩展名称、描述、命令、偏好设置和所需权限。

第三步：使用热重载进行开发

运行开发服务器：

npm run dev

这会启动一个监视文件变更并在发生更改时重新编译的监听器。回到 Raycast，您的开发扩展会自动出现。每次您保存文件时，扩展就会在 Raycast 中重新加载——您获得几乎即时的反馈，类似于 Web 开发中的热模块替换。

第四步：构建和测试

开发环境也是您的测试环境。在构建过程中直接在 Raycast 中与您的扩展交互。没有单独的模拟器或仿真器——您针对真实情况进行测试。

对于调试，使用出现在 Raycast 开发者控制台中的 console.log() 语句（通过"切换开发者工具"命令访问），或使用带有 Raycast 调试配置的 VS Code 调试器。

核心 API 组件

List（列表）

最常见的组件。显示带有标题、副标题、图标和附件的可搜索项目列表。支持分节、过滤和分页。大多数 Raycast 扩展都基于 List。

Detail（详情）

显示从 Markdown 渲染的富内容。非常适合显示 README 文件、API 响应、文档或任何详细信息。支持用于结构化数据的元数据侧边栏。

Form（表单）

带有文本字段、文本区域、下拉菜单、复选框、日期选择器和文件选择器的输入表单。当您的扩展需要从用户收集信息时使用这些——比如创建 Issue、撰写消息或配置设置。

Grid（网格）

用于图像密集内容的可视网格布局。由 Unsplash、图标选择器和调色板工具等扩展使用。每个网格项目可以显示带有标题和副标题的图像。

ActionPanel（操作面板）

当用户在列表项上按 Enter 或 Cmd+K 时出现的操作菜单。操作可以打开 URL、将文本复制到剪贴板、推送新视图、运行函数等。这是大多数用户交互发生的地方。

偏好设置和存储

API 提供了用于用户可配置设置（API 密钥、默认选项）的偏好设置系统，以及用于在会话之间持久化数据的本地存储 API。偏好设置在 package.json 中定义，并在 Raycast 中自动渲染为设置表单。

Raycast 商店：发布您的扩展

Raycast 商店是扩展触及用户的方式。发布是免费的，但需要审查流程。以下是工作方式：

1. Fork 扩展仓库 — 所有商店扩展都存放在 raycast/extensions GitHub 仓库中
2. 添加您的扩展 — 将您的扩展目录放在 extensions/ 文件夹中
3. 开启 Pull Request — 提交您的扩展进行审查
4. 审查流程 — Raycast 团队审查质量、安全性和准则合规性（通常 3-7 个工作日）
5. 发布 — 一旦获批，您的扩展就会出现在商店中，供所有 Raycast 用户使用

审查准则

Raycast 对商店扩展有明确的质量标准：

• 扩展必须有明确的目的且可靠运行
• 代码质量很重要——干净的 TypeScript、适当的错误处理、加载状态
• UI 应遵循 Raycast 设计模式（使用内置组件，不要对抗框架）
• 没有恶意行为、数据收集或不必要的权限
• README 中有良好的描述、截图和文档

审查过程严格但公平。如果要求更改，审查者会提供清晰的反馈。大多数扩展在一周内获批。

使用 API 构建的流行扩展示例

为了了解可能实现的内容，以下是商店中一些出色的扩展：

• Brew — 从 Raycast 搜索、安装和管理 Homebrew 包。演示了带搜索、操作和 Shell 命令执行的 List。
• Notion — 快速捕获到 Notion 数据库、搜索页面和创建新页面。展示了 Form 使用和 API 集成。
• Spotify 播放器 — 在菜单栏中显示正在播放信息的完整音乐控制。演示了菜单栏集成和实时更新。
• 剪贴板历史 — Raycast 的内置扩展之一，展示了带有分节、搜索和剪贴板操作的 List 如何协同工作。
• 颜色拾取器 — 带有格式转换的系统级颜色拾取器。展示了扩展如何访问 macOS 系统功能。

所有这些都在 raycast/extensions 仓库中开源，因此您可以阅读源代码作为参考和灵感。

构建优秀扩展的技巧

从简单开始

您的第一个扩展不需要很复杂。从解决一个问题出色的单一命令开始。以后可以添加更多命令和功能。商店中最好的扩展通常只做一件事，但做得非常好。

优雅地处理加载和错误

在 List 和 Detail 组件上使用 isLoading prop 显示加载指示器。将 API 调用包装在 try-catch 块中，并使用 showToast() 显示有意义的错误消息。用户不应该看到空白屏幕或神秘的错误。

严格使用 TypeScript

在您的 tsconfig.json 中启用严格模式。Raycast API 完全有类型，TypeScript 会在您运行扩展之前捕获大多数 bug。当类型正确定义时，VS Code 中的自动完成非常出色。

利用缓存

如果您的扩展从 API 获取数据，使用 Raycast 的 Cache API 在本地存储响应。这使扩展在后续启动时感觉即时，同时新鲜数据在后台加载。

研究现有扩展

学习模式的最佳方法是阅读已建立扩展的源代码。raycast/extensions 仓库有超过 1,000 个扩展可以学习。找到与您要构建的类似的，研究其架构。

使用 Raycast Pro 功能构建扩展

如果您是 Raycast Pro 订阅者，您的扩展可以利用额外的功能。Raycast AI 可以与自定义扩展一起用于智能自动完成、内容生成和工具内的自然语言处理。云同步确保您的扩展偏好设置在所有 Mac 上保持一致。

在任何计划上构建扩展都是免费的，但将它们与 Pro 功能如 AI 结合使用会将其提升到新的水平。如果您还没有尝试过 Pro，享受 8 折优惠和免费试用——这是目前最优惠的方案。

要了解 Raycast 如何融入 macOS 生产力格局的更多信息，请阅读我们的 Raycast 是什么指南。

常见问题

我需要了解 React 才能构建 Raycast 扩展插件吗？

基本的 React 知识很有帮助，因为 Raycast 扩展使用 React 组件，但您不需要是专家。API 提供了预构建的 UI 组件——List、Detail、Form、ActionPanel——可以处理大部分布局和交互。如果您了解 JavaScript 并理解 JSX 语法，您可以快速构建功能性扩展。官方文档包含大量可直接使用的示例。

扩展审查流程是什么样的？

通过向 raycast/extensions GitHub 仓库提交 Pull Request 后，Raycast 团队会审查其质量、安全性和准则合规性。审查通常需要 3-7 个工作日。团队可能在批准前要求更改——反馈具有建设性和针对性。一旦获批，您的扩展就会发布到 Raycast 商店，供所有用户使用。

我可以从 Raycast 扩展中获利吗？

目前，Raycast 不为商店扩展提供直接的货币化机制。所有已发布的扩展对用户免费安装。但是，您可以构建与您的付费服务或 SaaS 产品集成的扩展，有效地将扩展作为分发渠道。一些开发者还为客户构建私人自定义扩展作为付费咨询工作。

Raycast API 是免费使用的吗？

是的，完全免费。Raycast API、开发工具、CLI 脚手架和商店发布都是免费的。您不需要 Raycast Pro 来开发或发布扩展——免费版包含完整的扩展开发功能。您可能遇到的唯一费用与您的扩展集成的第三方 API 有关（如 OpenAI、数据库等）。