企业官网建设流程全解析

• CLI
• 后端
• 云原生

本篇技术指南基于当前仓库中的官方示例 examples/remix/README.md 展开，完整讲解如何用 Remix 官方 CLI 基于该模板创建项目、本地开发、并零配置部署到 Vercel，同时深入@vercel/remix与@vercel/remix-builder的源码实现，剖析"零配置"背后的 Vite Preset 机制与 Edge/Node 双运行时切换原理。读完本文，你将掌握一套可复制的 Remix + Vercel 从开发到上线的完整实战路径。

示例项目概览：一个开箱即用的 Remix 站点

仓库中的 examples/remix 是一个结构极简、可直接部署的 Remix 示例站点，其目录构成如下：

examples/remix/ ├── app/ │ ├── routes/ │ │ ├── _index.tsx # 首页路由 │ │ └── edge.tsx # Edge Runtime 演示路由 │ └── root.tsx # 根布局（含 Vercel Analytics） ├── public/ │ └── favicon.ico ├── README.md ├── package.json ├── tsconfig.json └── vite.config.ts

它没有vercel.json、没有手写的 Lambda 配置、也没有自定义构建脚本——这正是"零配置"（zero configuration）的含义：项目的构建、打包与运行时选择全部由 vite.config.ts 与 Vercel 的 Remix Builder 自动推导。

第一步：用 Remix CLI 基于模板创建项目

README 给出的起步方式是通过 Remix 官方 CLI 直接引用该模板生成新项目：

npx create-remix@latest --template vercel/vercel/examples/remix

执行后，CLI 会把本仓库examples/remix目录下的全部文件（app/、public/、package.json、tsconfig.json、vite.config.ts等）复制到新项目，并引导安装依赖。这意味着你得到的不是一个残缺的骨架，而是一个包含首页、Edge 路由、Vercel Analytics 注入与完整 TypeScript 配置的可运行项目。

本地开发：安装依赖并启动 Vite Dev Server

进入新项目目录后，先安装依赖：

npm install

随后启动 Remix 开发服务器：

npm run dev

按 README 说明，打开 http://localhost:5173 即可看到示例首页。端口 5173 正是 Vite 的默认端口——示例基于 Vite 生态（vite ^5.1.0）搭建，Remix 的 Vite 插件将开发服务器托管在 Vite 上。

项目脚本一览

从 examples/remix/package.json 可以看到三个核心脚本：

其中build是 Vercel 构建阶段自动识别的标准构建命令，与@vercel/remix-builder源码中buildCommand: 'remix build'的默认约定一致（见下文源码分析）。

部署到 Vercel：零配置的两种方式

README 提供了两种部署路径，均无需任何额外配置。

方式一：通过 Dashboard 一键部署

示例 README 顶部内嵌了Deploy with Vercel按钮（指向 Vercel 平台的模板克隆页），点击后 Vercel 会自动导入本示例仓库的examples/remix目录、识别为 Remix 框架并完成部署，同时提供了对应的在线演示站点（Live Example）供直接体验效果。

方式二：使用 Vercel CLI 部署

如果你希望从命令行完成部署，README 给出的流程是：

npm i -g vercel vercel

第一条命令全局安装 Vercel CLI；第二条命令在当前项目目录下执行，CLI 会依次引导你完成登录（如尚未登录）、关联项目等交互，随后上传代码并触发云端构建，首次部署成功后还会提示是否将当前目录与项目绑定以便后续增量部署。整个过程同样不需要手写任何配置文件。

"零配置"的底层原理：Vercel Vite Preset

示例真正特殊之处在于 vite.config.ts：

import { vitePlugin as remix } from "@remix-run/dev"; import { installGlobals } from "@remix-run/node"; import { defineConfig } from "vite"; import { vercelPreset } from "@vercel/remix/vite"; import tsconfigPaths from "vite-tsconfig-paths"; installGlobals(); export default defineConfig({ plugins: [remix({ presets: [vercelPreset()] }), tsconfigPaths()], });

关键在vercelPreset()这一行。它来自@vercel/remix（示例中固定版本2.10.0，见 package.json），作为 Remix Vite 插件的 preset 注入。Preset 会在构建期把 Remix 的路由清单（route manifest）、构建产物路径等元信息以 JSON 形式落盘到.vercel/remix-build-result.json，供 Vercel 云端构建器消费。

构建器侧的实现在 packages/remix/src/build-vite.ts，其中定义了REMIX_FRAMEWORK_SETTINGS：

• primaryPackageName: '@remix-run/dev'—— 以此包判定框架版本；
• buildCommand: 'remix build'—— 识别/执行的构建命令；
• buildResultFilePath: '.vercel/remix-build-result.json'—— 读取 preset 产出的构建元数据；
• sourceSearchValue: '@remix-run/dev/server-build'—— 用于定位服务端构建入口。

