avatar
🇨🇳
如何打包并发布一个 NPM 包：从零到上线的完整流程
🥈

如何打包并发布一个 NPM 包：从零到上线的完整流程

published_date
最新编辑 2025年01月14日
slug
全面指南，教你从零开始开发、打包并发布一个高质量的NPM包。涵盖项目配置、代码质量控制、自动化部署、发布流程及最佳实践，帮助你高效提升开发效率并创建专业的开源项目。
tags
npm
首页 - Jessie的旅行日记
欢迎来到Jessie的旅行日记，分享精彩旅程和独特体验。
https://www.jessieontheroad.com/
Jessie-jzn - Overview
Senior Software Engineer. Jessie-jzn has 14 repositories available. Follow their code on GitHub.
Jessie-jzn - Overview
https://github.com/Jessie-jzn
Jessie-jzn - Overview
 
在日常开发中，我们经常需要将自己的代码封装成 NPM 包供团队共享或社区使用。然而，初次尝试发布 NPM 包可能会遇到各种问题，比如权限、配置错误或者登录失败等。在本文中，我将结合结合实际项目经验，详细介绍如何开发、打包并发布一个 NPM 包。内容涵盖基础配置、代码质量控制、自动化部署以及发布最佳实践，快速掌握发布 NPM 包的核心流程。

1. 项目配置

在创建一个 NPM 包之前，确保项目已经准备好。执行以下命令初始化项目：
npm init
或者使用交互式的方式生成 package.json 文件：
npm init -y
生成的 package.json 文件是 NPM 包的核心配置，关键字段如下：
  • name：包名（全局唯一）。
  • version：版本号，遵循 SemVer 规范。
  • main：入口文件。
  • license：开源协议。

1.1 package.json 基础配置

{
  "name": "your-package-name",
  "version": "1.0.11",
  "description": "Package description",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "type": "module",
  "files": [
    "dist",
    "README.md"
  ],
  "scripts": {
    "build": "run-s build:*",
    "build:webpack": "webpack --mode production --config webpack.config.cjs",
    "build:tsc": "tsc --emitDeclarationOnly",
    "test": "run-p test:*",
    "test:eslint": "eslint '**/*.{ts,tsx}'",
    "test:prettier": "prettier '**/*.{js,jsx,ts,tsx}' --check",
    "format": "prettier --write 'src/**/*.{ts,tsx}'",
    "lint": "eslint '**/*.{ts,tsx}' --fix"
  }
  {
  "peerDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "dependencies": {
    "react-fast-compare": "^3.2.2"
  },
  "devDependencies": {
    "typescript": "^5.3.3",
    "webpack": "^5.97.1",
    "eslint": "^8.56.0",
    "prettier": "^3.2.4"
  }
}

2. 开发环境与代码质量控制

2.1 .npmrc 配置

registry=https://registry.npmjs.org/
sass_binary_site=https://npmmirror.com/mirrors/node-sass/
electron_mirror=https://npmmirror.com/mirrors/electron/

2.2 .npmignore 配置

# 开发文件
src/
tests/
.github/
.vscode/

# 配置文件
.eslintrc.cjs
.prettierrc.cjs
webpack.config.cjs

# 其他
*.log
.DS_Store

2.3 ESLint 配置 (.eslintrc.cjs)

module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: 2021,
    sourceType: "module",
    ecmaFeatures: {
      jsx: true
    }
  },
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "prettier"
  ],
  rules: {
    "@typescript-eslint/no-explicit-any": "off",
    "react/prop-types": "off"
  }
};

2.4 Prettier 配置 (package.json)

{
  "prettier": {
    "semi": true,
    "trailingComma": "es5",
    "singleQuote": false,
    "printWidth": 100,
    "tabWidth": 2,
    "useTabs": false,
    "bracketSpacing": true,
    "endOfLine": "lf"
  }
}

2.5 忽略格式化文件 (.prettierignore)

# 构建输出
dist/
build/
coverage/

# 依赖
node_modules/

# 配置文件
.eslintrc.cjs
webpack.config.cjs

3. 本地调试与测试

3.1 本地测试和构建
npm run lint     # 运行 ESLint
npm run format   # 运行 Prettier 格式化
npm test          # 执行测试
在发布之前，最好在本地进行测试。可以用以下命令将包链接到本地全局环境：
3.1.1 使用 npm link
  1. 首先在 react-notion-simplify 包目录下执行：
