React 图标库发布到 npm 仓库

发布于:2025-07-30 ⋅ 阅读:(32) ⋅ 点赞:(0)

将搭建的 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 patch1.0.1
  • 次要版本(新增功能): npm version minor1.1.0
  • 主要版本(重大变更): npm version major2.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:确保 nameversionmain/module 字段正确。
  2. 登录 npmnpm login
  3. 构建代码npm run build
  4. 测试本地包npm packnpm link
  5. 发布npm publish
  6. 更新维护:通过 npm versionnpm publish 迭代版本。

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


网站公告

今日签到

点亮在社区的每一天
去签到