Bootstrap 5 不再内置图标，推荐两种方案：一是使用官方 bootstrap-icons 库，需注意引入顺序、类名前缀及实心/线框区分；二是内联 SVG 代码并设 fill="currentColor" 和 viewBox，以实现颜色、动画及对齐控制。
Bootstrap 5 不再内置图标，所谓“添加自定义图标”，本质是你自己决定用什么方案加载 SVG 或字体，并绕过任何“自动集成”幻想。最稳的路径只有两条：用 bootstrap-icons 官方库快速上手，或把 SVG 内联进 HTML 实现完全可控的颜色与动画。
用 bootstrap-icons 是最快但必须守规矩的做法
它不是 Bootstrap 的一部分，而是独立 CSS 库，引入顺序、类名、加载方式错一个，图标就静默消失。
-
<link>标签必须放在 Bootstrap CSS 之后，否则color、font-size继承会失效 - 类名必须带
bi-前缀，比如搜索是bi-search，不是icon-search或fa-search - 实心/线框是不同图标，
bi-heart和bi-heart-fill不能混用，也不能靠删后缀来“变实心” - Vue/Vite/Angular 项目里，别把 CSS
@import写在组件 scoped style 里——它不会全局生效
内联 SVG 才能真正控制颜色、动画和响应式缩放
直接 <img src="icon.svg"> 会错位、不继承文字颜色、hover 变色做不到——因为它是图片，不是文本流的一部分。
- 必须把 SVG 代码复制进 HTML，写成
<svg></svg>，且每个<path></path>的fill设为currentColor -
viewBox必须显式声明，推荐统一用"0 0 16 16"，再用width="1em" height="1em"控制尺寸 - 加
class="align-middle"或style="vertical-align: -0.125em;"对齐文字基线，baseline默认值会让图标挂得太高 - 按钮里放图标时，别套
<i></i>—— Bootstrap 的.i类是为字体图标设计的，对 SVG 无效甚至干扰布局
别踩这些常见坑
很多“图标不显示”问题根本不是代码写错，而是路径、加载时机或 CSS 作用域导致的静默失败。
- 从
bootstrap-iconsnpm 包里复制 SVG 源码时，检查有没有硬编码的fill="#000"，必须手动改成currentColor - 用 Webpack/Vite 时，别直接
importSVG 文件当组件（除非配了?raw），否则打包后路径可能 404 - 多个图标库共存（比如同时引了 Font Awesome 和 bootstrap-icons），CSS 优先级冲突会导致图标字体被覆盖，此时加
font-family: 'bootstrap-icons' !important能临时救急 - 暗色模式下图标没变色？不是图标库问题，是你的
color没继承到——检查父元素是否设了color，以及 SVG 是否漏了fill="currentColor"
真正麻烦的从来不是“怎么加一个图标”，而是让图标在所有尺寸、所有主题、所有框架上下文里都保持对齐、变色、可聚焦——这些细节没被封装进任何 class 里，得你一条条校验。
