当前位置：首页 > news >正文

React 图标库发布到 npm 仓库

news 2025/7/31 17:33:27

将搭建的 React 图标库发布到 npm 仓库需要经过一系列步骤，包括配置 package.json、构建代码、注册 npm 账号、测试和发布。以下是详细流程：

1. 准备工作

(1) 确保项目结构完整

图标库的典型结构（以 Rollup 构建为例）：

my-react-icons/
├── dist/               # 构建输出目录（由 Rollup 生成）
├── src/                # 源代码
│   ├── icons/          # 图标组件
│   └── index.js        # 统一导出
├── rollup.config.js    # Rollup 配置
├── package.json        # 项目配置
└── README.md           # 使用文档

(2) 检查 `package.json` 关键字段

{"name": "my-react-icons",      // 包名（确保唯一性，先在 npm 搜索是否重名）"version": "1.0.0",           // 版本号（遵循语义化版本规范）"description": "A custom React icon library","main": "dist/index.js",       // CommonJS 入口文件"module": "dist/index.esm.js", // ES Module 入口文件（支持 Tree Shaking）"files": ["dist"],            // 指定发布到 npm 的目录"scripts": {"build": "rollup -c",       // 构建命令"prepublishOnly": "npm run build" // 发布前自动构建},"peerDependencies": {         // 声明依赖的 React 版本"react": ">=16.8.0","react-dom": ">=16.8.0"},"keywords": ["react", "icons", "svg"],"author": "Your Name","license": "MIT"
}

2. 注册 npm 账号

(1) 注册账号

访问 npm 官网注册账号。
如果已有账号，跳过此步骤。

(2) 本地登录 npm

在项目根目录运行：

npm login

按提示输入：

Username: 你的 npm 用户名
Password: 密码
Email: 注册邮箱（需验证）

登录成功后会显示：
Logged in as <your-username> on https://registry.npmjs.org/

3. 构建代码

运行构建命令生成 dist 目录：

npm run build

确保 dist 目录下包含：

index.js（CommonJS 格式）
index.esm.js（ES Module 格式）

4. 测试本地包

(1) 本地模拟发布

在项目根目录运行：

npm pack

生成一个 .tgz 文件（如 my-react-icons-1.0.0.tgz），在其他项目中安装测试：

cd ../another-project
npm install ../my-react-icons/my-react-icons-1.0.0.tgz

测试是否正常使用：

import { Home } from 'my-react-icons';

(2) 使用 `npm link`（可选）

在图标库目录运行：

npm link

在测试项目目录运行：

npm link my-react-icons

5. 正式发布到 npm

(1) 检查 npm 源

确保使用的是官方源：

npm config get registry
# 应该是 https://registry.npmjs.org/

如果使用淘宝镜像，需切换：

npm config set registry https://registry.npmjs.org/

(2) 发布包

在项目根目录运行：

npm publish

成功后会显示：
+ my-react-icons@1.0.0

6. 发布后验证

访问 https://www.npmjs.com/package/my-react-icons，查看包是否已上线。
在其他项目中安装测试：
```
npm install my-react-icons
```

7. 更新版本

修改代码后，按语义化版本规则更新版本号：

补丁版本（修复 bug）: npm version patch → 1.0.1
次要版本（新增功能）: npm version minor → 1.1.0
主要版本（重大变更）: npm version major → 2.0.0

重新发布：

npm publish

8. 常见问题解决

(1) 包名冲突

错误提示：You do not have permission to publish "my-react-icons"
解决：修改 package.json 中的 name 为唯一名称（如 @yourusername/my-react-icons）。

(2) 未验证邮箱

错误提示：npm ERR! 403 Forbidden - PUT https://registry.npmjs.org/my-react-icons - You must verify your email before publishing a package
解决：登录 npm 官网验证邮箱。

(3) 重复发布

错误提示：Cannot publish over existing version
解决：更新版本号后再发布。

9. 高级配置（可选）

(1) 添加 TypeScript 支持

创建 index.d.ts 类型声明文件：

// src/types.d.ts
import * as React from 'react';
export interface IconProps extends React.SVGProps<SVGSVGElement> {size?: number | string;color?: string;
}
export declare const Home: React.FC<IconProps>;

在 package.json 中添加：
```
"types": "dist/types.d.ts"
```

(2) 自动化构建与发布

使用 GitHub Actions 自动发布（示例配置 .github/workflows/publish.yml）：

name: Publish to npm
on:push:tags:- 'v*'
jobs:publish:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: actions/setup-node@v4with:node-version: 20registry-url: https://registry.npmjs.org/- run: npm install- run: npm publishenv:NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # 在 npm 获取 token 并添加到 GitHub Secrets