如何发布 npm 包并配置私有注册库？ - 面试题

npm 允许开发者将自定义包发布到 npm registry，供他人使用。同时，企业可以使用私有 registry 管理内部包。

发布 npm 包

1. 准备工作

注册 npm 账号：

bash
npm adduser
# 或
npm login

验证登录：

bash
npm whoami

2. package.json 配置

确保 package.json 包含必要字段：

json
{
  "name": "my-awesome-package",
  "version": "1.0.0",
  "description": "An awesome npm package",
  "main": "index.js",
  "keywords": ["awesome", "package"],
  "author": "Your Name <email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-awesome-package.git"
  },
  "homepage": "https://github.com/username/my-awesome-package#readme",
  "bugs": {
    "url": "https://github.com/username/my-awesome-package/issues"
  },
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ],
  "scripts": {
    "prepublishOnly": "npm run build && npm run test",
    "build": "tsc",
    "test": "jest"
  }
}

重要字段说明：

name：包名，必须唯一（在公开 registry）
version：遵循语义化版本
private：设置为 false 或删除该字段才能发布
files：指定要包含在发布包中的文件

3. 发布流程

构建和测试：

bash
npm run build
npm test

预发布检查：

bash
npm pack

这会生成 .tgz 文件，可以检查将要发布的内容。

发布到公开 registry：

bash
npm publish

发布特定标签：

bash
npm publish --tag beta

发布到私有 scope：

bash
npm publish --access public

4. 版本管理

更新版本：

bash
# 补丁版本 (1.0.0 -> 1.0.1)
npm version patch

# 次版本 (1.0.0 -> 1.1.0)
npm version minor

# 主版本 (1.0.0 -> 2.0.0)
npm version major

# 预发布版本
npm version prerelease --preid beta

发布新版本：

bash
git push --follow-tags
npm publish

私有 Registry

1. 配置私有 Registry

设置全局 registry：

bash
npm config set registry https://registry.yourcompany.com

设置项目级 registry：在项目根目录创建 .npmrc：

shell
registry=https://registry.yourcompany.com

2. 使用 Scoped Packages

创建 scoped 包：

json
{
  "name": "@yourcompany/package-name"
}

配置 scope registry：

bash
npm config set @yourcompany:registry https://registry.yourcompany.com

在 .npmrc 中配置：

shell
@yourcompany:registry=https://registry.yourcompany.com

3. 认证配置

使用 token 认证：

bash
npm config set //registry.yourcompany.com/:_authToken YOUR_TOKEN

在 .npmrc 中配置：

shell
//registry.yourcompany.com/:_authToken=${NPM_TOKEN}

使用环境变量：

bash
export NPM_TOKEN=your_token_here

4. 发布到私有 registry

发布 scoped 包：

bash
npm publish

发布为公开包（在私有 registry）：

bash
npm publish --access public

常用发布命令

bash
# 检查包名是否可用
npm view <package-name>

# 查看包信息
npm info <package-name>

# 查看包的所有版本
npm view <package-name> versions

# 查看包的依赖
npm view <package-name> dependencies

# 取消发布（谨慎使用）
npm unpublish <package-name>@<version>

# 废弃包版本
npm deprecate <package-name>@<version> "This version is deprecated"

# 搜索包
npm search <keyword>

# 查看当前 registry
npm config get registry

# 查看 npm 配置
npm config list

.npmignore 文件

.npmignore 文件用于指定发布时要忽略的文件：

shell
# 源代码
src/
test/
*.ts
*.spec.js

# 开发配置
.eslintrc
.prettierrc
jest.config.js
tsconfig.json

# 文档
docs/
*.md
!README.md

# CI/CD
.github/
.gitlab-ci.yml

# IDE
.vscode/
.idea/

注意：.npmignore 会覆盖 files 字段。

最佳实践

1. 版本管理

遵循语义化版本规范
在发布前运行完整测试
使用 prepublishOnly 脚本确保质量
维护 CHANGELOG.md 记录变更

2. 包结构

shell
my-package/
├── package.json
├── README.md
├── LICENSE
├── .npmignore
├── src/
│   └── index.ts
├── dist/
│   ├── index.js
│   └── index.d.ts
└── test/
    └── index.test.js

3. 文档

提供清晰的 README.md
包含安装和使用示例
说明 API 和配置选项
提供贡献指南

4. 安全性

不要在包中包含敏感信息
使用 npm audit 检查安全漏洞
定期更新依赖
使用 .npmignore 排除敏感文件

5. 持续集成

yaml
# .github/workflows/publish.yml
name: Publish Package

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

常见问题

1. 包名冲突

如果包名已被占用，考虑：

使用 scoped 包：@username/package-name
选择不同的名称
联系包的所有者

2. 发布失败

常见原因：

包名已被占用
缺少必要字段
版本号未更新
认证失败

3. 取消发布限制

npm 限制取消发布：

只能取消发布 72 小时内的版本
不能取消发布超过 24 小时的主要版本
使用 deprecate 替代 unpublish

企业级解决方案

1. Verdaccio

轻量级私有 npm registry：

bash
npm install -g verdaccio
verdaccio

2. Artifactory

企业级制品仓库，支持多种包管理器。

3. Nexus Repository

另一个流行的企业级制品仓库解决方案。

4. GitHub Packages

使用 GitHub 作为私有 registry：

bash
npm config set registry https://npm.pkg.github.com
npm login --scope=@your-username --registry=https://npm.pkg.github.com

掌握 npm 发布和私有 registry 配置对于团队协作和企业级项目管理至关重要。