7月 15, 2026

npm 套件發布完整教學：從建立專案到發布自己的 npm Package

前言

在 JavaScript 或 Node.js 的開發中，我們常常會使用許多第三方套件，例如：


npm install axios
npm install express
npm install lodash

這些套件都來自 npm (Node Package Manager)。

如果自己也開發了一個工具，希望：

在不同專案重複使用
分享給團隊成員
開源給其他開發者使用

就可以將它發布到 npm。

本篇文章將完整介紹如何建立並發布第一個 npm Package。

什麼是 npm？

npm 是 Node.js 官方提供的套件管理平台，提供：

套件管理
版本控制
相依套件管理
套件發布
套件下載

目前已經擁有數百萬個套件，是 JavaScript 最大的生態系。

安裝 Node.js

確認已安裝 Node.js


node -v

例如


v22.10.0

再確認 npm


npm -v

例如


10.9.0

建立專案

建立一個新的資料夾


mkdir my-first-package

cd my-first-package

初始化 npm


npm init

依序輸入：


package name
version
description
entry point
author
license

也可以直接使用


npm init -y

建立完成後會看到


package.json

內容如下：


{
  "name": "my-first-package",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT"
}

撰寫程式

建立


index.js

內容


function hello(name) {
    return `Hello ${name}!`;
}

module.exports = hello;

本機測試

建立


test.js


const hello = require("./index");

console.log(hello("Jeff"));

執行


node test.js

輸出


Hello Jeff!

代表套件運作正常。

建立 npm 帳號

前往

https://www.npmjs.com/

註冊帳號。

登入 npm

終端機輸入


npm login

新版 npm 可能會開啟 Browser Login。

登入成功可確認


npm whoami

若成功會顯示


jeff123

package.json 常用設定

例如：


{
    "name": "my-first-package",
    "version": "1.0.0",
    "description": "Demo npm package",
    "main": "index.js",
    "keywords": [
        "demo",
        "tool"
    ],
    "author": "Jeff",
    "license": "MIT"
}

各欄位說明：

欄位	用途	是否必要	範例
`name`	套件名稱，發布至 npm 時的唯一名稱。	✔ 必要	my-first-package
`version`	套件版本號，遵循 Semantic Versioning（語意化版本）。	✔ 必要	1.0.0
`description`	套件簡介，方便使用者了解套件用途。	建議	Demo npm package
`main`	指定套件的入口檔案。	建議	index.js
`keywords`	搜尋關鍵字，提高 npm 搜尋能見度。	建議	["tool", "utility"]
`author`	套件作者資訊。	建議	Jeff
`license`	套件授權方式。	建議	MIT
`repository`	原始碼儲存庫網址，通常為 GitHub Repository。	建議	https://github.com/jeff/my-first-package
`homepage`	套件首頁或官方文件網址。	選填	https://github.com/jeff/my-first-package
`bugs`	回報 Issue 的網址或 Email。	選填	https://github.com/jeff/my-first-package/issues
`scripts`	定義 npm 指令，例如 test、build、start。	建議	npm run build
`dependencies`	正式環境所需的相依套件。	依需求	axios、lodash
`devDependencies`	開發期間使用的套件，例如 ESLint、Jest。	依需求	typescript、eslint
`files`	指定發佈到 npm 時要包含哪些檔案。	建議	["dist"]

發布套件

直接執行


npm publish

第一次可能出現


403 Forbidden

通常原因：

名稱已被使用
未登入
沒有權限

修改 package 名稱即可。

例如


jeff-super-tool

再次發布


npm publish

看到


+ jeff-super-tool@1.0.0

表示成功。

安裝自己發布的套件

任何人都可以安裝


npm install jeff-super-tool

使用方式


const hello = require("jeff-super-tool");

console.log(hello("Jeff"));

更新版本

修改程式後，需要更新版本。

例如


1.0.0

改成


1.0.1

或使用


npm version patch

會自動變成


1.0.1

更新後再次發布


npm publish

Semantic Version（語意化版本）

npm 使用：


Major.Minor.Patch

例如


2.3.5

代表：


Major = 2
Minor = 3
Patch = 5

Patch

修正 Bug


1.0.0

↓

1.0.1

Minor

新增功能


1.0.0

↓

1.1.0

Major

重大修改（Breaking Change）


1.0.0

↓

2.0.0

package-lock.json 要不要發布？

通常：

✔ 發布 Git 專案

保留


package-lock.json

✔ npm Package

通常不用特別處理，npm 發布時主要依據 package.json。

README.md

建議撰寫 README。

例如：


# my-first-package

Demo npm package

## Installation

```bash
npm install my-first-package
```

## Usage

```javascript
const hello = require("my-first-package");

console.log(hello("Jeff"));
```

README 將會顯示在 npm 網站上。

常見錯誤

403 Forbidden

代表：

名稱重複
沒登入
沒權限

You cannot publish over the previously published versions

代表：

同一個版本不能重複發布。

例如：


1.0.0

已發布。

再次發布


1.0.0

會失敗。

需要更新版本。

例如


1.0.1

npm ERR! code E404

通常代表：

package 名稱錯誤
package 尚未發布

發布 Scope Package

若希望使用自己的命名空間，可以建立 Scoped Package。

例如：


@jeff/utils

package.json


{
  "name": "@jeff/utils"
}

發布時需加入：


npm publish --access public

否則 Scoped Package 預設為 Private。

最佳實務

建議在發布 npm 套件時遵循以下原則：

使用有意義的套件名稱，避免與現有套件衝突。
維持清楚的 README.md，包含安裝、使用方式與範例。
採用 Semantic Versioning 管理版本。
在發布前先於本機完整測試功能。
使用 .npmignore 或 files 欄位避免將測試資料、設定檔或大型檔案一併發布。
定期更新相依套件，修補安全性漏洞。
若為開源專案，加入 LICENSE 與 CHANGELOG.md，方便使用者了解授權方式與版本更新內容。

結語

npm 不只是 JavaScript 的套件管理工具，更是分享與重複利用程式碼的重要平台。無論是將常用工具封裝成套件、建立團隊共用函式庫，或是開源自己的專案，只要掌握建立、測試、版本管理與發布流程，就能輕鬆將程式碼分享給全世界的開發者。

希望透過這篇教學，能幫助你完成第一個 npm Package 的發布，並逐步建立屬於自己的套件生態系。未來也可以進一步學習 TypeScript 支援、自動化 CI/CD 發布流程，以及 GitHub Actions 自動部署，打造更完整的套件開發與維護流程。

搜尋此網誌

jeff的blog