教你发布一个 npm 的组织包

0背景与前置条件

对于使用 npm 包，每个人都不陌生，但是如何发布，尤其是 npm 组织包（Organization Packages）有些同学不太清楚。下面从零开始搭建一个 Vite 的 utils 工具包和文档静态站点。

前置条件

1. 注册 npm 账号：打开 npm 官网注册账号（记住用户名、密码、邮箱，发布时需要，开启 2FA 认证）；
2. 安装 Node 环境：确保本地安装了 Node.js（推荐 v16+），终端输入 node -v 查看版本；
3. npm 注册一个组织：注册成功后即可创建组织包。作者创建的是 zhj92，包名为 @zhj92/purchase-utils（组织名不能重复，需自己取名）。

1用 Vite 搭建项目 + 目录结构

1.1 创建基础项目

# 新建项目文件夹（假设包名叫 my-utils，可自定义）
mkdir my-utils && cd my-utils

# 用vite初始化项目（选择 vanilla-ts 模板，方便写TypeScript类型）
npm create vite@latest . -- --template vanilla-ts

1.2 安装依赖

# 安装项目依赖
npm install

# 安装文档生成工具（用vitepress，适合轻量文档）
npm install vitepress -D
# 其他依赖
npm i @types/node path terser esbuild -D

1.3 目录结构调整

my-utils/
├── src/
│   ├── index.ts        # 工具函数入口（对外暴露的方法）
│   └── utils/          # 具体工具函数文件夹
│       ├── format.ts   # 比如格式化相关函数
│       └── validate.ts # 比如验证相关函数
├── docs/               # 文档目录（vitepress用）
│   ├── index.md        # 文档首页
│   └── guide/          # 使用指南
│       └── usage.md    # 函数使用说明
├── package.json        # 项目配置（核心）
├── vite.config.ts      # vite打包配置
└── tsconfig.json       # TypeScript配置

2编写工具函数与打包配置

2.1 示例：写一个格式化时间的函数

/**
 * 格式化时间为 YYYY-MM-DD 格式
 * @param date 可选，传入Date对象或时间戳，默认当前时间
 * @returns 格式化后的日期字符串
 * @example
 * formatDate() => "2024-05-20"
 * formatDate(new Date(2023, 0, 1)) => "2023-01-01"
 */
export function formatDate(date?: Date | number): string {
  const d = date ? new Date(date) : new Date();
  const year = d.getFullYear();
  const month = String(d.getMonth() + 1).padStart(2, '0');
  const day = String(d.getDate()).padStart(2, '0');
  return `${year}-${month}-${day}`;
}

2.2 暴露函数入口

// 导出所有工具函数（方便用户导入）
export * from './utils/format';
// 未来添加的函数都在这里导出，比如：
// export * from './utils/validate';

2.3 配置 Vite 打包（关键）

import { defineConfig } from "vite";
import path from "path";

export default defineConfig({
  build: {
    // 打包为库模式
    lib: {
      entry: path.resolve(__dirname, "src/index.ts"), // 入口文件
      name: "myUtils", // 全局变量名（UMD模式用）
      fileName: (format) => `my-utils.${format}.js`, // 输出文件名
      formats: ["es", "umd"], // 输出两种格式：ES模块和UMD
    },
    // 压缩代码
    minify: "terser",
  },
});

3package.json / 类型声明 / 文档

3.1 配置 package.json（核心）

{
  "name": "@zhj92/purchase-utils",
  "version": "0.0.1",
  "type": "module",
  "main": "./dist/purchase-utils.umd.js",
  "module": "./dist/purchase-utils.es.js",
  "types": "./dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc && vite build",
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs"
  },
  "keywords": [
    "purchase-utils",
    "format",
    "tools"
  ],
  "author": "zhanghongjie",
  "license": "MIT",
  "description": "采购管理智能体的工具函数库",
  "devDependencies": {
    "@types/node": "^24.9.2",
    "path": "^0.12.7",
    "terser": "^5.44.0",
    "typescript": "~5.9.3",
    "vite": "npm:rolldown-vite@7.1.14",
    "vitepress": "^1.6.4"
  },
  "overrides": {
    "vite": "npm:rolldown-vite@7.1.14"
  }
}

3.2 生成 TypeScript 类型声明

{
  "compilerOptions": {
    // ...其他默认配置
    "declaration": true, // 生成.d.ts类型文件
    "outDir": "dist" // 类型文件输出到dist目录
  },
  "include": ["src"] // 只处理src目录
}

3.3 编写文档（vitepress）

创建 docs/.vitepress/config.ts：

import { defineConfig } from "vitepress";

export default defineConfig({
  title: "@zhj92/purchase-utils", // 文档标题
  description: "采购管理智能体的工具函数库文档",
  themeConfig: {
    nav: [{ text: "首页", link: "/" }],
    sidebar: {
      "/": [{ text: "使用指南", link: "/guide/usage" }],
    },
  },
});

docs/index.md（首页）：

# @zhj92/purchase-utils

采购管理智能体的工具函数库，简化采购管理过程。

## 安装
```bash
npm install @zhj92/purchase-utils
```

## 快速开始
import { formatDate } from '@zhj92/purchase-utils';
console.log(formatDate());

docs/guide/usage.md（函数说明）：

# 工具函数列表

## formatDate
格式化时间为 YYYY-MM-DD 格式

### 用法
import { formatDate } from 'my-utils';

// 默认当前时间
console.log(formatDate()); // "2024-05-20"

// 传入Date对象
console.log(formatDate(new Date(2023, 0, 1))); // "2023-01-01"

// 传入时间戳
console.log(formatDate(1672502400000)); // "2023-01-01"

3.4 本地预览文档

npm run docs:dev

4发布到 npm 与部署

4.1 登录 npm

npm login

4.2 打包项目

npm run build

此时会生成 dist 目录，包含打包后的代码和类型声明。

4.3 发布

npm publish --access public

4.4 代码同步 GitHub 与 Vercel 部署静态站点

• 代码同步 GitHub：本地代码推送到 GitHub 仓库；
• Vercel 部署：用于文档展示，导入 GitHub 仓库并选择 VitePress 构建即可。