NPM 包开发与发布实战指南

这份指南将带你从零开始开发一个遵循组件化、语义化和结构化原则的 TypeScript 工具库，并将其发布到 NPM。

1. 准备工作 (Preparation)

确保你已经拥有：

Node.js 环境。

NPM 账号（如果还没有，去 npmjs.com 注册）。

2. 项目初始化 (Initialization)

我们将创建一个名为 my-utils-demo 的文件夹（你可以替换为你喜欢的名字，但注意去 NPM 搜一下是否重名）。

mkdir my-utils-demo cd my-utils-demo npm init -y

推荐的目录结构 (Structure)

符合我们约定的清晰结构：

my-utils-demo/ ├── src/ │ ├── index.ts # 入口文件 │ ├── math.ts # 数学相关逻辑 │ ├── format.ts # 格式化相关逻辑 │ └── types.ts # 类型定义 ├── dist/ # 构建产物 (自动生成) ├── package.json ├── tsconfig.json └── README.md

3. 环境配置 (Configuration)

为了代码的可维护性和类型提示，我们使用 TypeScript。

安装依赖

npm install typescript --save-dev

配置 tsconfig.json

在根目录新建 tsconfig.json：

{ "compilerOptions": { "target": "ES6", "module": "CommonJS", "declaration": true, // 生成 .d.ts 类型文件 "outDir": "./dist", // 输出目录 "strict": true // 开启严格模式 }, "include": ["src"] }

4. 编写核心代码 (Coding)

遵循我们的 100行原则 和 语义化命名。

4.1 类型定义 (src/types.ts)

// 这里的命名清晰地描述了数据结构 export interface CalculationResult { success: boolean; value: number; message?: string; }

4.2 业务逻辑 (src/math.ts)

import { CalculationResult } from './types';

/**

• 计算两个数的和
• @param a 第一个数字
• @param b 第二个数字 */ export const addNumbers = (a: number, b: number): CalculationResult => { return { success: true, value: a + b }; };

/**

• 计算两个数的差 */ export const subtractNumbers = (a: number, b: number): CalculationResult => { return { success: true, value: a - b }; };

4.3 统一出口 (src/index.ts)

// 保持清晰的导入导出顺序 export * from './types'; export * from './math';

5. 配置 Package.json

修改 package.json，确保关键字段正确。

{ "name": "你的包名", "version": "1.0.0", "main": "dist/index.js", // 入口文件 "types": "dist/index.d.ts", // 类型声明文件入口 "scripts": { "build": "tsc" // 构建命令 }, "files": [ // 指定发布到 NPM 的文件 "dist" ], // ... 其他信息 }

6. 构建与测试 (Build & Test)

在发布前，先在本地构建并验证。

构建代码：

npm run build

检查 dist 目录下是否生成了 .js 和 .d.ts 文件。

Git 提交（遵循我们的提交规范）：

git init git add . git commit -m "feat: 初始化项目结构并实现基础数学计算功能"

7. 发布到 NPM (Publish)

登录 NPM：

npm login

按提示输入用户名、密码和邮箱。

发布：

npm publish

注意：如果是第一次发布 scoped 包（如 @username/package），需要加 --access public 参数。

8. 安装与验证 (Install)

发布成功后，创建一个新的测试项目来验证安装。

cd .. mkdir test-my-package cd test-my-package npm init -y npm install 你的包名

新建 index.js 测试：

const { addNumbers } = require('你的包名');

const result = addNumbers(5, 10); console.log(result); // 期望输出: { success: true, value: 15 }

9. 后续迭代 (Iteration)

当你需要更新包时，遵循以下步骤：

修改代码（遵循组件化拆分）。

构建：npm run build。

提交 Git：git commit -m "fix: 修复加法计算中的精度丢失问题"。

更新版本号：npm version patch (小修补) 或 minor (新功能)。

发布：npm publish。