跳到主要內容
← 回到學習

學習 · 開發工具

發布自己的npm包

By Kurau3 分鐘閱讀

目錄 · 7 個段落
  1. 01基本流程
  2. 02scope 套件(@username/pkg-name)
  3. 03更新版本
  4. 04package.json 必要欄位
  5. 05進階做法(2026)
  6. 06常見地雷
  7. 07替代發布平台

發布自己的 npm 套件

TL;DR
流程:註冊 npm 帳號 → npm login → npm publish。有 scope name(@username/pkg)要加 --access public,否則預設 private(要付費)。版本管理走 semver(1.2.3 = major.minor.patch)。

基本流程

# 1. 註冊 npm 帳號(npmjs.com)
 
# 2. 登入(會問 username / password / email / OTP)
npm login
 
# 3. 確認登入身份
npm whoami
 
# 4. package.json 設定好(name / version / main / files / etc)
 
# 5. 發布
npm publish
bash

npm publish 會把 package.json + 你 include 的檔案上傳,自動讀 README.md 當作介紹頁。

scope 套件(@username/pkg-name)

# 預設是 private,要付費
npm publish
 
# 公開發布
npm publish --access public      # ⭐ 必加
bash

scope 套件 像是 @bobo100/cra-template-bobonext.js,必須加 --access public 才會公開發布。

更新版本

# 用 npm version 自動更新版號 + 打 git tag
npm version patch        # 1.0.0 → 1.0.1(bugfix)
npm version minor        # 1.0.1 → 1.1.0(新功能,向後相容)
npm version major        # 1.1.0 → 2.0.0(breaking change)
 
# 然後發布
npm publish --access public
bash

規則:版本必須 大於現在線上版本,不能往下改。發布錯了 24 hr 內可以 unpublish,過期就只能廢棄(deprecate)。

package.json 必要欄位

{
  "name": "@bobo100/my-package",
  "version": "1.0.0",
  "description": "簡短描述",
  "main": "dist/index.js",            // 入口
  "module": "dist/index.esm.js",      // ESM 入口(modern)
  "types": "dist/index.d.ts",         // TS 型別
  "files": [                          // ⭐ 哪些檔要 publish
    "dist/",
    "README.md",
    "LICENSE"
  ],
  "keywords": ["react", "..."],
  "author": "Bobo",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/Bobo100/my-package"
  }
}
json

files 欄位很重要,沒設會把 node_modules / 測試檔等垃圾全 ship 出去。

進階做法(2026)

1. 用 changesets 管版本

適合 monorepo / 多 package 同時發版:

npm install --save-dev @changesets/cli
npx changeset init
npx changeset                # 互動式選 patch/minor/major
npx changeset version        # 套用版號
npx changeset publish        # 發布
bash

2. CI 自動發版

# .github/workflows/publish.yml
on:
  push:
    branches: [main]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
yaml

NPM_TOKEN 從 npmjs.com → Account → Access Tokens 產生。

常見地雷

1. 套件名搶占
熱門名稱可能被搶。發布前先 npm view <name> 確認。 個人套件建議用 scope 開頭(@username/pkg),不會撞名。
2. 沒設 .npmignore / files
npm 預設打包整個資料夾(除了 .gitignore + node_modules)。 用 files 欄位明確列出要 ship 的目錄。
3. README 沒更新
npm 頁面 會顯示 README,publish 前確認 README 內容對應到當前版本。
4. 版本號 prerelease
npm version 1.0.0-beta.1
npm publish --tag beta       # ⭐ 別人 install 時要 npm install pkg@beta
bash

預設 install 不會抓到 prerelease 版本,要加 --tag。

替代發布平台

平台特色
npm registry預設
GitHub Packages跟 GitHub 整合
JSR2024 推出,Deno 出的下一代 registry
私有 registryVerdaccio 自架

2026 年觀察 JSR,Deno team 出的,主打更好的 TypeScript 支援、自動產 docs。

目錄