1.1 什么是 Remix
Remix 是一个基于 Web 平台标准的全栈 React 框架。它由 React Router 的原班人马（Ryan Florence 和 Michael Jackson）于 2020 年创建，2022 年被 Shopify 收购，并于同年开源。Remix 的核心理念只有一句话：与 Web 标准协同工作，而非对抗它。
大多数现代框架都会在浏览器 API 之上发明新的数据获取抽象（如 Next.js 的 getServerSideProps、SWR、React Query）。Remix 走了相反的路——它直接使用浏览器原生的 fetch、Request、Response、FormData、URLSearchParams，服务端运行的代码与浏览器的心智模型完全一致。
React Router v7 = Remix2024 年，Remix 与 React Router 正式合并。Remix v2 的核心特性已全部并入 React Router v7，未来 Remix 品牌将用于指代"框架模式"，React Router v7 既可作为客户端路由库使用，也可开启框架模式获得完整的 SSR/Loader/Action 能力。本教程以 Remix v2 API 讲解，与 React Router v7 框架模式完全等价。
1.2 Remix vs Next.js 核心差异
Remix 和 Next.js 都是优秀的全栈 React 框架，但它们的设计哲学截然不同。
Next.js（Vercel 出品）
- React Server Components 优先
- 自定义缓存 API（fetch 扩展）
- Server Actions（直接调用服务端函数）
- 强调零 JS 的 RSC 渲染
- Turbopack 构建工具
- 与 Vercel 平台深度绑定
- 页面级数据获取模型
Remix（Shopify 出品）
- Web 标准 API 优先
- 浏览器原生 HTTP 缓存
- Action + HTML Form（无 JS 也工作）
- 强调渐进增强
- Vite 构建工具
- 适配器体系，平台无关
- 嵌套路由级数据获取模型
| 维度 | Next.js | Remix |
|---|---|---|
| 渲染模型 | RSC + Client Components | SSR + 客户端 hydration |
| 数据获取 | async Server Component | loader 函数 |
| 数据变更 | Server Actions | action 函数 + Form |
| 路由嵌套 | layout.tsx 布局嵌套 | Outlet 嵌套路由 |
| 错误处理 | error.tsx | 每条路由 ErrorBoundary |
| 无 JS 降级 | 有限支持 | 完整渐进增强 |
| 部署目标 | 偏向 Vercel/Node | Node/边缘/CF Workers |
选型建议如果你的团队熟悉 React Server Components 并主要部署在 Vercel，选 Next.js；如果你更看重 Web 标准、渐进增强、多平台部署灵活性，或有 Shopify/电商场景，选 Remix。两者都是顶级框架，各有所长。
1.3 Shopify 收购与 React Router v7 历史
理解 Remix 的发展历史，有助于理解它当前的技术状态和生态走向。
- 2020年：Ryan Florence 和 Michael Jackson（React Router 作者）开始开发 Remix，最初是付费框架
- 2021年10月：Remix v1 发布，随即开源
- 2022年10月：Shopify 宣布收购 Remix 团队，原团队留任继续开发，Remix 仍然开源
- 2023年9月：Remix v2 发布，引入 Vite 构建、扁平路由约定
- 2024年：Remix 与 React Router 宣布合并，所有 Remix 特性将并入 React Router v7
- 现在：React Router v7 框架模式 = Remix v2，生态逐步统一
Shopify HydrogenShopify 将 Remix 作为其电商前端框架 Hydrogen 的底层。这意味着 Remix 在生产环境中服务着全球数百万 Shopify 店铺，框架的稳定性和性能经过了大规模验证。
1.4 安装与创建项目
使用官方脚手架创建 Remix 项目，只需一条命令即可开始。
# 创建新的 Remix 项目
npx create-remix@latest my-remix-app
# 交互提示：
# ? Initialize a new git repository? Yes
# ? Install dependencies with npm? Yes
# 进入目录并启动开发服务器
cd my-remix-app
npm run dev
# 访问 http://localhost:5173 （Vite 默认端口）
SHELL# 使用 pnpm（推荐）
pnpm create remix@latest my-remix-app
# 直接使用模板（如 Indie Stack：含 SQLite + Prisma + auth）
npx create-remix@latest --template remix-run/indie-stack my-app
SHELL官方模板 StackRemix 提供三个官方模板：Indie Stack（SQLite + Prisma + Fly.io，适合独立开发者）、Blues Stack（PostgreSQL + Prisma，生产级）、Grunge Stack（AWS + DynamoDB，云原生）。初学者推荐 Indie Stack 快速上手。
1.5 项目结构解析
Remix 项目的目录结构以 app/ 为核心，所有路由和业务逻辑都在这里。
my-remix-app/
├── app/
│ ├── root.tsx # 根路由（HTML 骨架 + 全局 layout）
│ ├── entry.client.tsx # 客户端入口（hydration）
│ ├── entry.server.tsx # 服务端入口（SSR 渲染）
│ └── routes/ # 所有路由文件在这里
│ ├── _index.tsx # 首页 /
│ ├── blog.tsx # /blog 布局
│ └── blog.$slug.tsx # /blog/:slug 动态路由
├── public/ # 静态资源
├── package.json
├── remix.config.js # Remix 配置（v2 使用 vite.config.ts）
└── vite.config.ts # Vite 配置
STRUCTUREroot.tsx — 应用根节点
app/root.tsx 是整个应用的 HTML 骨架，等价于 Next.js 的 app/layout.tsx，但它同时也是一条路由，可以导出 loader 和 ErrorBoundary。
// app/root.tsx
import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";
export default function App() {
return (
<html lang="zh-CN">
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<Meta /> {/* 路由 meta export 插入点 */}
<Links /> {/* 路由 links export 插入点 */}
</head>
<body>
<Outlet /> {/* 子路由渲染位置 */}
<ScrollRestoration />
<Scripts />
</body>
</html>
);
}
TSX1.6 开发服务器与热更新
Remix v2 使用 Vite 作为构建工具，开发体验极快。
# 开发模式（HMR 热更新）
npm run dev
# 生产构建
npm run build
# 本地预览生产构建
npm run start
# 类型检查
npm run typecheck
SHELLVite 插件模式Remix v2 将自身实现为一个 Vite 插件（vitePlugin），这意味着你可以充分利用 Vite 的插件生态（如 SVG 处理、环境变量注入等），同时享受 Vite 的极速 HMR。
1.7 核心术语名词解释
-
Loader
路由的服务端数据加载函数。每条路由可以导出一个
loader函数，在页面渲染前于服务端执行，返回数据供组件使用。类比 Next.js 的getServerSideProps，但更简洁。 - Action 路由的服务端数据变更函数。处理表单 POST、PUT、DELETE 请求，执行数据库写入、重定向等副作用。HTML Form 提交时自动调用。
- 嵌套路由 Remix 的核心特性。子路由可以嵌套在父路由的布局中，每层路由有独立的 loader，并行加载数据，UI 和数据结构完全对应。
- Outlet 来自 React Router 的组件，用于在父路由组件中标记子路由的渲染位置，是实现嵌套路由 UI 的关键。
- 渐进增强 在没有 JavaScript 的情况下，Remix 应用仍然可以正常工作（HTML Form 提交到 Action，服务端渲染页面返回）。JavaScript 的作用是增强用户体验（无刷新提交、乐观 UI），而非依赖。
- 水合 (Hydration) 服务端渲染返回静态 HTML 后，React 在客户端接管（attach event listeners），使页面具备交互能力的过程。Remix 的每次导航都是服务端渲染，然后在客户端水合。
- 资源路由 只导出 loader/action 而不导出默认组件的路由，相当于 API 端点，返回 JSON、图片、RSS 等任意内容。
-
Fetcher
useFetcherHook，允许在不导航的情况下调用 loader 或 action，实现局部数据加载/提交，如点赞、收藏等交互。
本章小结Remix 是一个"Web 标准优先"的全栈框架，以 Loader（读）和 Action（写）两个函数构建完整的数据流。核心优势：嵌套路由的并行数据加载、HTML Form 的渐进增强、以及通过适配器体系支持多种部署目标。下一章将深入学习 Remix 的文件系统路由约定。