Vite 是一个强大、高性能且可扩展的 JavaScript 项目开发环境。为了改进和扩展 Remix 的打包功能，我们现在支持 Vite 作为替代编译器。未来，Vite 将成为 Remix 的默认编译器。
现有的 Remix 编译器，通过 remix build 和 remix dev CLI 命令访问，并通过 remix.config.js 配置，现在被称为 “经典 Remix 编译器”。
Remix Vite 插件以及 remix vite:build 和 remix vite:dev CLI 命令统称为 “Remix Vite”。
未来，除非另有说明，否则文档将假定使用 Remix Vite。
我们提供了一些不同的基于 Vite 的模板供您入门。
# Minimal server:
npx create-remix@latest
# Express:
npx create-remix@latest --template remix-run/remix/templates/express
# Cloudflare:
npx create-remix@latest --template remix-run/remix/templates/cloudflare
# Cloudflare Workers:
npx create-remix@latest --template remix-run/remix/templates/cloudflare-workers
这些模板包含一个 vite.config.ts 文件，其中配置了 Remix Vite 插件。
Remix Vite 插件通过项目根目录下的 vite.config.ts 文件进行配置。有关更多信息，请参阅我们的Vite 配置文档。
要开始使用 Cloudflare，您可以使用 cloudflare 模板
npx create-remix@latest --template remix-run/remix/templates/cloudflare
有两种方式可以在本地运行您的 Cloudflare 应用程序
# Vite
remix vite:dev
# Wrangler
remix vite:build # build app before running wrangler
wrangler pages dev ./build/client
虽然 Vite 提供了更好的开发体验，但 Wrangler 通过在 Cloudflare 的 workerd 运行时 而不是 Node 中运行您的服务器代码，提供了对 Cloudflare 环境更接近的模拟。
为了在 Vite 中模拟 Cloudflare 环境，Wrangler 提供了 本地 workerd 绑定的 Node 代理。Remix 的 Cloudflare 代理插件为您设置这些代理
import {
vitePlugin as remix,
cloudflareDevProxyVitePlugin as remixCloudflareDevProxy,
} from "@remix-run/dev";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [remixCloudflareDevProxy(), remix()],
});
这些代理在您的 loader 或 action 函数中的 context.cloudflare 中可用
export const loader = ({ context }: LoaderFunctionArgs) => {
const { env, cf, ctx } = context.cloudflare;
// ... more loader code here...
};
请查看 Cloudflare 的 getPlatformProxy 文档，了解有关每个代理的更多信息。
要为 Cloudflare 资源配置绑定
每当您更改 wrangler.toml 文件时，您需要运行 wrangler types 以重新生成您的绑定。
然后，您可以通过 context.cloudflare.env 访问您的绑定。例如，对于一个绑定为 MY_KV 的 KV 命名空间。
export async function loader({
context,
}: LoaderFunctionArgs) {
const { MY_KV } = context.cloudflare.env;
const value = await MY_KV.get("my-key");
return json({ value });
}
如果您想向加载上下文中添加其他属性，您应该从一个共享模块中导出一个 getLoadContext 函数，以便 Vite、Wrangler 和 Cloudflare Pages 中的加载上下文都以相同的方式增强。
import { type AppLoadContext } from "@remix-run/cloudflare";
import { type PlatformProxy } from "wrangler";
// When using `wrangler.toml` to configure bindings,
// `wrangler types` will generate types for those bindings
// into the global `Env` interface.
// Need this empty interface so that typechecking passes
// even if no `wrangler.toml` exists.
interface Env {}
type Cloudflare = Omit<PlatformProxy<Env>, "dispose">;
declare module "@remix-run/cloudflare" {
interface AppLoadContext {
cloudflare: Cloudflare;
extra: string; // augmented
}
}
type GetLoadContext = (args: {
request: Request;
context: { cloudflare: Cloudflare }; // load context _before_ augmentation
}) => AppLoadContext;
// Shared implementation compatible with Vite, Wrangler, and Cloudflare Pages
export const getLoadContext: GetLoadContext = ({
context,
}) => {
return {
...context,
extra: "stuff",
};
};
getLoadContext 传递给 Cloudflare 代理插件 和 functions/[[path]].ts 中的请求处理程序，否则您将根据运行应用程序的方式获得不一致的加载上下文增强。
首先，在您的 Vite 配置中将 getLoadContext 传递给 Cloudflare 代理插件，以便在运行 Vite 时增强加载上下文。
import {
vitePlugin as remix,
cloudflareDevProxyVitePlugin as remixCloudflareDevProxy,
} from "@remix-run/dev";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";
import { getLoadContext } from "./load-context";
export default defineConfig({
plugins: [
remixCloudflareDevProxy({ getLoadContext }),
remix(),
],
});
接下来，在您的 functions/[[path]].ts 文件中将 getLoadContext 传递给请求处理程序，以便在运行 Wrangler 或部署到 Cloudflare Pages 时增强加载上下文。
import { createPagesFunctionHandler } from "@remix-run/cloudflare-pages";
// @ts-ignore - the server build file is generated by `remix vite:build`
import * as build from "../build/server";
import { getLoadContext } from "../load-context";
export const onRequest = createPagesFunctionHandler({
build,
getLoadContext,
});
Vite 处理客户端和服务器代码的混合使用方式与 Classic Remix 编译器不同。有关更多信息，请参阅我们关于拆分客户端和服务器代码的文档。
Vite 管理 public 目录的方式与现有的 Remix 编译器有明显的不同。Vite 将文件从 public 目录复制到客户端构建目录，而 Remix 编译器则保持 public 目录不变，并使用子目录 (public/build) 作为客户端构建目录。
为了使默认的 Remix 项目结构与 Vite 的工作方式保持一致，构建输出路径已更改。现在有一个单一的 buildDirectory 选项，默认为 "build"，取代了单独的 assetsBuildDirectory 和 serverBuildDirectory 选项。这意味着，默认情况下，服务器现在被编译到 build/server 中，客户端现在被编译到 build/client 中。
这也意味着以下配置默认值已更改
"/" 而不是 "/build/"。serverBuildFile 取代，其默认值为 "index.js"。此文件将写入您配置的 buildDirectory 中的服务器目录中。Remix 迁移到 Vite 的原因之一是让您在采用 Remix 时学习更少的内容。这意味着，对于您想要使用的任何其他捆绑功能，您应该参考 Vite 文档 和 Vite 插件社区，而不是 Remix 文档。
Vite 有许多 功能 和 插件，这些功能和插件没有内置在现有的 Remix 编译器中。使用任何此类功能都会导致现有的 Remix 编译器无法编译您的应用程序，因此只有当您打算从此以后完全使用 Vite 时才使用它们。
👉 将 Vite 作为开发依赖项安装
npm install -D vite
Remix 现在只是一个 Vite 插件，因此您需要将其连接到 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"],
}),
],
});
Vite 为 HMR 等开发功能提供了强大的客户端运行时，使 <LiveReload /> 组件过时。在开发中使用 Remix Vite 插件时，<Scripts /> 组件将自动包含 Vite 的客户端运行时和其他仅用于开发的脚本。
👉 删除 <LiveReload/>，保留 <Scripts />
import {
- LiveReload,
Outlet,
Scripts,
}
export default function App() {
return (
<html>
<head>
</head>
<body>
<Outlet />
- <LiveReload />
<Scripts />
</body>
</html>
)
}
Vite 处理各种不同文件类型的导入，有时方式与现有的 Remix 编译器不同，因此让我们从 vite/client 引用 Vite 的类型，而不是从 @remix-run/dev 引用过时的类型。
由于 vite/client 提供的模块类型与 @remix-run/dev 隐式包含的模块类型不兼容，因此您还需要在 TypeScript 配置中启用 skipLibCheck 标志。一旦 Vite 插件成为默认编译器，Remix 将来就不需要此标志。
👉 更新 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
如果您在开发中使用 remix-serve (或者在没有 -c 标志的情况下使用 remix dev)，则需要切换到新的最小开发服务器。它内置于 Remix Vite 插件中，当您运行 remix vite:dev 时，它将接管。
Remix Vite 插件不会安装任何 全局 Node polyfill，因此如果您依赖 remix-serve 来提供它们，则需要自己安装它们。最简单的方法是在您的 Vite 配置顶部调用 installGlobals。
Vite 开发服务器的默认端口与 remix-serve 不同，因此如果您想保持相同的端口，则需要通过 Vite 的 server.port 选项配置此端口。
您还需要更新到新的构建输出路径，服务器的路径为 build/server，客户端资产的路径为 build/client。
👉 更新您的 dev、build 和 start 脚本
{
"scripts": {
"dev": "remix vite:dev",
"build": "remix vite:build",
"start": "remix-serve ./build/server/index.js"
}
}
👉 在您的 Vite 配置中安装全局 Node polyfill
import { vitePlugin as remix } from "@remix-run/dev";
+import { installGlobals } from "@remix-run/node";
import { defineConfig } from "vite";
+installGlobals();
export default defineConfig({
plugins: [remix()],
});
👉 配置您的 Vite 开发服务器端口（可选）
export default defineConfig({
server: {
port: 3000,
},
plugins: [remix()],
});
如果您在开发中使用自定义服务器，则需要编辑您的自定义服务器以使用 Vite 的 connect 中间件。这将将资产请求和初始渲染请求委托给开发期间的 Vite，让您即使使用自定义服务器也能从 Vite 出色的 DX 中受益。
然后，您可以在开发期间加载名为 "virtual:remix/server-build" 的虚拟模块来创建基于 Vite 的请求处理程序。
您还需要更新您的服务器代码以引用新的构建输出路径，其中服务器构建的路径为 build/server，客户端资产的路径为 build/client。
例如，如果您使用的是 Express，这是您可以执行的操作。
👉 更新您的 server.mjs 文件
import { createRequestHandler } from "@remix-run/express";
import { installGlobals } from "@remix-run/node";
import express from "express";
installGlobals();
const viteDevServer =
process.env.NODE_ENV === "production"
? undefined
: await import("vite").then((vite) =>
vite.createServer({
server: { middlewareMode: true },
})
);
const app = express();
// handle asset requests
if (viteDevServer) {
app.use(viteDevServer.middlewares);
} else {
app.use(
"/assets",
express.static("build/client/assets", {
immutable: true,
maxAge: "1y",
})
);
}
app.use(express.static("build/client", { maxAge: "1h" }));
// handle SSR requests
app.all(
"*",
createRequestHandler({
build: viteDevServer
? () =>
viteDevServer.ssrLoadModule(
"virtual:remix/server-build"
)
: await import("./build/server/index.js"),
})
);
const port = 3000;
app.listen(port, () =>
console.log("https://127.0.0.1:" + port)
);
👉 更新您的 build、dev 和 start 脚本
{
"scripts": {
"dev": "node ./server.mjs",
"build": "remix vite:build",
"start": "cross-env NODE_ENV=production node ./server.mjs"
}
}
如果您愿意，您也可以使用 TypeScript 编写您的自定义服务器。然后，您可以使用诸如 tsx 或 tsm 之类的工具来运行您的自定义服务器
tsx ./server.ts
node --loader tsm ./server.ts
请记住，如果您这样做，初始服务器启动可能会有一些明显的减速。
Remix Vite 插件仅正式支持 Cloudflare Pages，该平台专为全栈应用程序设计，不同于 Cloudflare Workers Sites。如果您当前使用的是 Cloudflare Workers Sites，请参阅 Cloudflare Pages 迁移指南。
👉 在 remix 插件 之前 添加 cloudflareDevProxyVitePlugin，以正确覆盖 vite 开发服务器的中间件！
import {
vitePlugin as remix,
cloudflareDevProxyVitePlugin,
} from "@remix-run/dev";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [cloudflareDevProxyVitePlugin(), remix()],
});
您的 Cloudflare 应用程序可能正在设置 Remix Config server 字段以生成一个捕获所有 Cloudflare 函数。使用 Vite，不再需要这种间接性。相反，您可以直接为 Cloudflare 编写捕获所有路由，就像您为 Express 或任何其他自定义服务器编写路由一样。
👉 为 Remix 创建一个捕获所有路由
import { createPagesFunctionHandler } from "@remix-run/cloudflare-pages";
// @ts-ignore - the server build file is generated by `remix vite:build`
import * as build from "../build/server";
export const onRequest = createPagesFunctionHandler({
build,
});
👉 通过 context.cloudflare.env 而不是 context.env 访问绑定和环境变量
虽然您主要在开发期间使用 Vite，但您也可以使用 Wrangler 来预览和部署您的应用程序。
要了解更多信息，请参阅本文档的Cloudflare部分。
👉 更新您的 package.json 脚本
{
"scripts": {
"dev": "remix vite:dev",
"build": "remix vite:build",
"preview": "wrangler pages dev ./build/client",
"deploy": "wrangler pages deploy ./build/client"
}
}
当使用现有 Remix 编译器的默认选项时，服务器被编译到 build 中，客户端被编译到 public/build 中。由于 Vite 通常使用其 public 目录的方式与现有 Remix 编译器相比存在差异，这些输出路径已更改。
👉 更新对构建输出路径的引用
build/server 中。build/client 中。例如，要从 Blues Stack 更新 Dockerfile
-COPY --from=build /myapp/build /myapp/build
-COPY --from=build /myapp/public /myapp/public
+COPY --from=build /myapp/build/server /myapp/build/server
+COPY --from=build /myapp/build/client /myapp/build/client
Remix 编译器利用 tsconfig.json 中的 paths 选项来解析路径别名。这在 Remix 社区中很常用，用于将 ~ 定义为 app 目录的别名。
Vite 默认不提供任何路径别名。如果您依赖此功能，则可以安装 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-bundleVite 内置支持 CSS 副作用导入、PostCSS 和 CSS Modules 以及其他 CSS 捆绑功能。Remix Vite 插件会自动将捆绑的 CSS 附加到相关的路由。
@remix-run/css-bundle@remix-run/css-bundlecssBundleHref 导出将始终为 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 函数仅用于连接 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
.css?url 导入需要 Vite v5.1 或更高版本
-import styles from "~/styles/dashboard.css";
+import styles from "~/styles/dashboard.css?url";
export const links = () => {
return [
{ rel: "stylesheet", href: styles }
];
}
如果你的项目正在使用 Tailwind CSS，你首先需要确保你有一个 PostCSS 配置文件，该文件会被 Vite 自动识别。这是因为当启用 Remix 的 tailwind 选项时，Remix 编译器不需要 PostCSS 配置文件。
👉 如果缺少 PostCSS 配置文件，请添加，包括 tailwindcss 插件
export default {
plugins: {
tailwindcss: {},
},
};
如果你的项目已经有一个 PostCSS 配置文件，你需要添加 tailwindcss 插件（如果它尚未存在）。这是因为当启用 Remix 的 tailwind 配置选项时，Remix 编译器会自动包含此插件。
👉 如果缺少 tailwindcss 插件，请将其添加到你的 PostCSS 配置中
export default {
plugins: {
tailwindcss: {},
autoprefixer: {},
},
};
👉 迁移 Tailwind CSS 导入
如果你在 links 函数中引用你的 Tailwind CSS 文件，你需要迁移你的 Tailwind CSS 导入语句。
如果你正在使用 Vanilla Extract，你需要设置 Vite 插件。
👉 安装官方的 Vite 的 Vanilla Extract 插件
npm install -D @vanilla-extract/vite-plugin
👉 将 Vanilla Extract 插件添加到你的 Vite 配置中
import { vitePlugin as remix } from "@remix-run/dev";
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [remix(), vanillaExtractPlugin()],
});
如果你正在使用 MDX，由于 Vite 的插件 API 是 Rollup 插件 API 的扩展，你应该使用官方的 MDX Rollup 插件
👉 安装 MDX Rollup 插件
npm install -D @mdx-js/rollup
Remix 插件期望处理 JavaScript 或 TypeScript 文件，因此任何来自其他语言（如 MDX）的转译必须首先完成。在这种情况下，这意味着将 MDX 插件放在 Remix 插件之前。
👉 将 MDX Rollup 插件添加到你的 Vite 配置中
import mdx from "@mdx-js/rollup";
import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [mdx(), remix()],
});
Remix 编译器允许你在 MDX 中定义 frontmatter。如果你正在使用此功能，你可以在 Vite 中使用 remark-mdx-frontmatter 来实现此目的。
👉 安装所需的 Remark frontmatter 插件
npm install -D remark-frontmatter remark-mdx-frontmatter
👉 将 Remark frontmatter 插件传递给 MDX Rollup 插件
import mdx from "@mdx-js/rollup";
import { vitePlugin as remix } from "@remix-run/dev";
import remarkFrontmatter from "remark-frontmatter";
import remarkMdxFrontmatter from "remark-mdx-frontmatter";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [
mdx({
remarkPlugins: [
remarkFrontmatter,
remarkMdxFrontmatter,
],
}),
remix(),
],
});
在 Remix 编译器中，frontmatter 导出名为 attributes。这与 frontmatter 插件的默认导出名称 frontmatter 不同。虽然可以配置 frontmatter 导出名称，但我们建议更新你的应用程序代码以使用默认导出名称。
👉 在 MDX 文件中将 MDX attributes 导出重命名为 frontmatter
---
title: Hello, World!
---
- # {attributes.title}
+ # {frontmatter.title}
👉 对于使用者，将 MDX attributes 导出重命名为 frontmatter
import Component, {
- attributes,
+ frontmatter,
} from "./posts/first-post.mdx";
👉 将 *.mdx 文件的类型添加到 env.d.ts
/// <reference types="@remix-run/node" />
/// <reference types="vite/client" />
declare module "*.mdx" {
let MDXComponent: (props: any) => JSX.Element;
export const frontmatter: any;
export default MDXComponent;
}
Remix 编译器允许你在 frontmatter 中定义 headers、meta 和 handle 路由导出。remark-mdx-frontmatter 插件显然不支持这个 Remix 特有的功能。如果你正在使用此功能，你应该手动将 frontmatter 映射到路由导出。
👉 将 MDX 路由的 frontmatter 映射到路由导出
---
meta:
- title: My First Post
- name: description
content: Isn't this awesome?
headers:
Cache-Control: no-cache
---
export const meta = frontmatter.meta;
export const headers = frontmatter.headers;
# Hello World
请注意，由于你显式地映射 MDX 路由导出，你现在可以自由地使用你喜欢的任何 frontmatter 结构。
---
title: My First Post
description: Isn't this awesome?
---
export const meta = () => {
return [
{ title: frontmatter.title },
{
name: "description",
content: frontmatter.description,
},
];
};
# Hello World
Remix 编译器还提供了所有 MDX 文件的 filename 导出。这主要是为了启用链接到 MDX 路由集合。如果你正在使用此功能，你可以通过 glob 导入 在 Vite 中实现此目的，它为你提供了一个方便的数据结构，将文件名映射到模块。这使得维护 MDX 文件列表更容易，因为你不再需要手动导入每个文件。
例如，要导入 posts 目录中的所有 MDX 文件
const posts = import.meta.glob("./posts/*.mdx");
这相当于手动编写
const posts = {
"./posts/a.mdx": () => import("./posts/a.mdx"),
"./posts/b.mdx": () => import("./posts/b.mdx"),
"./posts/c.mdx": () => import("./posts/c.mdx"),
// etc.
};
如果你愿意，你也可以急切地导入所有 MDX 文件
const posts = import.meta.glob("./posts/*.mdx", {
eager: true,
});
你可以使用 NODE_OPTIONS 环境变量 来启动调试会话
NODE_OPTIONS="--inspect-brk" npm run dev
然后你可以从浏览器附加调试器。例如，在 Chrome 中，你可以打开 chrome://inspect 或单击开发工具中的 NodeJS 图标以附加调试器。
vite-plugin-inspect 会向你展示每个 Vite 插件如何转换你的代码以及每个插件花费的时间。
Remix 包含一个用于性能分析的 --profile 标志。
remix vite:build --profile
当使用 --profile 运行时，将生成一个 .cpuprofile 文件，可以共享或上传到 speedscope.app 进行分析。
你也可以在开发模式下通过按 p + enter 来进行分析，当开发服务器运行时，可以启动新的分析会话或停止当前会话。如果需要分析开发服务器的启动，你也可以使用 --profile 标志在启动时初始化分析会话
remix vite:dev --profile
请记住，你始终可以查看 Vite 性能文档以获取更多提示！
要可视化和分析你的捆绑包，你可以使用 rollup-plugin-visualizer 插件
import { vitePlugin as remix } from "@remix-run/dev";
import { visualizer } from "rollup-plugin-visualizer";
export default defineConfig({
plugins: [
remix(),
// `emitFile` is necessary since Remix builds more than one bundle!
visualizer({ emitFile: true }),
],
});
然后，当你运行 remix vite:build 时，它将在你的每个捆绑包中生成一个 stats.html 文件
build
├── client
│ ├── assets/
│ ├── favicon.ico
│ └── stats.html 👈
└── server
├── index.js
└── stats.html 👈
在浏览器中打开 stats.html 以分析你的捆绑包。
请查看调试和性能部分以获取常规故障排除提示。另外，请通过查看 github 上 remix vite 插件的已知问题，看看是否有人遇到类似的问题。
如果你期望热更新但却得到完整的页面重新加载，请查看我们的 关于热模块替换的讨论，以了解有关 React Fast Refresh 的限制以及常见问题的解决方法。
Vite 支持 ESM 和 CJS 依赖，但有时你仍然可能会遇到 ESM / CJS 互操作问题。通常，这是因为依赖项未正确配置以支持 ESM。我们不会责怪他们，正确支持 ESM 和 CJS 真的很难。
有关修复示例错误的演练，请查看 🎥 如何修复 Remix 中的 CJS/ESM 错误。
要诊断你的某个依赖项是否配置错误，请查看 publint 或 Are The Types Wrong。此外，你可以使用 vite-plugin-cjs-interop 插件 来平滑外部 CJS 依赖项的 default 导出的问题。
最后，你还可以显式配置哪些依赖项与 Vite 的 ssr.noExternal 选项一起打包到你的服务器中，以模拟 Remix 编译器的 serverDependenciesToBundle 和 Remix Vite 插件。
如果你在开发期间在浏览器控制台中看到指向服务器代码的错误，你可能需要显式隔离仅服务器代码。例如，如果你看到类似
Uncaught ReferenceError: process is not defined
那么你需要找出哪个模块正在拉入依赖项，这些依赖项期望使用仅服务器全局变量（如 process），并使用单独的 .server 模块或使用 vite-env-only隔离代码。由于 Vite 使用 Rollup 在生产环境中 treeshake 你的代码，因此这些错误仅在开发中发生。
Remix Vite 插件仅用于应用程序的开发服务器和生产构建。虽然还有其他基于 Vite 的工具（如 Vitest 和 Storybook）使用了 Vite 配置文件，但 Remix Vite 插件并未设计用于这些工具。我们目前建议在使用其他基于 Vite 的工具时排除该插件。
对于 Vitest
import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig, loadEnv } from "vite";
export default defineConfig({
plugins: [!process.env.VITEST && remix()],
test: {
environment: "happy-dom",
// Additionally, this is to load ".env.test" during vitest
env: loadEnv("test", process.cwd(), ""),
},
});
对于 Storybook
import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";
const isStorybook = process.argv[1]?.includes("storybook");
export default defineConfig({
plugins: [!isStorybook && remix()],
});
或者，你可以为每个工具使用单独的 Vite 配置文件。例如，要使用专门针对 Remix 的 Vite 配置
remix vite:dev --config vite.config.remix.ts
在不提供 Remix Vite 插件时，你的设置可能还需要提供 Vite Plugin React。例如，当使用 Vitest 时
import { vitePlugin as remix } from "@remix-run/dev";
import react from "@vitejs/plugin-react";
import { defineConfig, loadEnv } from "vite";
export default defineConfig({
plugins: [!process.env.VITEST ? remix() : react()],
test: {
environment: "happy-dom",
// Additionally, this is to load ".env.test" during vitest
env: loadEnv("test", process.cwd(), ""),
},
});
当 React 用于渲染整个文档（如 Remix 所做的那样）时，你可能会在将元素动态注入到 head 元素时遇到问题。如果文档被重新挂载，则现有的 head 元素将被删除并替换为一个全新的元素，从而删除 Vite 在开发期间注入的任何 style 元素。
这是一个已知的 React 问题，已在他们的canary 发布渠道中修复。如果你了解所涉及的风险，你可以将你的应用程序固定到特定的 React 版本，然后使用package overrides 来确保这是整个项目中使用的唯一 React 版本。例如
{
"dependencies": {
"react": "18.3.0-canary-...",
"react-dom": "18.3.0-canary-..."
},
"overrides": {
"react": "18.3.0-canary-...",
"react-dom": "18.3.0-canary-..."
}
}
值得强调的是，Vite 注入的样式出现此问题仅在开发中发生。生产构建不会有此问题，因为会生成静态 CSS 文件。
在 Remix 中，当你的 根路由的默认组件导出与其 ErrorBoundary 和/或 HydrateFallback 导出之间交替渲染时，可能会出现此问题，因为这会导致挂载新的文档级组件。
它也可能由于 hydration 错误而发生，因为它会导致 React 从头开始重新渲染整个页面。hydration 错误可能是由你的应用程序代码引起的，但也可能是由操作文档的浏览器扩展引起的。
这对 Vite 来说很重要，因为在开发过程中，Vite 会将 CSS 导入转换为 JS 文件，这些 JS 文件会将样式作为副作用注入到文档中。Vite 这样做是为了支持静态 CSS 文件的延迟加载和 HMR（热模块替换）。
例如，假设你的应用程序有以下 CSS 文件
* { margin: 0 }
在开发过程中，当作为副作用导入时，此 CSS 文件将被转换为以下 JavaScript 代码
import {createHotContext as __vite__createHotContext} from "/@vite/client";
import.meta.hot = __vite__createHotContext("/app/styles.css");
import {updateStyle as __vite__updateStyle, removeStyle as __vite__removeStyle} from "/@vite/client";
const __vite__id = "/path/to/app/styles.css";
const __vite__css = "*{margin:0}"
__vite__updateStyle(__vite__id, __vite__css);
import.meta.hot.accept();
import.meta.hot.prune(()=>__vite__removeStyle(__vite__id));
这种转换不会应用于生产代码，这就是为什么这个样式问题只会影响开发环境。
当使用 Cloudflare Pages 时，你可能会在 wrangler pages dev 中遇到以下错误
ERROR: Your worker called response.clone(), but did not read the body of both clones.
This is wasteful, as it forces the system to buffer the entire response body
in memory, rather than streaming it through. This may cause your worker to be
unexpectedly terminated for going over the memory limit. If you only meant to
copy the response headers and metadata (e.g. in order to be able to modify
them), use `new Response(response.body, response)` instead.
这是一个Wrangler 已知的问题。
Vite 是一个令人惊叹的项目，我们感谢 Vite 团队所做的工作。特别感谢 来自 Vite 团队的 Matias Capeletto、Arnaud Barré 和 Bjorn Lu 的指导。
Remix 社区很快开始探索对 Vite 的支持，我们感谢他们的贡献
最后，我们受到了其他框架如何实现 Vite 支持的启发
