SvelteKit中无需CDN script标签本地引入Ionicons的方案

你之前几次尝试失败的核心原因有三个：

1. ionicons 是纯浏览器端的自定义元素库，代码中直接依赖window、document等浏览器DOM API，在SvelteKit的SSR服务端渲染阶段执行会直接报错
2. 官方npm包默认输出的ESM/UMD版本采用了动态分块加载设计，依赖import.meta.url或运行时路径拼接拉取分块资源，Vite打包时无法正确识别这类动态导入的路径规则，会出现资源404、URL构造失败的问题
3. 直接引入CDN脚本出现布局偏移，本质是自定义元素未注册前，<ion-icon>标签没有默认宽高，JS加载完成后才被替换为SVG内容撑开尺寸，导致页面位移

下面给两个可落地的本地引入方案，完全不需要依赖CDN，也不需要用第三方封装包：

方案一：极简自封装SVG组件（推荐，零布局偏移、无运行时冗余） #

这个方案完全不需要引入ionicons的自定义元素运行时，直接复用npm包内的SVG图标源数据，自己封装一个仅几行代码的Svelte组件，图标直接以SVG形式渲染，没有任何额外JS加载开销，从根源上避免闪烁和布局偏移，同时完全兼容原有图标命名规则。

1. 首先安装ionicons依赖：

pnpm add ionicons
# 或 npm install ionicons

2. 新建src/lib/Icon.svelte组件，写入如下代码：

<script>
  export let name = '';
  // 按需加载对应图标SVG数据，Vite/Rollup可正常解析该动态导入规则
  $: iconPromise = import(`ionicons/icons/${name}.js`).then(mod => mod.default);
</script>

{#await iconPromise then svgContent}
  {@html svgContent}
{/await}

<style>
  :global(svg) {
    width: 1em;
    height: 1em;
    fill: currentColor;
    vertical-align: -0.125em;
    display: inline-block;
  }
</style>

3. 使用方式和官方组件完全一致，只需要把原有<ion-icon name="xxx" />替换为<Icon name="xxx" />即可，图标名不需要做任何修改，比如<Icon name="heart" />就能正常渲染心形图标。
   该方案会在构建时自动按需打包用到的图标，不会全量引入所有图标资源，体积最小，渲染无延迟。

方案二：本地静态资源引入（完全保留官方用法，无需修改业务标签） #

如果不想替换现有业务代码里的<ion-icon>标签，可以把ionicons的静态资源复制到本地项目静态目录，直接引入本地脚本，不走CDN，配合预设CSS彻底解决布局偏移问题。

1. 安装ionicons依赖后，修改vite.config.js，添加一个自定义插件，每次启动/构建时自动把ionicons的静态文件复制到项目静态目录，不需要手动操作：

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import fs from 'node:fs';
import path from 'node:path';

// 自动复制ionicons静态资源的自定义插件
function copyIoniconsAssets() {
  const srcPath = path.resolve(process.cwd(), 'node_modules/ionicons/dist/ionicons');
  const destPath = path.resolve(process.cwd(), 'static/ionicons');
  return {
    name: 'copy-ionicons-assets',
    buildStart() {
      // 递归复制资源，Node 16+ 原生支持cpSync
      fs.cpSync(srcPath, destPath, { recursive: true });
    }
  };
}

export default defineConfig({
  plugins: [sveltekit(), copyIoniconsAssets()]
});

2. 在根布局src/routes/+layout.svelte中引入本地脚本，同时预设ion-icon的默认样式，避免布局偏移：

<svelte:head>
  <!-- 引入本地静态脚本，不走CDN -->
  <script type="module" src="/ionicons/ionicons.esm.js"></script>
  <script nomodule src="/ionicons/ionicons.js"></script>
</svelte:head>

<!-- 全局预设ion-icon尺寸，未加载JS时也占据正确空间，彻底消除布局偏移 -->
<svelte:head>
  <style>
    ion-icon {
      display: inline-block;
      width: 1em;
      height: 1em;
      vertical-align: -0.125em;
      contain: layout size style;
    }
  </style>
</svelte:head>

配置完成后，原有写的<ion-icon name="xxx" />标签可以完全保留不用修改，脚本从本地同域静态资源加载，速度远快于CDN，配合预设的CSS尺寸，不会出现加载闪烁和布局位移。

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