remix

构建和审查 Remix 应用

查找上下文和文档

使用不熟悉的 Remix API 前，请阅读相关的已安装文档：

1. 阅读应用的 AGENTS.md、package.json 和 tsconfig.json，然后检查负责所要更改行为的代码。
2. 按任务、导出项或关键词搜索 node_modules/remix/INDEX.md，例如 grep -i 'session' node_modules/remix/INDEX.md。如需查找特定函数、类型或属性，请搜索 node_modules/remix/guides 和 node_modules/remix/src。
3. 根据索引找到相关工作流指南，然后查阅软件包 README，确认确切的导入、选项、行为和示例。如果没有相关指南，请使用 API README 和应用中现有的模式。

已安装的文档是权威依据，即使它与此技能中的内容不同，也应以其为准。不要依赖记忆中的 Remix 2 模式或较新版本的在线 API。如果安装中没有索引，请检查其 package.json 的导出项，以及匹配的已安装 README、源码和类型定义。

Remix 心智模型

Remix 基于 Request、Response、URL 和 FormData 等 Web API 构建。其 API 在运行时显式组合；不要假设存在基于文件的路由、生成的路由类型或强制的构建步骤。

路由、路由器和控制器

Remix 应用通常将路由拆分为三个部分：

• 路由定义 URL 和方法契约，包括类型化 URL 生成（入门模板中的 app/routes.ts）。
• 路由器连接路由、中间件和控制器（app/router.ts）。
• 控制器实现处理已匹配路由的操作（app/actions/）。

此组织方式适用于服务端应用，也适用于使用 SPA 路由器的浏览器应用。Remix 的各个部分可以组合和替换；使用其中一个不意味着必须采用其他部分。请遵循应用现有的选择；创建新应用时，采用文档中说明的入门模板约定。

最简的服务端路由可以返回纯 Web Response：

// app/routes.ts
import { get, route } from 'remix/routes'

export const routes = route({
  hello: get('/hello/:name'),
})

// app/actions/controller.ts
import { createController } from 'remix/router'

import { routes } from '../routes.ts'

export default createController(routes, {
  actions: {
    hello(context) {
      return new Response(`Hello, ${context.params.name}!`)
    },
  },
})

// app/router.ts
import { createRouter } from 'remix/router'

import controller from './actions/controller.ts'
import { routes } from './routes.ts'

export const router = createRouter()
router.map(routes, controller)

运行时适配器会将请求传递给 router.fetch(request)。请根据同一份路由契约生成 URL：routes.hello.href({ name: 'Remix' }) 会生成 /hello/Remix。

组件

Remix 组件使用 JSX，但并非 React。组件的 setup 函数在每个实例中运行一次，并返回一个渲染函数。setup 中的局部变量会在多次渲染之间保留状态；事件处理程序会更改该状态，并调用 handle.update() 请求再次渲染：

import { on } from 'remix/component'
import type { Handle } from 'remix/component'

function Counter(handle: Handle) {
  let count = 0

  return () => (
    <button
      type="button"
      mix={on('click', () => {
        count++
        handle.update()
      })}
    >
      Count: {count}
    </button>
  )
}

请在渲染期间从 handle.props 读取变化的属性，而不要在 setup 中捕获其初始值。不要套用 React hooks 或生命周期的假设。

事件处理程序只会在组件于浏览器中挂载或完成 hydration 后运行；仅由服务端渲染的 HTML 不具备交互性。请遵循已安装的交互指南和应用现有的浏览器入口设置。

在应用中开展工作

• 除非任务要求更改，否则请保留应用的包管理器、脚本、运行时、中间件顺序和导入约定。不要只为匹配入门模板而替换现有方案。
• 修改负责该行为的最小范围代码。将路由本地代码放在一起；只有在多个区域需要时才共享。
• 优先使用 Web API、原生链接、按钮和表单，以及现有的第一方 Remix 原语，而不是自定义抽象。
• 将浏览器可访问的模块视为公开内容：不要在其中放置机密或可信的服务端逻辑。在入门模板中，同目录的 public/ 目录表示浏览器可访问的源代码。

验证行为

使用应用的脚本进行相关测试和类型检查，然后直接验证更改后的行为。对于 UI 更改，请在浏览器中实际操作交互，而不仅仅是查看渲染后的外观。在增强服务端渲染页面时，请同时检查普通文档行为和增强路径。对于涉及不可信输入或访问控制的更改，请测试拒绝和失败路径。

使用已安装的测试指南了解测试模式，并使用 CLI 文档进行诊断。在结构或配置更改后运行 remix doctor；在应用修复之前先审查发现的问题。不要仅仅为了让诊断通过而运行破坏性数据库命令或重写配置。报告已检查的内容以及仍未验证的内容。