Rails 控制器返回 Inertia 响应时如何正确传参…

在 Rails 控制器中为 Inertia.js 页面提供数据、共享数据、flash、重定向和校验错误时使用。

适用场景

解决思路

1. 传递数据必须显式调用 `render inertia: { key: data }`，实例变量不会自动作为 props 传给前端（除非配置了 alba-inertia gem，需先检查 Gemfile）。
2. 添加 prop 前先判断：每个页面都需要的用基类控制器中的 `inertia_share`；计算昂贵的用 `InertiaRails.defer`；仅部分重载需要的用 `InertiaRails.optional`；很少变化的参考数据用 `InertiaRails.once`。
3. 注意 `default_render: true` 只自动推断组件名，不会自动传实例变量；只要 action 访问数据库，就必须调用 `render inertia:` 并传数据；空 action 仅适用于无需数据的静态页面。
4. 渲染不同页面时用 `render inertia: 'errors/show', props: { error: e }` 显式指定组件路径。
5. prop 类型语法：普通 `{ key: value }` 始终求值；惰性 `-> { ... }`；可选 `InertiaRails.optional { ... }`；延迟 `InertiaRails.defer { ... }`；分组延迟 `InertiaRails.defer(group: 'name') { ... }`；一次性 `InertiaRails.once { ... }`；合并 `InertiaRails.merge { ... }`；深合并 `InertiaRails.deep_merge { ... }`；始终包含 `InertiaRails.always { ... }`；滚动 `InertiaRails.scroll { ... }`。
6. 所有 prop 辅助方法都是 `InertiaRails` 常量上的模块方法，必须写成 `InertiaRails.defer { ... }`，不要写成 `inertia.defer`、`Inertia.defer` 或 `inertia_rails.defer`。
7. 延迟 prop 的前端用法：页面组件用 `Deferred` 组件包裹并传 `data` 和 `fallback`，子组件通过 `usePage().props` 读取该 prop。
8. 共享数据用控制器中的 `inertia_share`（需要 `current_user`、request 等控制器上下文），支持静态值、lambda 和条件形式；多个 `inertia_share` 自上而下合并，子控制器同名 key 覆盖父控制器；block 和 lambda 按请求惰性求值，非 Inertia 请求不执行。
9. flash 自动处理；如需暴露自定义 key，在 `config/initializers/inertia_rails.rb` 中设置 `config.flash_keys = %i[notice alert toast]`（默认 `%i[notice alert]`），并同步更新 `FlashData` TypeScript 类型。
10. create/update/delete 后始终重定向（PRG）；校验失败时用 `redirect_back_or_to new_user_path, inertia: { errors: @user.errors.to_hash(true) }`。
11. 校验错误用 `errors.to_hash(true)`（如 `{ name: ["Name can't be blank"] }`），不要用 `errors.full_messages`（扁平字符串无字段 key，前端无法映射到输入框）；key 必须与输入的 `name` 属性完全匹配。
12. 外部 URL（Stripe、OAuth、SSO）必须用 `inertia_location url`（返回 409 + `X-Inertia-Location` 头），绝不能用 `redirect_to`（返回 302 会被 Inertia 客户端当 JSON 解析导致重定向失败）。
13. 授权作为 props 时传每个资源的 `can` hash，前端控制可见性、服务端强制访问；实现时阅读 `references/authorization.md`。
14. 历史加密：设置 `config.encrypt_history = Rails.env.production?`；登出或角色变更时用 `redirect_to path, inertia: { clear_history: true }`。
15. 配置项（version、encrypt_history、flash_keys 等）参考 `references/configuration.md`；使用高级 prop 类型（merge、scroll、deep_merge）或组合多个 prop 选项时阅读 `references/prop-types.md`。
16. 排障：Stripe/OAuth 302 循环用 `inertia_location`；错误不显示在字段旁检查 `to_hash` key 与输入 `name` 是否匹配；TS2305 找不到 `postsPath` 时在修改 `config/routes.rb` 后运行 `rails js_routes:generate`。

适用边界 · 注意事项

• 项目使用 alba-inertia gem 时实例变量会自动序列化为 props，无需显式 `render inertia:`（应参考 alba-inertia 技能）。
• 不向前端传递权限数据时不要加载 `references/authorization.md`。
• 基础 `defer`、`optional`、`once`、`always` 用法无需加载 `references/prop-types.md`；日常控制器工作无需加载 `references/configuration.md`。