教你发布一个npm的组织包

背景

对于使用npm包，每个人都不陌生，但是如何发布，尤其是npm 组织包（Organization Packages有些同学不太清楚，正好朋友想找帮忙发布个他们常用utils的工具包，正好我也好久没发布了，给他写一个demo，正好记录下避免忘记

下面我从零开始 搭建一个vite的utils工具包 和 文档静态站点

一、前置条件

1. 注册 npm 账号 打开 npm 官网 注册账号（记住用户名、密码、邮箱，发布时需要,开启2FA认证）
2. 安装 Node 环境 确保本地安装了 Node.js（推荐 v16+），终端输入 node -v 查看版本，没有的话去 Node 官网 下载安装
3. npm注册一个组织 注册流程如下

注册成功后 可查看是否创建成功 我创建的是 zhj92后面我将按照此发布，你要自己取名字 不能重复

二、用 Vite 搭建项目

1. 创建基础项目

bash

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

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

2. 安装依赖

bash

# 安装项目依赖
npm install

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

三、目录结构调整

按以下结构整理文件（删除 vite 默认的冗余文件）：

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配置

四、编写工具函数

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

创建 src/utils/format.ts：

typescript

/**
 * 格式化时间为 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. 暴露函数入口

在 src/index.ts 中统一导出：

typescript

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

五、配置 Vite 打包（关键）

修改 vite.config.ts，让打包结果适合 npm 发布：

typescript

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",
  },
});

六、配置 package.json（核心）

修改 package.json 关键配置（注意替换成你的信息）：

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"
  }
}

七、生成 TypeScript 类型声明

修改 tsconfig.json，开启类型声明生成：

json

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

八、编写文档（vitepress）

1. 初始化文档配置

创建 docs/.vitepress/config.ts：

typescript

import { defineConfig } from "vitepress";

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

2. 写文档内容

• docs/index.md（首页）： 注意换成md格式

# @zhj92/purchase-utils

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

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

```

## 快速开始

```bash
import { formatDate } from '@zhj92/purchase-utils';
console.log(formatDate());
```

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

# 工具函数列表

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

### 用法
```typescript
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. 本地预览文档

bash

npm run docs:dev

打开终端提示的地址（通常是 http://localhost:5173），就能看到文档了

九、发布到 npm

1. 登录 npm

终端输入（注意：确保没有使用淘宝镜像，若用了先切换回官方源 npm config set registry https://registry.npmjs.org/）：

npm login

按提示输入用户名、密码、邮箱（可能需要验证邮箱）

2. 打包项目

npm run build

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

3. 发布

npm publish --access public

如果发布成功，会显示发布的版本信息。此时去 npm 官网搜索你的包名（比如 my-utils），就能找到它了！

注意登陆发布的过程 会要你输出 2FA 验证，输入六位密码即可

此时 你打开npm搜索 https://www.npmjs.com/package/@zhj92/purchase-utils即可访问 注意你得 名称替换

十、代码同步github

过程省略 本地代码推送到github仓库

十一、vercel部署 静态站点

用于文档展示

vercel包文档介绍

总结

以上就是发布npm包和静态站点的详细方法 酌情取用，源码地址