未来标志和弃用

本指南将引导您完成在 Remix 应用中采用未来标志的过程。通过遵循此策略，您将能够以最少的更改升级到 Remix 的下一个主要版本。要了解有关未来标志的更多信息，请参阅开发策略。

我们强烈建议您在每个步骤后进行提交并发布，而不是一次完成所有操作。大多数标志可以按任何顺序采用，下面会注明例外情况。

更新到最新的 v2.x

首先更新到 v2.x 的最新次要版本，以获得最新的未来标志。您在升级时可能会看到许多弃用警告，我们将在下面介绍。

👉 更新到最新的 v2

npm install @remix-run/{dev,react,node,etc.}@2

移除 `installGlobals`

背景

以前 Remix 需要安装 fetch polyfill。这是通过调用 installGlobals() 完成的。

下一个主要版本要求 Node 20 或更高版本，以利用内置的 fetch 支持。

注意：如果您将 miniflare/cloudflare worker 与您的 remix 项目一起使用，请确保您的兼容性标志也设置为 2023-03-01 或更高版本。

👉 更新到 Node 20+

建议您升级到最新的偶数编号的 Node LTS 版本。

👉 移除 installGlobals

import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";

-installGlobals();

export default defineConfig({
  plugins: [remix()],
});

采用 Vite 插件

背景

Remix 不再使用其自身的、封闭的编译器（现在称为“经典编译器”），而是使用 Vite。Vite 是一个功能强大、高性能且可扩展的 JavaScript 项目开发环境。有关性能、故障排除等更多信息，请查看 Vite 文档。

虽然这不是一个未来标志，但新功能和某些功能标志仅在 Vite 插件中可用，经典编译器将在下一个 Remix 版本中删除。

👉 安装 Vite

npm install -D vite

更新你的代码

👉 将你 Remix 应用程序根目录下的 remix.config.js 替换为 vite.config.ts

import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [remix()],
});

受支持的 Remix 配置选项的子集应直接传递给插件

export default defineConfig({
  plugins: [
    remix({
      ignoredRouteFiles: ["**/*.css"],
    }),
  ],
});

👉 添加 unstable_optimizeDeps（可选）

许多用户发现自动优化依赖项可以帮助他们更容易地采用 Vite 插件。因此，我们在 Vite 插件中添加了 unstable_optimizeDeps 标志。

在 React Router v7 发布之前，此标志将保持“不稳定”状态，因此在升级到 React Router v7 之前，在 Remix v2 应用程序中采用此标志并非至关重要。

export default defineConfig({
  plugins: [
    remix({
      future: {
        unstable_optimizeDeps: true,
      },
    }),
  ],
});

👉 删除 <LiveReload/>，保留 <Scripts />

  import {
-   LiveReload,
    Outlet,
    Scripts,
  }

  export default function App() {
    return (
      <html>
        <head>
        </head>
        <body>
          <Outlet />
-         <LiveReload />
          <Scripts />
        </body>
      </html>
    )
  }

👉 更新 tsconfig.json

更新 tsconfig.json 中的 types 字段，并确保 skipLibCheck、module 和 moduleResolution 都已正确设置。

{
  "compilerOptions": {
    "types": ["@remix-run/node", "vite/client"],
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "Bundler"
  }
}

👉 更新/删除 remix.env.d.ts

删除 remix.env.d.ts 中的以下类型声明

- /// <reference types="@remix-run/dev" />
- /// <reference types="@remix-run/node" />

如果 remix.env.d.ts 现在为空，请删除它

rm remix.env.d.ts

配置路径别名

Vite 默认不提供任何路径别名。如果你依赖此功能（例如，将 ~ 定义为 app 目录的别名），你可以安装 vite-tsconfig-paths 插件，以自动解析 Vite 中 tsconfig.json 中的路径别名，使其与 Remix 编译器的行为一致。

👉 安装 vite-tsconfig-paths

npm install -D vite-tsconfig-paths

👉 将 vite-tsconfig-paths 添加到你的 Vite 配置中