# 在包目录下
npm link
  1. 然后在要测试的项目目录下执行：
# 在测试项目目录下
npm link 包名 (react-notion-simplify)
3.1.2 使用 yalc（推荐，更稳定）
  1. 首先全局安装 yalc：
npm install -g yalc
  1. 在 react-notion-simplify 包目录下执行：
# 构建包
npm run build

# 发布到本地 yalc 仓库
yalc publish
  1. 在测试项目中执行：
# 添加本地包
yalc add react-notion-simplify

# 安装依赖
npm install
  1. 当修改了 react-notion-simplify 的代码后，需要：
# 在包目录下
npm run build
yalc push  # 这会自动更新所有使用这个包的项目
推荐使用 yalc 的原因：
  • 更稳定，不会影响全局 node_modules
  • 更接近真实的发布场景
  • 支持热更新推送
  • 避免 npm link 可能出现的依赖问题

4. 发布配置与注意事项

4.1发布前检查清单

  • 更新版本号：
npm version patch  # 小版本更新
npm version minor  # 功能版本更新
npm version major  # 主版本更新
  • 运行测试：
npm run test      # 运行所有测试
npm run lint      # 代码质量检查
npm run format    # 代码格式化
  • 构建检查：
npm run build     # 确保构建正常
4.2 手动发布步骤
  • 登录 NPM
# 按提示输入用户名、密码和邮箱
npm login

# 如果登录失败，可以尝试以下操作：清理缓存
npm cache clean --force
 
# 检查是否使用了非官方的 NPM 镜像
npm config get registry

# 如果输出是 https://registry.npmmirror.com，可以切换回官方源
npm config set registry https://registry.npmjs.org

# 验证登录状态
npm whoami

4.3.发布到 NPM

在项目根目录运行以下命令：
npm publish
如果需要发布为 beta 或其他标签版本，可以使用：
npm publish --tag beta

# 推送代码和标签
git push origin main --tags

5. 使用 GitHub Actions 自动发布

为了避免手动发布，可以将发布过程集成到 GitHub Actions 中。以下是一个示例工作流：
name: Publish NPM Package

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
          registry-url: https://registry.npmjs.org/

      - name: Install dependencies
        run: npm install

      - name: Publish to NPM
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm publish
💡
在 GitHub 仓库的 Settings > Secrets and variables > Actions 中，添加 NPM_TOKEN。

6.解决常见问题

问题 1：登录失败或频繁要求登录
  • 检查 .npmrc 文件是否配置了令牌：
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
  • 在 CI/CD 中，使用环境变量 NPM_TOKEN 来避免手动登录。
问题 2：ENEEDAUTH 或权限不足
  • 确认是包的管理员：
npm owner ls 包名
  • 如果不是，请联系当前管理员授权。
问题 3：包体积过大
  • 检查 .npmignore 是否正确。
  • 使用 npm pack 查看将要发布的文件。

7. 版本管理与更新

每次更新包时，需要更新版本号。使用以下命令：
npm version patch  # 补丁版本

npm version minor  # 次版本

npm version major  # 主版本
然后重新发布：
npm publish

8. 验证发布

发布完成后，确认包已经成功上线：
npm info 包名
可以在 npm 官网 搜索并查看包的详细信息。

9. 最佳实践与示例

9.1 代码组织

  • 使用 TypeScript 编写源码
  • 提供完整的类型定义
  • 模块化组织代码

9.2 示例：图片 URL 处理工具

export const defaultMapImageUrl = (url: string): string => {
  if (!url) {
    return "";
  }

  if (url.startsWith("data:")) {
    return url;
  }

  // 处理相对路径
  if (url.startsWith("/")) {
    url = `https://www.notion.so${url}`;
  }

  return url;
};

9.3 版本控制建议

  • 遵循语义化版本
  • 及时更新 CHANGELOG.md
  • 为每个版本打标签
  • 保持向后兼容性

9.4 文档维护

  • 编写详细的 README.md
  • 提供使用示例
  • 说明安装和配置步骤
  • 列出所有公共 API
通过以上步骤，你以顺利地将一个 NPM 包从开发到发布上线。如果在发布过程中遇到问题，欢迎交流经验！
 
Table of Contents