教你发布一个npm的组织包

背景

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

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

一、前置条件

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

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

二、用 Vite 搭建项目

1. 创建基础项目

bash

perl 复制代码

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

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

2. 安装依赖

bash

bash 复制代码

# 安装项目依赖
npm install

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

三、目录结构调整

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

plaintext 复制代码

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

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

javascript 复制代码

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

五、配置 Vite 打包（关键）

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

typescript

javascript 复制代码

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

perl 复制代码

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

json 复制代码

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

八、编写文档（vitepress）

1. 初始化文档配置

创建 docs/.vitepress/config.ts：

typescript

php 复制代码

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格式

markdown 复制代码

# @zhj92/purchase-utils

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

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

```

## 快速开始

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

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

markdown 复制代码

# 工具函数列表

## 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

arduino 复制代码

npm run docs:dev

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

九、发布到 npm

1. 登录 npm

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

bash 复制代码

npm login

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

2. 打包项目

bash 复制代码

npm run build

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

3. 发布

bash 复制代码

npm publish --access public

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

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

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

十、代码同步github

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

十一、vercel部署静态站点

用于文档展示

vercel包文档介绍

总结

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

教你发布一个npm的组织包

背景

一、前置条件

二、用 Vite 搭建项目

1. 创建基础项目

2. 安装依赖

三、目录结构调整

四、编写工具函数

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

2. 暴露函数入口

五、配置 Vite 打包（关键）

六、配置 package.json（核心）

七、生成 TypeScript 类型声明

八、编写文档（vitepress）

1. 初始化文档配置

2. 写文档内容

3. 本地预览文档

九、发布到 npm

1. 登录 npm

2. 打包项目

3. 发布

十、代码同步github

十一、vercel部署 静态站点

总结

十一、vercel部署静态站点