import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  plugins: [remix(), tsconfigPaths()],
});

删除 @remix-run/css-bundle

Vite 内置了对 CSS 副作用导入、PostCSS 和 CSS 模块等 CSS 打包功能的支持。Remix Vite 插件会自动将打包的 CSS 附加到相关的路由。

当使用 Vite 时，@remix-run/css-bundle包是多余的，因为它的 cssBundleHref 导出将始终为 undefined。

👉 卸载 @remix-run/css-bundle

npm uninstall @remix-run/css-bundle

👉 删除对 cssBundleHref 的引用

- import { cssBundleHref } from "@remix-run/css-bundle";
  import type { LinksFunction } from "@remix-run/node"; // or cloudflare/deno

  export const links: LinksFunction = () => [
-   ...(cssBundleHref
-     ? [{ rel: "stylesheet", href: cssBundleHref }]
-     : []),
    // ...
  ];

修复 links 中引用的 CSS 导入

如果你在 links 函数中引用 CSS，则需要更新相应的 CSS 导入以使用 Vite 的显式 ?url 导入语法。

👉 在 links 中使用的 CSS 导入中添加 ?url

-import styles from "~/styles/dashboard.css";
+import styles from "~/styles/dashboard.css?url";

export const links = () => {
  return [
    { rel: "stylesheet", href: styles }
  ];
}

迁移 Tailwind CSS 或 Vanilla Extract

如果你正在使用 Tailwind CSS 或 Vanilla Extract，请参阅完整迁移指南。

从 Remix App Server 迁移

👉 更新你的 dev、build 和 start 脚本

{
  "scripts": {
    "dev": "remix vite:dev",
    "build": "remix vite:build",
    "start": "remix-serve ./build/server/index.js"
  }
}

👉 配置你的 Vite 开发服务器端口（可选）

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [remix()],
});

迁移自定义服务器

如果你正在迁移客户服务器或 Cloudflare Functions，请参阅完整迁移指南。

迁移 MDX 路由

如果你正在使用 MDX，则应使用官方的 MDX Rollup 插件。有关分步演练，请参阅完整迁移指南。

v3_fetcherPersist

背景

fetcher 生命周期现在基于它返回到空闲状态的时间，而不是它的所有者组件卸载的时间：有关更多信息，请查看 RFC。

👉 启用标志

remix({
  future: {
    v3_fetcherPersist: true,
  },
});

更新你的代码

这不太可能影响你的应用程序。你可能需要检查 useFetchers 的任何用法，因为它们可能会比以前持续更长时间。根据你正在执行的操作，你可能会渲染比以前更长的内容。

v3_relativeSplatPath

背景