此外，仓库中的 packages/remix 即@vercel/remix-builder（当前版本 5.9.1，见 packages/remix/package.json），它负责读取上述构建结果，把 Remix 应用编译为 Vercel Functions 输出。由于 preset + builder 的组合自动完成了从"源码"到"可部署函数"的桥接，用户侧自然无需编写vercel.json或自定义 Serverless 适配代码。

运行时选择：Edge 与 Node 的双轨支持

示例在 app/routes/edge.tsx 中演示了 Remix 的运行时声明语法：

import type { MetaFunction } from "@vercel/remix"; export const config = { runtime: "edge" }; export const meta: MetaFunction = () => [{ title: "Remix@Edge | New Remix App" }]; export default function Edge() { return ( <div style={{ fontFamily: "system-ui, sans-serif", lineHeight: "1.4" }}> <h1>Welcome to Remix@Edge</h1> </div> ); }

通过export const config = { runtime: "edge" }，该路由在部署时会被编译为 Edge Function；而首页路由 app/routes/_index.tsx 未声明runtime，默认落入 Node.js 运行时。

这一判定逻辑在 packages/remix/src/build-vite.ts 的getRuntimeSettings中体现得十分直白：

getRuntimeSettings(runtime: string) { if (runtime === 'edge') { return this.edge; // 使用 default/server-edge.mjs 作为服务端入口 } return this.node; // 使用 default/server-node.mjs }

两种运行时分别对应packages/remix/defaults/目录下的 server-edge.mjs 与 server-node.mjs，最终产物为EdgeFunction或NodejsLambda。也就是说，一个 Remix 应用可以混合部署：普通页面跑 Node 运行时，需要极低冷启动与全球边缘响应的路由（如个性化、A/B 实验、地域化内容）切到 Edge 运行时，二者共存于同一次部署中。

根布局与 Web 分析注入

app/root.tsx 是示例的根布局，除了标准的Links、Meta、Outlet、ScrollRestoration、Scripts之外，还引入了：

import { Analytics } from "@vercel/analytics/react"; // ... <Analytics />

Analytics组件来自@vercel/analytics（示例中版本^1.2.2），在服务端渲染的 HTML 中注入 Vercel Web Analytics 脚本，页面加载后即可在 Vercel Dashboard 中看到访问统计，无需再接入第三方统计代码——这同样是"开箱即用"的一部分。

TypeScript 配置中的关键点

examples/remix/tsconfig.json 中值得注意的两处：

1. "types": ["@vercel/remix", "node", "vite/client"]—— 显式引入@vercel/remix的类型声明，因此_index.tsx、edge.tsx中可以直接从"@vercel/remix"导入MetaFunction类型，并获得config.runtime等 Vercel 扩展的提示与校验；
2. "paths": { "~/*": ["./app/*"] }—— 配置~/别名指向app/目录，配合vite-tsconfig-paths插件在 Vite 构建中生效，项目内引用~/routes/xxx这类路径无需相对跳转。

同时"noEmit": true表明类型检查与产物构建完全分离：实际产物由 Vite 产出，tsc仅承担类型校验职责（对应npm run typecheck）。

深入验证：仓库内的集成测试与更多示例

若想进一步验证本示例的行为，仓库在 packages/remix/test 下提供了大量集成测试夹具，覆盖了多种 Remix 形态：

• fixtures-legacy/—— 经典remix.config.js项目（含 pnpm、npm9、turborepo、monorepo 等变体，以及02-remix-basics中与示例同源的edge.tsx/index.tsx路由）；
• fixtures-vite/—— 基于 Vite 插件的项目（含04-spa-with-vercel-preset的 SPA + Vercel Preset 组合、自定义entry.server、singleFetch等场景）；
• fixtures-react-router/—— React Router（Remix 的姊妹框架）相关夹具，说明@vercel/remix-builder对两种框架采用同一套构建管线。

每个夹具都配有probes.json，用于断言部署后各路由的响应行为；integration-vite.test.ts、integration-legacy.test.ts等文件则是驱动这些断言的主测试入口。对照阅读 packages/remix/src/build-vite.ts 与这些测试，可以完整还原"Remix 应用如何在 Vercel 上被识别、构建并生成函数"的整条链路。

小结

从 examples/remix/README.md 的寥寥几步命令，到 vite.config.ts 中的vercelPreset()，再到 packages/remix/src/build-vite.ts 的构建器实现，一条清晰的链路贯穿始终：模板提供最小可运行结构 → Preset 在构建期产出元数据 → Builder 读取元数据并生成对应运行时的函数 → 部署即完成。对本示例而言，你唯一需要做的就是把npx create-remix@latest --template vercel/vercel/examples/remix、npm install、npm run dev以及vercel这几条命令跑起来。

• CLI
• 后端
• 云原生