如何發布 NPM 套件？

為什麼要發布自己的 NPM 套件？

其實也沒什麼，以前都覺得發布 NPM 套件是大神才做的事，但我自己也想裝逼寫一個，所以就嘗試看看了哈哈哈，萬一不小心成為知名套件的開發者不就超屌的，履歷會超加分耶應該啦。

實際試過之後發現其實沒那麼難！而且有幾個好處：

重複使用：一次開發，到處使用
版本管理：不用每次都複製程式碼
分享給社群：說不定能幫到其他人
履歷加分：開源貢獻總是好事

初始化專案

首先建立一個新資料夾，然後初始化：

bash

mkdir my-awesome-package
cd my-awesome-package
npm init

如果想要快速建立，可以用：

bash

npm init -y

package.json 的關鍵設定

這是我發布套件時的 package.json 範例：

package.json

json

{
    "name": "chinese-number-format",
    "version": "1.0.2",
    "description": "中文數字轉換工具",
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
    "scripts": {
        "build": "tsc",
        "test": "jest"
    },
    "repository": {
        "type": "git",
        "url": "https://github.com/garylin0969/chinese-number-format.git"
    },
    "keywords": ["中文", "數字", "轉換", "台灣"],
    "author": {
        "name": "GaryLin",
        "email": "gary@example.com"
    },
    "license": "MIT"
}

重要欄位說明

name: 套件名稱，要是唯一的（去 npmjs.com 確認沒被用過）
version: 版本號，遵循 semantic versioning
description: 簡短說明，會出現在搜尋結果
main: 進入點檔案
keywords: 關鍵字，幫助別人找到你的套件
repository: GitHub 連結，讓人知道原始碼在哪

使用 TypeScript 開發

我建議用 TypeScript 開發，提供型別定義會讓用戶體驗更好：

bash

npm install typescript --save-dev
npx tsc --init

我的 tsconfig.json 設定：

tsconfig.json

json

{
    "compilerOptions": {
        "target": "es2016",
        "module": "commonjs",
        "outDir": "./dist",
        "declaration": true,
        "strict": true,
        "esModuleInterop": true
    },
    "include": ["src/**/*.ts"],
    "exclude": ["node_modules", "dist"]
}

實際開發套件

假設我要做一個簡單的工具函數：

src/index.ts

typescript

/**
 * 將數字轉換為中文
 * @param num 要轉換的數字
 * @returns 中文數字字串
 */
export function numberToChinese(num: number): string {
    const digits = ['零', '一', '二', '三', '四', '五', '六', '七', '八', '九'];
    const units = ['', '十', '百', '千', '萬'];
 
    if (num === 0) return '零';
 
    // 簡化版實作，實際會更複雜
    return num
        .toString()
        .split('')
        .map((d) => digits[parseInt(d)])
        .join('');
}

測試很重要

bash

npm install jest @types/jest ts-jest --save-dev

src/index.test.ts

typescript

import { numberToChinese } from './index';
 
describe('numberToChinese', () => {
    test('基本轉換', () => {
        expect(numberToChinese(123)).toBe('一二三');
        expect(numberToChinese(0)).toBe('零');
    });
});

建置套件

bash

npm run build

這會產生 dist 資料夾，裡面有編譯後的 JS 檔案和型別定義檔。

發布前的檢查

1. 測試本地安裝

bash

npm pack

這會產生一個 .tgz 檔案，你可以在其他專案裡測試：

bash

npm install ../my-package/my-package-1.0.0.tgz

2. 確認檔案內容

bash

npm publish --dry-run

這會顯示將要發布的檔案清單，確認沒有包含不該包含的檔案。

註冊 NPM 帳號並發布

1. 註冊帳號

去 npmjs.com 註冊帳號。

2. 本地登入

bash

npm login

3. 發布套件

bash

npm publish

第一次發布可能會很緊張，但其實就這麼簡單！

我踩過的坑

1. 套件名稱衝突

我一開始取的名稱已經被用了，所以要記得先去 npmjs.com 搜尋確認。

2. 忘記建置就發布

發布前一定要記得 npm run build，不然用戶安裝到的是原始碼。

3. .gitignore 和 .npmignore 搞混

記住：

.gitignore 控制什麼不要上傳到 Git
.npmignore 控制什麼不要發布到 NPM

4. 版本號忘記更新

每次發布前記得更新版本號，或使用：

bash

npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.0 → 1.1.0
npm version major  # 1.0.0 → 2.0.0

維護和更新

發布新版本

bash

# 更新版本號
npm version patch
 
# 發布
npm publish

廢棄舊版本

如果某個版本有問題：

bash

npm deprecate my-package@1.0.0 "這個版本有 bug，請使用 1.0.1"

最佳實踐

寫好 README：這是用戶看到的第一印象
提供型別定義：TypeScript 用戶會感謝你
寫測試：確保品質，也讓別人敢用
遵循語義化版本：破壞性變更要升 major 版本
及時回應 issue：維護開源專案的責任 (但我寫好玩的試試的XD)

推廣你的套件

在 GitHub README 加上安裝說明
寫部落格文章介紹
在相關社群分享
收集用戶反饋持續改進