更改多段 splats 路径（如 dashboard/*（与仅 * 相对））的相对路径匹配和链接。有关更多信息，请查看 CHANGELOG。

👉 启用标志

remix({
  future: {
    v3_relativeSplatPath: true,
  },
});

更新你的代码

如果你有任何带有路径 + splat 的路由，如 dashboard.$.tsx 或 route("dashboard/*")，并且在其下方有诸如 <Link to="relative"> 或 <Link to="../relative"> 之类的相对链接，则你需要更新你的代码。

👉 将路由拆分为两个

对于任何 splat 路由，将其拆分为布局路由和带有 splat 的子路由


└── routes
    ├── _index.tsx
+   ├── dashboard.tsx
    └── dashboard.$.tsx

// or
routes(defineRoutes) {
  return defineRoutes((route) => {
    route("/", "home/route.tsx", { index: true });
-    route("dashboard/*", "dashboard/route.tsx")
+    route("dashboard", "dashboard/layout.tsx", () => {
+      route("*", "dashboard/route.tsx");
    });
  });
},

👉 更新相对链接

更新该路由树中带有相对链接的任何 <Link> 元素，以包含额外的 .. 相对段，以便继续链接到同一位置

// dashboard.$.tsx or dashboard/route.tsx
function Dashboard() {
  return (
    <div>
      <h2>Dashboard</h2>
      <nav>
-        <Link to="">Dashboard Home</Link>
-        <Link to="team">Team</Link>
-        <Link to="projects">Projects</Link>
+        <Link to="../">Dashboard Home</Link>
+        <Link to="../team">Team</Link>
+        <Link to="../projects">Projects</Link>
      </nav>
    </div>
  );
}

v3_throwAbortReason

背景

当服务器端请求被中止时（例如，用户在加载器完成之前离开页面），Remix 将抛出 request.signal.reason，而不是诸如 new Error("query() call aborted...") 之类的错误。

👉 启用标志

remix({
  future: {
    v3_throwAbortReason: true,
  },
});

更新你的代码

你可能不需要调整任何代码，除非你在 handleError 中有自定义逻辑来匹配之前的错误消息，以便将其与其他错误区分开来。

v3_lazyRouteDiscovery

背景

启用此标志后，Remix 不再在初始加载时将完整路由清单发送到客户端。相反，Remix 仅在清单中发送服务器渲染的路由，然后在用户在应用程序中导航时获取其余路由。有关更多详细信息，请参阅文档和博客文章

👉 启用标志

remix({
  future: {
    v3_lazyRouteDiscovery: true,
  },
});

更新你的代码

你无需对应用程序代码进行任何更改即可使此功能正常工作。

如果你希望禁用某些链接上的急切路由发现，你可能会发现新的 <Link discover> API 的某些用法。

v3_singleFetch

此标志需要Vite 插件。

背景

启用此标志后，Remix 在客户端导航期间使用单个 fetch 进行数据请求。这通过将数据请求视为与文档请求相同的方式来简化数据加载，从而无需以不同方式处理标头和缓存。对于高级用例，你仍然可以选择进行细粒度的重新验证。有关更多信息，请查看“Single Fetch”文档。

👉 启用标志（和类型）

import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";

declare module "@remix-run/node" {
  // or cloudflare, deno, etc.
  interface Future {
    v3_singleFetch: true;
  }
}

export default defineConfig({
  plugins: [
    remix({
      future: {
        v3_singleFetch: true,
      },
    }),
    tsconfigPaths(),
  ],
});

更新你的代码

启用该标志后，你应该能够基本上按原样使用你的代码，但应随着时间的推移进行以下更改，并且在下一个主要版本之前是必需的。

👉 删除 json()/defer()，改为使用原始对象

Single Fetch 开箱即用地支持 JSON 对象和 Promise，因此你可以从 loader/action 函数返回原始数据

-import { json } from "@remix-run/node";

export async function loader({}: LoaderFunctionArgs) {
  let tasks = await fetchTasks();
- return json(tasks);
+ return tasks;
}

-import { defer } from "@remix-run/node";

export async function loader({}: LoaderFunctionArgs) {
  let lazyStuff = fetchLazyStuff();
  let tasks = await fetchTasks();
- return defer({ tasks, lazyStuff });
+ return { tasks, lazyStuff };
}

如果你使用 json/defer 的第二个参数在你的响应上设置自定义状态或标头，你可以继续通过新的 data API 执行此操作

-import { json } from "@remix-run/node";
+import { data } from "@remix-run/node";

export async function loader({}: LoaderFunctionArgs) {
  let tasks = await fetchTasks();
-  return json(tasks, {
+  return data(tasks, {
    headers: {
      "Cache-Control": "public, max-age=604800"
    }
  });
}

👉 调整你的服务器中止延迟

如果你在你的 entry.server.tsx 文件中使用了自定义的 ABORT_DELAY，则应将其更改为使用 Single Fetch 利用的新 streamTimeout API

-const ABORT_DELAY = 5000;
+// Reject/cancel all pending promises after 5 seconds
+export const streamTimeout = 5000;

// ...

function handleBrowserRequest(/* ... */) {
  return new Promise((resolve, reject) => {
    const { pipe, abort } = renderToPipeableStream(
      <RemixServer
        context={remixContext}
        url={request.url}
-        abortDelay={ABORT_DELAY}
      />,
      {
        onShellReady() {
          /* ... */
        },
        onShellError(error: unknown) {
          /* ... */
        },
        onError(error: unknown) {
          /* ... */
        },
      }
    );

-    setTimeout(abort, ABORT_DELAY);
+   // Automatically timeout the React renderer after 6 seconds, which ensures
+   // React has enough time to flush down the rejected boundary contents
+   setTimeout(abort, streamTimeout + 1000);
  });
}

