后端集成

相关源文件

• docs/guide/backend-integration.md
• packages/vite/src/node/plugins/manifest.ts
• packages/vite/src/node/ssr/ssrManifestPlugin.ts
• playground/backend-integration/__tests__/backend-integration.spec.ts
• playground/backend-integration/dir/foo.css
• playground/backend-integration/frontend/entrypoints/foo.pcss
• playground/backend-integration/frontend/entrypoints/main.ts
• playground/backend-integration/frontend/entrypoints/water-container.svg
• playground/backend-integration/frontend/styles/url.css
• playground/backend-integration/vite.config.js
• playground/css-sourcemap/vite.config.js
• playground/css/manual-chunk.css
• playground/multiple-entrypoints/vite.config.js
• playground/tailwind/vite.config.ts
• playground/test-utils.ts

本文档涵盖了 Vite 的后端集成系统，该系统允许传统的服务器端框架（如 Rails、Laravel、Django 等）在使用 Vite 进行资源打包和开发的同时，仍由后端服务器提供 HTML。该系统会生成映射文件，将源文件与其最终构建的资源进行关联，从而使后端服务器能够正确地包含带有缓存清除哈希值的 CSS 和 JavaScript 文件。

有关将 Vite 作为主要服务器进行服务器端渲染（SSR）的信息，请参阅 服务器端渲染。

概述

Vite 的后端集成解决了将现代前端工具与传统后端框架结合使用所面临的挑战。在开发过程中，后端提供 HTML，而 Vite 运行一个单独的开发服务器来处理资源。在生产环境中，Vite 生成映射文件，告知后端具体哪个构建资源对应哪个入口点。

来源： docs/guide/backend-integration.md1-196 playground/backend-integration/vite.config.js1-59

映射生成系统

映射插件生成一个 JSON 文件，该文件将源入口点与其最终构建的资源进行映射，包括所有依赖项、CSS 文件和导入的资源。

位于 packages/vite/src/node/plugins/manifest.ts30-194 中的 manifestPlugin 函数在 generateBundle 钩子期间生成映射。它处理 Rollup bundle 中的每个 chunk，并创建具有以下结构的 ManifestChunk 对象：

属性	类型	描述
file	字符串	最终带哈希的文件名
src	字符串	原始源路径
css	string[]	关联的 CSS 文件
assets（资源）	string[]	引用的静态资源
imports	string[]	静态导入的 chunk
dynamicImports	string[]	动态导入的 chunk
isEntry	布尔值	是否为入口点
isDynamicEntry	布尔值	是否为动态入口点

来源： packages/vite/src/node/plugins/manifest.ts15-28 packages/vite/src/node/plugins/manifest.ts82-120

SSR 映射系统

对于服务器端渲染应用程序，Vite 会生成一个额外的 SSR 映射，有助于为特定模块预加载资源。

位于 packages/vite/src/node/ssr/ssrManifestPlugin.ts19-116 中的 ssrManifestPlugin 函数创建了从模块 ID 到其关联的预加载资源的映射。这使得 SSR 框架能够知道在服务器渲染特定模块时应预加载哪些 CSS 和 JavaScript 文件。

来源： packages/vite/src/node/ssr/ssrManifestPlugin.ts19-116 packages/vite/src/node/ssr/ssrManifestPlugin.ts55-104

开发工作流

在开发过程中，后端框架提供的 HTML 会包含直接指向 Vite 开发服务器的 script 标签。

配置

Vite 配置必须启用 CORS 并设置正确的 origin

HTML 模板集成

后端模板包含这些特定于开发的 script 标签

对于使用 @vitejs/plugin-react 的 React 应用程序，React Refresh 需要额外的设置

来源： docs/guide/backend-integration.md39-64 playground/backend-integration/vite.config.js28-33

生产工作流

在生产环境中，后端读取生成的映射文件，以确定为每个入口点包含哪些资源。

映射结构示例

资源解析算法

后端必须遵循此算法来包含所有必需的资源

1. 对于入口点 chunk，包含其 css 数组中的所有 CSS 文件
2. 递归地跟随 imports 数组中的所有 chunk，并包含它们的 CSS 文件
3. 从入口点的 file 属性中包含主脚本文件
4. 可选地为导入的 JavaScript chunk 包含 <link rel="modulepreload"> 标签

来源： docs/guide/backend-integration.md132-142 docs/guide/backend-integration.md162-195

配置选项

后端集成通过几个配置选项进行控制

构建配置

选项	类型	描述
build.manifest	boolean | string	启用映射生成，可选择指定文件名
build.ssrManifest	boolean | string	启用 SSR 映射生成
build.rollupOptions.input	对象	定义入口点

服务器配置

选项	类型	描述
server.cors.origin	字符串	后端服务器的 CORS URL
server.origin	字符串	Vite 服务器的资源解析 URL

模块预加载 Polyfill

使用映射时，请在您的入口点中包含模块预加载 polyfill

此 polyfill 可确保在不同浏览器中具有正确的模块预加载行为。

来源： docs/guide/backend-integration.md9-37 playground/backend-integration/frontend/entrypoints/main.ts1

测试基础设施

后端集成系统在 playground 中包含了完善的测试基础设施

测试配置

位于 playground/backend-integration/vite.config.js9-53 中的 BackendIntegrationExample 插件演示了一个完整的后端集成设置

• 使用 globSync 进行动态入口点发现
• 自定义输出目录结构
• 前端源代码的别名配置
• 具有固定端口的服务器配置，用于测试

映射验证

位于 playground/backend-integration/__tests__/backend-integration.spec.ts48-100 验证了

• 正确的映射结构和入口点映射
• CSS 资源与 JavaScript 入口点的关联
• 无空 chunk 的资源文件生成
• 跨平台路径处理（Windows 兼容性）

来源： playground/backend-integration/vite.config.js9-53 playground/backend-integration/__tests__/backend-integration.spec.ts48-100