lucide-react 图标库安装与定制速查
项目地址: https://gitcode.com/GitHub_Trending/lu/lucide lucide-react 是开源图标库 Lucide 的 React 官方实现，每个图标都是即插即用的 React 组件。本文覆盖安装、逐参数调样式、全局风格二选一、常见坑位，以及从 react-feather 迁移的完整路径。
30 秒跑通：安装 lucide-react 并渲染第一个图标
在已有 React 工程（Vite、CRA 均可）根目录执行任意一种安装命令：
pnpm add lucide-react
# 或 npm install lucide-react / yarn add / bun add
然后写第一个图标，两行就出图：
import { Camera } from 'lucide-react';
export default function App() {
return <Camera />;
}
因为只导入了 Camera，最终产物里也只有这一个图标——package.json 里声明了 "sideEffects": false，打包器会自动把没用到的图标摇掉，新项目老项目都能装（peer 依赖覆盖 React 16.5 到 19）。
逐项调参：尺寸、颜色与描边宽度
尺寸 size。默认 24，调它时图标宽高一起变：
<Landmark size={64} />
不想写 prop 的话，也可以用 CSS 的 width / height 控制，甚至写成 1em 让图标跟着父级字号伸缩——"图标 + 文字"并排的场景最实用。
颜色 color。默认值是 currentColor，白话讲就是"图标自动跟随文字颜色"：父元素是红色，图标就是红色，不用额外设置。想单独指定就传 color="#3e9392"。
描边宽度 strokeWidth。全套图标都是线条画出来的（SVG 的 stroke，即"描边"），默认 2，传 1 会更纤细：
<FolderLock strokeWidth={1} />
固定线条 nonScalingStroke。图标放大时线条默认等比变粗，设成 true 后无论多大线条都保持 2px 不变。旧写法 absoluteStrokeWidth 已标记废弃，新代码直接用前者：
<RollerCoaster size={96} nonScalingStroke />
全局风格二选一：CSS 还是 LucideProvider
项目里图标一多，逐处传 prop 就很痛苦。官方给了两条路（细节见 docs/guide/react/advanced/global-styling.md）：
路线一：CSS。 每个图标都带 lucide 这个 class，一条选择器管住全家：
.lucide {
color: #ffadff;
width: 56px;
height: 56px;
stroke-width: 1px;
}
官方最推荐这条路，简单直接。代价是：CSS 优先级会盖掉单个图标上的 size、color、strokeWidth prop，个别图标想破例就没法用了。
路线二：LucideProvider。 用上下文给整棵子树注入默认值，同时仍允许单个图标用自己的 prop 覆盖：
<LucideProvider color="red" size={48} strokeWidth={2}>
<Home />
</LucideProvider>
内部遵循"显式 prop > Provider 值 > 默认值"的优先级，className 也会合并而不是互相覆盖。
选型规则一句话：要全项目一刀切、不需要例外，走 CSS；要统一基调但保留个别定制空间，走 LucideProvider。
容易踩的坑
⚠️ 把 DynamicIcon 当万能入口。 拿它加载全部图标时，构建会把整库图标都拉进来，网络请求变多、加载时可能闪烁，SSR 首次渲染还可能取不到值。静态场景老老实实直接 import。
⚠️ 无障碍标签贴错位置。 图标默认带
aria-hidden="true"，屏幕阅读器自动跳过——装饰性场景这正是想要的。但把图标放进按钮时，aria-label应贴在按钮上（<button aria-label="Go to home">），让辅助技术描述的是可点击的元素本身，而不是里面的装饰图形。
⚠️ v1 起品牌图标已被移除。 Github、Slack、Figma 等 14 个品牌类图标整体下架，仍在使用的话请换成品牌官方 SVG 或 Simple Icons 一类的品牌图标集（见 docs/guide/react/migration.md）。
从 react-feather 迁移：四步切换
两者 API 几乎一致，迁移基本是体力活（参考 docs/guide/react/migration-from-feather.md）：
- 装新包、卸旧包：
npm install lucide-react+npm uninstall react-feather； - 全局查找替换：
from 'react-feather'→from 'lucide-react'； - 修 4 个改名图标（见下表）；
- 其余图标同名兼容，props 用法原样保留。
| react-feather | lucide-react |
|---|---|
GitHub | Github |
Grid | LayoutGrid |
Table | Table2 |
Tool | Wrench |
进阶工具箱：按需取用
按名称动态加载。 图标名存在数据库里时（典型如 CMS 后台配置）才用 DynamicIcon，name 必填：
import { DynamicIcon } from 'lucide-react/dynamic';
<DynamicIcon name="camera" color="red" size={48} />
嵌套组合出自定义图标。 SVG 允许 svg 里再嵌 svg，可以把一个小图标"贴"进另一个里，用 x、y 摆位置（坐标需落在 24×24 画布内）。给 Mail 加未读红点（塞一个 <circle> 子元素）也是同一套玩法：
<Scan size={48} nonScalingStroke>
<User size={12} x={6} y={6} nonScalingStroke />
</Scan>
TypeScript 类型标注。 LucideProps 可给你的图标包装组件标注完整 prop（含任意 SVG 属性）；LucideIcon 是单个图标组件的类型，做 icon prop 可配置的按钮、菜单时直接用它。旧的 IconNode 类型已标记废弃，源码里请改用 LucideIconNode（定义见 packages/lucide-react/src/types.ts）。
统一导入命名。 每个图标其实有三个导入名：House、HouseIcon、LucideHouse 是同一个东西，前缀 / 后缀版本用来避免和其他库撞名。想统一团队风格，可在项目里放一个 lucide-react.d.ts 声明文件，把导入指向 lucide-react.prefixed 或 lucide-react.suffixed 子路径，并在 IDE 设置里关掉对 lucide-react 的自动导入建议。VS Code 里悬停图标组件时能看到完整文档：
收尾对照表：参数与默认值
| prop | 默认值 | 作用 |
|---|---|---|
size | 24 | 图标宽高（px） |
color | currentColor | 描边颜色，缺省跟随文字颜色 |
strokeWidth | 2 | 线条粗细 |
nonScalingStroke | false | 线条粗细不随图标放大 |
absoluteStrokeWidth | — | 已废弃，用 nonScalingStroke 替代 |
除此之外任意 SVG 属性（stroke、fill、className……）都能直接当 prop 传。建议的上手顺序：先装包跑通一个图标 → 用三个旋钮调好单图标外观 → 全局风格二选一 → 有 feather 旧代码就全局替换再修 4 个改名图标。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