v3_routeConfig

此标志需要Vite 插件。

基于配置的路由是 React Router v7 中的新默认设置，通过 app 目录中的 routes.ts 文件进行配置。Remix 中对 routes.ts 及其相关 API 的支持被设计为一种迁移路径，以帮助最大程度地减少将你的 Remix 项目转移到 React Router v7 时所需的更改数量。虽然在 @remix-run 范围内引入了一些新包，但这些新包的存在只是为了使 routes.ts 中的代码尽可能与 React Router v7 的等效代码相似。

启用 v3_routeConfig 未来标志后，Remix 的内置文件系统路由将被禁用，你的项目将选择加入 React Router v7 的基于配置的路由。如果你希望继续使用 Remix 的基于文件的路由，我们将在下面的 routes.ts 中介绍如何启用它。

更新你的代码

要将 Remix 的文件系统路由和路由配置迁移到 React Router v7 中的等效设置，你可以按照以下步骤操作

👉 启用标志

remix({
  future: {
    v3_routeConfig: true,
  },
});

👉 安装 @remix-run/route-config

此包与 React Router v7 的 @react-router/dev/routes 的 API 匹配，使 React Router v7 迁移尽可能容易。

npm install -D @remix-run/route-config

这提供了核心的 RouteConfig 类型，以及一组用于在代码中配置路由的助手。

👉 添加一个不带任何配置路由的 app/routes.ts 文件

touch app/routes.ts

import type { RouteConfig } from "@remix-run/route-config";

export default [] satisfies RouteConfig;

这是检查你的新 routes.ts 文件是否被成功拾取的良好方法。由于尚未定义任何路由，你的应用程序现在应呈现空白页。

👉 安装 @remix-run/fs-routes 并在 routes.ts 中使用它

npm install -D @remix-run/fs-routes

此包与 React Router v7 的 @react-router/fs-routes 的 API 匹配，使 React Router v7 迁移尽可能容易。

如果已将 ignoredRouteFiles 配置为 ["**/*"]，则应跳过此步骤，因为你已选择退出 Remix 的文件系统路由。

import { flatRoutes } from "@remix-run/fs-routes";

export default flatRoutes();

👉 如果你使用了 routes 配置选项，请添加 @remix-run/routes-option-adapter 并在 routes.ts 中使用它

Remix 提供了一种在代码中定义路由并插入替代文件系统路由约定（可通过 Vite 插件上的 routes 选项获得）的机制。

为了使迁移更容易，提供了一个适配器包，该适配器包将 Remix 的 routes 选项转换为 React Router 的 RouteConfig 数组。

首先，安装适配器

npm install -D @remix-run/routes-option-adapter

此包与 React Router v7 的 @react-router/remix-routes-option-adapter 的 API 匹配，使 React Router v7 迁移尽可能容易。

然后，更新你的 routes.ts 文件以使用适配器，将你的 routes 选项的值传递给 remixRoutesOptionAdapter 函数，该函数将返回一个配置的路由数组。

例如，如果你使用 routes 选项来使用替代文件系统路由实现，例如 remix-flat-routes

import { type RouteConfig } from "@remix-run/route-config";
import { remixRoutesOptionAdapter } from "@remix-run/routes-option-adapter";
import { flatRoutes } from "remix-flat-routes";

export default remixRoutesOptionAdapter((defineRoutes) =>
  flatRoutes("routes", defineRoutes)
) satisfies RouteConfig;

或者，如果你使用 routes 选项来定义基于配置的路由

import { flatRoutes } from "@remix-run/fs-routes";
import { type RouteConfig } from "@remix-run/route-config";
import { remixRoutesOptionAdapter } from "@remix-run/routes-option-adapter";

