如何在HTML中动态加载SVG Sprite文件？（Webpack环境）

阿华AIGC实验室

2026-5-12

嘿，这个场景我太熟悉了！之前做项目的时候也纠结过SVG Sprite的加载方式，既要保持HTML干净，又要解决单个SVG加载延迟的问题，用Webpack完全能搞定，给你几个实用的方案：

方案1：通过JS动态插入内联Sprite（最推荐，无HTML杂乱+性能友好）

这个方法会把SVG Sprite打包进JS bundle，页面加载时自动把Sprite插入到<body>顶部，既不用手动修改HTML模板，也避免了单个SVG的加载延迟问题。

步骤：

安装依赖
先装处理SVG的loader（svgo-loader可选，用来压缩SVG体积）：
```
npm install svg-sprite-loader svgo-loader --save-dev
```

配置Webpack
在webpack.config.js里添加规则，指定处理你的Sprite文件：

const path = require('path');

module.exports = {
  // ...其他配置
  module: {
    rules: [
      {
        test: /\.svg$/,
        // 只匹配你的Sprite文件，避免影响其他SVG资源
        include: path.resolve(__dirname, 'src/assets/icons/sprite.svg'),
        use: [
          'svg-sprite-loader',
          'svgo-loader' // 可选，压缩SVG文件
        ]
      }
    ]
  }
};

在入口JS中导入并插入Sprite
找到你的项目入口文件（比如src/main.js），添加以下代码：

import sprite from './assets/icons/sprite.svg';

// 创建容器并插入Sprite到body最顶部
const spriteWrapper = document.createElement('div');
spriteWrapper.innerHTML = sprite;
// 隐藏Sprite容器，避免占用布局空间
spriteWrapper.style.display = 'none';
document.body.insertBefore(spriteWrapper, document.body.firstChild);

这样一来，Webpack会自动把Sprite打包进JS，页面加载时JS会把Sprite插入到<body>顶部，你之前的<svg class="u-icon-gear-dims"><use xlink:href="#gear"></use></svg>语法就能直接用了，HTML完全保持干净，而且Sprite和JS同步加载，不会有图标延迟的问题。

方案2：复制Sprite文件到输出目录，通过模板动态引用（适合需独立Sprite文件的场景）

如果希望Sprite作为独立文件存在（比如方便缓存复用），可以用这个方法，但要注意：跨文件的<use>引用存在浏览器兼容性和同域限制，不如方案1稳妥。

步骤：

安装依赖

npm install html-webpack-plugin copy-webpack-plugin --save-dev

配置Webpack

const HtmlWebpackPlugin = require('html-webpack-plugin');
const CopyWebpackPlugin = require('copy-webpack-plugin');
const path = require('path');

module.exports = {
  // ...其他配置
  plugins: [
    // 把Sprite文件复制到输出目录，添加哈希值优化缓存
    new CopyWebpackPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, 'src/assets/icons/sprite.svg'),
          to: 'sprite.[hash:8].svg'
        }
      ]
    }),
    // 生成HTML模板，动态插入Sprite引用
    new HtmlWebpackPlugin({
      template: './template.html',
      templateParameters: (compilation, assets) => {
        // 获取复制后的Sprite文件名
        const spriteFile = Object.values(assets.assetsInfo).find(item => item.name.includes('sprite'))?.name || '';
        return {
          spritePath: spriteFile ? `/${spriteFile}` : ''
        };
      }
    })
  ]
};

修改HTML模板
在template.html的<body>顶部添加模板语法，插入Sprite：

<body>
  <% if (spritePath) { %>
    <svg style="display: none;">
      <use xlink:href="<%= spritePath %>#gear"></use>
    </svg>
  <% } %>
  <!-- 页面其他内容 -->
</body>

方案3：用raw-loader直接加载SVG内容（简单粗暴版）

如果不想用svg-sprite-loader，也可以用raw-loader直接加载SVG的文本内容，然后插入到DOM：

步骤：

安装依赖
```
npm install raw-loader --save-dev
```

配置Webpack

module.exports = {
  // ...其他配置
  module: {
    rules: [
      {
        test: /\.svg$/,
        include: path.resolve(__dirname, 'src/assets/icons/sprite.svg'),
        use: 'raw-loader'
      }
    ]
  }
};

入口JS插入Sprite

import spriteContent from './assets/icons/sprite.svg';

const spriteElement = document.createElement('svg');
spriteElement.innerHTML = spriteContent;
spriteElement.style.display = 'none';
document.body.prepend(spriteElement);

内容的提问来源于stack exchange，提问作者mellis481