h5打開以查看
一、初始設置：為成功發布做好準備
1. 項目初始化與結構
bash
# 創建項目目錄并初始化 mkdir my-awesome-lib cd my-awesome-lib npm init -y
推薦的項目結構：
text
my-awesome-lib/ ├── src/ # 源代碼目錄 │ └── index.js # 主入口文件 ├── dist/ # 構建輸出目錄（如果需要打包） ├── test/ # 測試文件 ├── docs/ # 文檔 ├── examples/ # 使用示例 ├── .github/ # GitHub 配置（workflows, ISSUE_TEMPLATE等） ├── package.json ├── README.md └── .npmignore # 可選，控制發布到npm的文件
2. 關鍵的?package.json?配置
一個庫的?package.json?配置與應用項目不同：
json
{"name": "my-awesome-lib", // 確保名字唯一且有意義"version": "1.0.0", // 遵循語義化版本規范"description": "A brief description of your awesome library","main": "dist/index.js", // CommonJS 入口點"module": "src/index.js", // ES Module 入口點 (如果支持)"types": "dist/index.d.ts", // TypeScript 類型定義文件"files": [ // 明確指定要發布到npm的文件"dist","src", // 可選：發布源碼以供tree-shaking"README.md"],"scripts": {"build": "babel src -d dist --copy-files","test": "jest","prepublishOnly": "npm run build && npm test", // 發布前自動構建和測試"version": "npm run build" // 執行npm version時自動構建},"keywords": ["tool", "utility", "awesome"],"author": "Your Name","license": "MIT","repository": {"type": "git","url": "https://github.com/your-username/my-awesome-lib.git"},"bugs": {"url": "https://github.com/your-username/my-awesome-lib/issues"},"homepage": "https://github.com/your-username/my-awesome-lib#readme","devDependencies": {// 開發工具...},"peerDependencies": {// 如果需要：如 "react": ">=16.8.0"},"engines": {"node": ">=14.0.0" // 指定支持的Node.js版本}
}
二、開發規范與工具鏈
1. 代碼質量與風格
bash
# 安裝必要的開發依賴 npm install --save-dev eslint prettier eslint-config-prettier @typescript-eslint/eslint-plugin @typescript-eslint/parser
.eslintrc.js?配置示例：
javascript
module.exports = {env: {node: true,es2021: true,},extends: ['eslint:recommended','prettier' // 確保ESLint和Prettier不沖突],parserOptions: {ecmaVersion: 12,sourceType: 'module',},rules: {// 自定義規則},
};
2. 測試框架
bash
npm install --save-dev jest ts-jest @types/jest
jest.config.js?配置：
javascript
module.exports = {preset: 'ts-jest',testEnvironment: 'node',testMatch: ['**/test/**/*.test.ts'],collectCoverageFrom: ['src/**/*.ts'],coverageDirectory: 'coverage',
};
3. 構建與打包
根據目標用戶選擇構建工具：
-
Rollup: 適合庫打包，Tree-shaking友好
-
Babel: 轉換現代JS語法
-
TypeScript: 類型安全和編譯
bash
npm install --save-dev @babel/core @babel/preset-env rollup @rollup/plugin-babel
三、版本控制與發布流程
1. 語義化版本 (SemVer)
遵循?MAJOR.MINOR.PATCH?規則：
-
PATCH (1.0.1): 向后兼容的bug修復
-
MINOR (1.1.0): 向后兼容的新功能
-
MAJOR (2.0.0): 不兼容的API變更
2. 自動化發布流程
使用?npm version?命令管理版本：
bash
# 開發完成后... npm test # 確保測試通過 npm run build # 構建生產版本# 更新版本號（選擇其一） npm version patch # 1.0.0 → 1.0.1 npm version minor # 1.0.1 → 1.1.0 npm version major # 1.1.0 → 2.0.0# 發布到npm npm publish# 推送到GitHub并打tag git push && git push --tags
3. 使用發布腳本自動化
在?package.json?中添加鉤子：
json
{"scripts": {"preversion": "npm test","version": "npm run build && git add -A dist","postversion": "git push && git push --tags"}
}
四、文檔編寫：讓用戶愛上你的庫
1.?README.md?- 你的門面
一個優秀的 README 應包含：
markdown
# My Awesome Lib[](https://badge.fury.io/js/my-awesome-lib) [](https://github.com/your-username/my-awesome-lib/actions) [](https://coveralls.io/github/your-username/my-awesome-lib)> 一句話描述庫的價值## ? Features- 功能點1 - 功能點2 - 功能點3## 📦 Installation```bash npm install my-awesome-lib # 或 yarn add my-awesome-lib
🚀 Quick Start
javascript
import { awesomeFunction } from 'my-awesome-lib';const result = awesomeFunction('input');
console.log(result); // 'Awesome output!'
📚 API Reference
awesomeFunction(input: string): string
詳細描述函數的作用、參數、返回值。
Example:
javascript
// 代碼示例
🤝 Contributing
歡迎貢獻！請閱讀?貢獻指南。
📄 License
MIT ??Your Name
text
#### 2. 高級文檔工具 - **TypeDoc**: 為TypeScript項目自動生成API文檔 - **JSDoc**: JavaScript項目的文檔生成 - **VitePress/VuePress**: 構建完整的文檔網站---### 五、維護與迭代最佳實踐#### 1. GitHub配置 創建 `.github` 目錄來規范協作：
.github/
├── ISSUE_TEMPLATE/
│ ├── bug_report.md
│ └── feature_request.md
├── PULL_REQUEST_TEMPLATE.md
└── workflows/
└── ci.yml
text
**示例 CI 工作流 (`.github/workflows/ci.yml`)**:
```yaml
name: CIon: [push, pull_request]jobs:test:runs-on: ubuntu-lateststrategy:matrix:node-version: [14.x, 16.x, 18.x]steps:- uses: actions/checkout@v3- name: Use Node.js ${{ matrix.node-version }}uses: actions/setup-node@v3with:node-version: ${{ matrix.node-version }}- run: npm ci- run: npm test- run: npm run build
2. 變更日志 (CHANGELOG.md)
使用?約定式提交?并自動生成變更日志：
bash
# 安裝工具
npm install --save-dev conventional-changelog-cli# 在package.json中添加腳本
{"scripts": {"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"}
}
3. 處理Issue和PR
-
使用模板規范Issue報告
-
建立清晰的貢獻指南
-
及時響應社區反饋
六、實戰案例：發布一個工具函數庫
1. 開發階段
bash
# 初始化
npm init -y# 添加開發依賴
npm install --save-dev jest @types/jest typescript @babel/core @babel/preset-env# 添加源碼
mkdir src
echo "export const add = (a, b) => a + b;" > src/index.js# 添加測試
mkdir test
echo "const { add } = require('../src'); test('adds 1 + 2 to equal 3', () => { expect(add(1, 2)).toBe(3); });" > test/index.test.js
2. 發布準備
json
{"main": "src/index.js","files": ["src", "README.md"],"scripts": {"test": "jest","prepublishOnly": "npm test"}
}
3. 首次發布
bash
# 登錄npm（如果第一次） npm login# 發布 npm publish# 或者發布測試版 npm version prepatch --preid=beta npm publish --tag beta
4. 迭代更新
bash
# 修復bug后發布補丁版本 npm version patch npm publish# 添加新功能后發布小版本 npm version minor npm publish# 用戶可以通過指定tag安裝測試版 npm install my-awesome-lib@beta
七、高級技巧與陷阱避免
-
作用域包：使用?
@username/package-name?避免命名沖突 -
多入口點：大型庫可以拆分多個入口
-
條件導出：為不同環境提供不同的入口點
-
避免全局副作用：確保庫的純凈性
-
瀏覽器兼容性：如果需要，提供UMD構建版本
-
TypeScript支持：即使用JS開發，也提供類型定義
記住，一個好的庫不僅僅是代碼，還包括文檔、測試和社區支持
h5打開以查看