export default remixRoutesOptionAdapter((defineRoutes) => {
  return defineRoutes((route) => {
    route("/", "home/route.tsx", { index: true });
    route("about", "about/route.tsx");
    route("", "concerts/layout.tsx", () => {
      route("trending", "concerts/trending.tsx");
      route(":city", "concerts/city.tsx");
    });
  });
}) satisfies RouteConfig;

如果你以这种方式定义基于配置的路由，则可能需要考虑迁移到新的路由配置 API，因为它更精简，同时仍然与旧 API 非常相似。例如，上面的路由将如下所示

import {
  type RouteConfig,
  route,
  layout,
  index,
} from "@remix-run/route-config";

export default [
  index("home/route.tsx"),
  route("about", "about/route.tsx"),
  layout("concerts/layout.tsx", [
    route("trending", "concerts/trending.tsx"),
    route(":city", "concerts/city.tsx"),
  ]),
] satisfies RouteConfig;

请注意，如果你需要混合和匹配不同的路由配置方法，则可以将它们合并为一个路由数组。RouteConfig 类型可确保所有内容仍然有效。

import { flatRoutes } from "@remix-run/fs-routes";
import type { RouteConfig } from "@remix-run/route-config";
import { route } from "@remix-run/route-config";
import { remixRoutesOptionAdapter } from "@remix-run/routes-option-adapter";

export default [
  ...(await flatRoutes({ rootDirectory: "fs-routes" })),

  ...(await remixRoutesOptionAdapter(/* ... */)),

  route("/hello", "routes/hello.tsx"),
] satisfies RouteConfig;

弃用

@remix-run/eslint-config

@remix-run/eslint-config 包已弃用，并且不会包含在 React Router v7 中。我们建议你转向简化的 ESLint 配置，例如 Remix 模板中包含的配置。

json

此实用程序已弃用，并且将在 React Router v7 中删除，以支持Single Fetch裸对象返回。

如果你不依赖 json 来序列化你的数据（例如字符串化 Date 对象），则可以安全地删除它。
如果你之前通过 json 返回 headers 或 status，你可以使用新的 data 工具作为直接替代来设置这些值。
如果你想将数据序列化为 JSON，你可以使用原生的 Response.json() 方法。

查看 Single Fetch 文档以获取更多信息。

defer

此实用程序已弃用，并且将在 React Router v7 中删除，以支持Single Fetch裸对象返回。

如果你之前通过 defer 返回 headers 或 status，你可以使用新的 data 工具作为直接替代来设置这些值。

查看 Single Fetch 文档以获取更多信息。

SerializeFrom

此类型已弃用，将在 React Router v7 中移除，因为 Single Fetch 不再将数据序列化为 JSON。

如果你依赖 SerializeFrom 来解包你的 loader/action 数据，你可以使用如下的自定义类型

type SerializeFrom<T> = ReturnType<typeof useLoaderData<T>>;

在大多数情况下，你应该可以直接移除 SerializeFrom，并使用从 useLoaderData/useActionData 返回的类型，或者 loader/action 函数中数据的类型。

多部分表单数据和文件上传工具

以下工具已被弃用，将在 React Router v7 中移除

unstable_parseMultipartFormData
unstable_composeUploadHandlers
unstable_createFileUploadHandler
unstable_createMemoryUploadHandler

我们建议使用 @mjackson/form-data-parser 和 @mjackson/file-storage 来处理多部分表单数据和文件上传。

你还可以查看 React Router “文件上传” 文档或 “使用 Remix 进行文件上传” 博客文章，以获取有关使用这些库的指南。

未来标志和弃用

更新到最新的 v2.x

移除 installGlobals

采用 Vite 插件

v3_fetcherPersist

v3_relativeSplatPath

v3_throwAbortReason

v3_lazyRouteDiscovery

v3_singleFetch

v3_routeConfig

弃用

@remix-run/eslint-config

json

defer

SerializeFrom

多部分表单数据和文件上传工具

移除 `installGlobals`