React 图标库发布到 npm 仓库

将搭建的 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. 发布后验证

1. 访问 https://www.npmjs.com/package/my-react-icons，查看包是否已上线。

2. 在其他项目中安装测试：

   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 支持

1. 创建 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>;

2. 在 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-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org/
      - run: npm install
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # 在 npm 获取 token 并添加到 GitHub Secrets

---

总结

1. 配置 package.json ：确保 name、version、main/module 字段正确。
2. 登录 npm ：npm login。
3. 构建代码 ：npm run build。
4. 测试本地包 ：npm pack 或 npm link。
5. 发布 ：npm publish。
6. 更新维护 ：通过 npm version 和 npm publish 迭代版本。

完成以上步骤后，你的 React 图标库就可以被全球开发者通过 npm install 使用了！