ruby-native

ruby_native

Ruby Native 可将 Rails 应用转换为 iOS 和 Android 应用。这个 gem 提供 Rails 端集成：视图辅助方法、YAML 配置文件、自动挂载到 /native 的端点，以及用于预览和部署构建的 CLI。完整文档（包括完整的辅助方法参考和配置架构）请访问 rubynative.com/docs。

安装

gem "ruby_native"

引擎会自动挂载到 /native。无需配置路由。

开始使用

运行安装生成器：

rails generate ruby_native:install

这会创建 config/ruby_native.yml，并根据你的路由生成标签页。如果你使用编码 Agent，请把下面的内容交给它：

bundle exec ruby_native mcp install

然后说：在此应用中设置 Ruby Native。它会配置布局、检查自己的工作，之后起草应用商店列表文案、截取屏幕截图并提交审核，只会在 Apple 保留给人工操作的少数几步停下来。手动操作时，步骤相同：

1. 使用你的配色和标签页编辑配置（见下文）。

2. 在布局 <head> 中添加样式表和 viewport-fit=cover：

   <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
   <%= stylesheet_link_tag :ruby_native %>
   

   viewport-fit=cover 是必需的，这样 CSS env(safe-area-inset-*) 变量才能解析为实际值，而不是 0。

3. 在布局 <body> 中添加标签栏：

   <%= native_tabs_tag %>
   

4. 在手机上预览（见下文）。

完整操作指南（包括安全区域布局，以及使用 native_app? 隐藏仅适用于 Web 的导航）请访问 rubynative.com/docs/setup。

配置

config/ruby_native.yml 控制原生外壳：

appearance:
  tint_color: "#007AFF"
  background_color: "#FFFFFF"

tabs:
  - title: Home
    path: /
    icon: house
  - title: Profile
    path: /profile
    icon: person

在开发环境中，无需重启服务器即可应用更改。完整配置架构请访问 rubynative.com/docs，其中包括外观和深色模式、导航栏品牌设置、高级模式、OAuth 和关联域名。

预览

无需部署，即可在真实设备上预览应用：

bundle exec ruby_native preview

这会启动 Cloudflare 隧道，并显示一个 QR 码，供 Ruby Native 应用扫描。Rails 服务器需要单独运行。需要安装 cloudflared：

brew install cloudflare/cloudflare/cloudflared

隧道会指向端口 3000；如果设置了 PORT，则会指向该端口，这与 rails server 选择端口的方式相同。传入 --port 4000 可覆盖端口；如果上游地址不在 localhost，则可传入 --url。

有关 deploy、login 和从 CI 自动部署的信息，请访问 rubynative.com/docs/cli。

React 和 Vue

使用 Inertia 而不是 ERB 构建？@ruby-native/react 和 @ruby-native/vue 提供相同的辅助方法，作为 npm 包发布，并与此 gem 同步版本。设置说明请访问 rubynative.com/docs/inertia。

AI Agent

每个文档页面都提供 Markdown：在 URL 后附加 .md，或请求 Accept: text/markdown。如需查看所有内容的索引，请获取 rubynative.com/llms.txt；如需将完整文档作为单个文件获取，请访问 llms-full.txt。

MCP 服务

文档会告诉 Agent 应该写什么，却不会告诉它写出来的内容是否有效；而 Ruby Native 的信号会按设计静默失败：不识别 data-native-* 属性的应用会忽略它。拼写错误不会渲染任何内容，不会引发错误，也不会记录日志，因此会一直留到有人打开构建，发现按钮不见了。

ruby_native mcp 弥补了这一环节。它通过标准输入和标准输出使用 MCP。三个工具直接读取你的工作副本，无需账户：

工具	可查询内容
check_views	模板中有哪些信号拼写错误、重复，或比已安装的 gem 更新
lookup_signals	每个 data-native-* 属性、所需的 gem 版本，以及生成该属性的辅助方法
validate_config	config/ruby_native.yml 中有哪些内容会被应用直接拒绝，哪些会被静默忽略

另外四个工具会读取你的账户，使用 ruby_native login 已存储的令牌：

工具	可查询内容
status	应用距离提交到 App Store 还有多远、有哪些阻碍，以及谁可以解决每项问题
config_errors	过去 48 小时内真实设备报告的失败情况，以及每项失败背后的解码错误
deployed_builds	用户实际可以安装的构建，以及它无法识别哪些信号
build_status	某个构建是否成功，以及失败时的错误

这两组工具需要配合使用。validate_config 会说明哪些内容将会解码失败；config_errors 会说明哪些内容确实解码失败，以及发生在哪些设备上。check_views 会将模板与 Gemfile 中的 gem 进行比较；deployed_builds 会将模板与应用商店中的二进制文件进行比较，这通常能解答“属性没问题，但我手机上什么也没发生”这个问题。

完整参考文档见 rubynative.com/docs/cli。在项目的 .mcp.json 中注册它，Claude Code 会读取此文件：

bundle exec ruby_native mcp install

然后说：在这个应用中设置 Ruby Native。

将其安装为 Claude Code 插件（先运行 claude plugin marketplace add ruby-native/gem，再运行 claude plugin install ruby-native@ruby-native）后，服务使用的仍是同一条命令。插件会询问是否提供 Ruby Native 令牌；留空即可，账户工具会使用这台机器上通过 ruby_native login 存储的登录信息。

或者，在接受 JSON 的客户端中：

{
  "mcpServers": {
    "ruby-native": {
      "command": "bundle",
      "args": ["exec", "ruby_native", "mcp"]
    }
  }
}

其余工具会通过 Ruby Native 准备各项内容，只有在构建或点击仪表板时才会联系 Apple：permissions_set、testers_add、icon_set、screenshots_setup、screenshots_capture、listing_push、listing_pull 和 demo_account_set，每个工具都与对应的 CLI 命令相同。submit 是唯一会自行联系 Apple 的工具：它需要分两次调用，中间要传入一个令牌，因此 Agent 必须先向你展示即将提交的内容，才能发送；withdraw 则会将其从队列中撤回，直到 Apple 批准。前三个工具不会离开你的机器；其余工具会将 CLI 令牌发送到 rubynative.com。check_views 需要 herb gem，与 ruby_native check 相同。

许可证

MIT。