使用vite-plugin-html在 HTML 文件中动态注入数据，如元数据、环境变量、标题

news2025/6/6 12:10:29

vite-plugin-html 是一个用于 Vite 构建工具的插件，它可以帮助你在构建过程中动态注入一些 HTML 内容，比如标题、元数据、环境变量等。通过使用这个插件，你可以根据项目的配置和环境变量自动生成带有动态内容的 HTML 文件，适用于 SEO、社交分享和其他需要动态设置 HTML 元素的场景。

元数据是什么

元数据（Metadata）是描述数据的数据，通常用于提供关于其他数据的详细信息。它并不是实际的内容本身，而是帮助解释、管理和分类这些内容的信息。在 Web 开发中，元数据通常指的是在 HTML 文档的部分使用的标签，来描述网页内容的性质、提供网页的附加信息，或者优化搜索引擎等。

常见的元数据标签

标签：这是最常见的元数据标签，用于提供关于网页的描述、关键词、作者等信息。

示例：

<meta name="description" content="这是一个示例网站，用于展示元数据的使用。">
<meta name="author" content="John Doe">
<meta name="keywords" content="HTML, 元数据, 网站">

标签：用来设置网页的标题，这个标题会在浏览器的标签栏显示。

示例：

<title>我的网站</title>

标签：常用于引入外部资源，如样式表（CSS）、图标等。也可以提供网页与其他文档或网站的关系信息。

示例：

<link rel="stylesheet" href="styles.css">
<link rel="icon" href="favicon.ico">

标签与 Open Graph（OG）协议：用于社交媒体分享时提供更丰富的内容（如 Facebook、Twitter）。

示例：

<meta property="og:title" content="分享标题">
<meta property="og:description" content="分享描述内容">
<meta property="og:image" content="分享图片链接">

标签与 Twitter 卡片（Twitter Cards）：用于在 Twitter 上分享时展示更多的格式化内容。

示例：

<meta name="twitter:title" content="Twitter 标题">
<meta name="twitter:description" content="Twitter 描述内容">
<meta name="twitter:image" content="Twitter 图片链接">

元数据的作用

搜索引擎优化（SEO）：通过设置正确的标签，可以帮助搜索引擎更好地理解网页内容，提高网页的可见性。
社交媒体分享：使用 Open Graph 和 Twitter Card 等协议，能让网页在社交媒体上分享时呈现更好的视觉效果和丰富的信息。
浏览器和设备兼容性：元数据可以设置网页如何在不同设备上显示（例如，设置视口宽度）。
提升用户体验：元数据可以让页面在用户访问时提供更多的描述信息，比如网页的语言、作者等。

为什么需要 vite-plugin-html？

在使用 Vite 进行项目开发时，很多时候需要根据不同的环境（如开发环境和生产环境）动态调整 HTML 文件中的内容。例如：

根据环境变量设置页面标题、描述或其他 meta 信息；
自动注入一些全局的 JavaScript 变量；
使用外部脚本或样式文件链接；
动态加载一些根据构建环境调整的内容。

1. 安装 vite-plugin-html

首先，你需要安装 vite-plugin-html 插件：

npm install vite-plugin-html --save-dev

或者使用 yarn：

yarn add vite-plugin-html --dev

2. 使用 vite-plugin-html

在 vite.config.js 或 vite.config.ts 配置文件中，你可以按如下方式使用插件：

import { defineConfig } from 'vite';
import createHtmlPlugin from 'vite-plugin-html';

export default defineConfig({
  plugins: [
    createHtmlPlugin({
      inject: {
        // 动态注入的内容
        data: {
          title: 'My Awesome Project',  // 设置页面标题
          description: 'This is an awesome project built with Vite.',  // 设置页面描述
          customVar: process.env.NODE_ENV === 'production' ? 'prod' : 'dev',  // 基于环境设置的自定义变量
        },
      },
    }),
  ],
});

3. 插件功能和配置

**inject：**用于注入动态内容到 HTML 文件中。你可以将动态数据（如环境变量、标题、描述等）通过 data 对象注入。
title: 设置 HTML 页面标签的内容。
description: 可以设置页面的标签内容。
customVar: 你还可以注入任意的变量，甚至是来自环境变量的数据，进行更复杂的动态注入。

**动态注入内容：**你可以使用 env 变量或者其他配置数据来动态修改 HTML 中的内容。例如，可以通过 process.env 来获取当前的构建环境，或者根据不同的需求设置不同的元数据。

高级用法
使用模板
你还可以将 HTML 文件模板作为输入，将内容插入到指定的位置。比如，下面的配置演示了如何使用模板文件：

import { defineConfig } from 'vite';
import createHtmlPlugin from 'vite-plugin-html';

export default defineConfig({
  plugins: [
    createHtmlPlugin({
      inject: {
        data: {
          title: 'Dynamic Title',
          description: 'Dynamic description from environment variables',
        },
      },
      minify: true, // 可以启用 HTML 最小化
      injectData: {
        customVar: process.env.NODE_ENV === 'production' ? 'production' : 'development',
      },
    }),
  ],
});

自定义模板
如果你需要自定义 HTML 模板，可以使用一个指定的模板文件：

import { defineConfig } from 'vite';
import createHtmlPlugin from 'vite-plugin-html';

export default defineConfig({
  plugins: [
    createHtmlPlugin({
      inject: {
        data: {
          title: 'My Custom Template',
          description: 'Description of my custom template',
        },
      },
      template: 'src/index.template.html', // 指定自定义模板路径
    }),
  ],
});

4 示例：基于环境变量注入

你可以使用环境变量来控制 HTML 中的内容，比如：

 plugins: [
    createHtmlPlugin({
      inject: {
        data: {
          title: env.DOMAIN_NAME,  // 基于环境的动态页面标题
          imageMeta: `https://www.${env.DOMAIN_NAME}.com/img/${env.DOMAIN_NAME}/img/ic_launcher.webp`,  // 动态图片 URL
          localeMeta: env.CURRENT_LANGUAGE,  // 当前网站的语言
          titleMeta: env.DOMAIN_NAME + ' ' + ruleMap[env.RULE_TYPE].meta.title,  // 自定义标题，基于规则
          descriptionMeta: ruleMap[env.RULE_TYPE].meta.description,  // 来自 ruleMap 的描述
        },
      },
    }),
  ],

   <title><%- title %></title>

    <meta property="og:type" content="website">
    <meta property="og:image" content="<%- imageMeta %>">
    <meta property="og:locale" content="<%- localeMeta %>">
    <meta property="og:title" content="<%- titleMeta %>">
    <meta property="og:description" content="<%- descriptionMeta %>">