1. 給 npm 包取個【唯一】的名字！

npm 包命名規范

• 只能包含小寫字母（a-z）、數字（0-9）、連字符（-） 和 下劃線（_），不能包含空格、大寫字母、標點符號（除連字符和下劃線外）或特殊字符（如 !、@、# 等）
• 長度不超過 214 個字符
• 建議以字母開頭
• 連字符（-）常用于分隔單詞（如 react-dom），下劃線（_）使用較少，避免連續使用連字符或下劃線（如 my–package 不推薦）
• 名稱應簡潔易記，體現包的具體功能
• 避免禁用的名稱，如 fs、npm、package、install、publish 等

范圍包

包名格式如下的為范圍包，適合個人或企業發布的系列包，如 @vue/cli 等

@scope/package-name

• scope 是npm 用戶名或組織名

在發布時，默認為私有范圍包（僅自己或授權用戶可見，且需要付費），可指定為公共范圍包（所有人可見可安裝，免費）

npm publish --access public

檢驗包名是否唯一

npm search 包名

或在 npm官網 中搜索試試

2. 創建項目

推薦的項目目錄結構

package-name/
├── package.json          # 包核心配置（必選）
├── README.md             # 包說明文檔（必選）
├── LICENSE               # 開源許可證（推薦）
├── CHANGELOG.md          # 版本變更記錄（推薦）
├── .gitignore            # Git 忽略文件
├── .npmignore            # npm 發布忽略文件（可選，默認繼承.gitignore）
├── tsconfig.json         # TypeScript 配置（如使用 TS）
├── src/                  # 源代碼目錄（核心邏輯）
│   ├── index.js          # 入口文件（導出核心功能）
│   ├── utils/            # 工具函數/輔助模塊
│   ├── core/             # 核心業務邏輯
│   ├── types/            # 類型定義（如使用 TS 或 JSDoc）
│   └── constants/        # 常量定義
├── dist/                 # 編譯/打包后的輸出目錄
│   ├── index.js          # 編譯后的入口文件
│   ├── index.cjs         # CommonJS 版本（如支持雙模塊）
│   └── index.mjs         # ES 模塊版本（如支持雙模塊）
├── test/                 # 測試目錄
│   ├── unit/             # 單元測試
│   ├── integration/      # 集成測試
│   └── fixtures/         # 測試用例數據
├── docs/                 # 詳細文檔（可選）
├── examples/             # 使用示例（可選）
└── scripts/              # 輔助腳本（如構建、發布腳本）

• 小型包可簡化結構（如省略 core/、docs/ 等目錄）。
• 前端工具包可能需要 browser/ 目錄區分瀏覽器環境代碼。
• 命令行工具需在 package.json 中配置 bin 字段，并在 src/ 中添加 CLI 入口。

使用 vite 的庫模式開發

因 vite 并沒有提供現成簡易的模板，建議按下文的方式創建項目

以包名 @ecclub/util 為例，創建文件夾 “util” ，內部目錄結構為：

具體代碼如下：

src/index.ts

按需改成任意業務代碼，但一定要用 export 對外導出！

export function sum(a: number, b: number) {return a + b;
}

.gitignore

node_modules/
dist/

package.json

需自定義的字段有：

• name 包的名稱
• description 包的描述
• keywords 包的關鍵詞數組
• author 包的作者

相關的依賴根據需要添加，已添加的依賴可以考慮升級到最新版

{"name": "@ecclub/util","version": "1.0.0","type": "module","description": "EC編程俱樂部開發的工具庫","main": "./dist/index.umd.cjs","module": "./dist/index.js","types": "./dist/index.d.ts","files": ["dist","index.d.ts"],"scripts": {"build": "tsc && vite build"},"keywords": ["util"],"author": "朝陽 <603092378@qq.com>","license": "MIT","devDependencies": {"typescript": "~5.9.2","vite": "^7.0.6","vite-plugin-dts": "^4.5.4"}
}

tsconfig.json

基本無需更改，可根據需要添加 ts 配置

{"compilerOptions": {"target": "es2022","useDefineForClassFields": true,"module": "esnext","lib": ["ES2022", "DOM", "DOM.Iterable"],"skipLibCheck": true,/* Bundler mode */"moduleResolution": "bundler","allowImportingTsExtensions": true,"isolatedModules": true,"moduleDetection": "force","noEmit": true,/* Linting */"strict": true,"noUnusedLocals": true,"noUnusedParameters": true,"noFallthroughCasesInSwitch": true,"noUncheckedSideEffectImports": true},"include": ["src"]
}

vite.config.ts

基本無需更改，可根據需要添加 vite 配置

import { defineConfig } from "vite";
import dts from "vite-plugin-dts";export default defineConfig({build: {lib: {entry: "./src/index.ts",name: "index",fileName: "index",},},plugins: [dts({// 生成類型聲明文件insertTypesEntry: true,}),],
});

使用 npm 開發

以包名 mypack-test 為例

1. 新建文件夾 mypack-test

2. 用vscode 打開文件夾 mypack-test

3. 終端執行 npm init 生成 package.json 文件，按提示輸入相關信息或一路回車，最后輸入 y 回車即可。
   
   藍框內的部分為包的信息，可根據需要自行輸入（或等生成package.json后再修改）

   package.json 中各字段的含義詳見
   https://blog.csdn.net/weixin_41192489/article/details/150345315

4. 新建文件index.js，內容為
   要點：定義的函數/變量一定要對外導出！

   /*函數功能——求和參數——兩個數字
   */
   function sum(a, b) {return a + b;
   }module.exports = {sum: sum,
   };

5. 新建文件README.md，內容為包相關的信息

6. 新建文件 .npmignore，內容為發布時不需要打包的文件，如

   node_modules
   *.log
   

3. 打包項目

若使用 npm 開發則跳過此步

此處以 vite 庫模式開發為例：

先安裝依賴

npm i

再執行打包腳本

得到

4. 發布 npm 包

先檢查 npm 的下載源是否為官方源，若不是，則需重新設置為官方源

npm config set registry https://registry.npmjs.org/

注冊 npm 賬號

npm adduser

或者直接去官網注冊 https://www.npmjs.com/

登錄 npm 賬號

npm login

按提示按下 Enter 后，會用瀏覽器打開 npm 官網進行登錄

輸入賬號密碼后，點擊登錄按鈕

輸入注冊 npm 賬號時綁定的郵箱中收到的一次性驗證碼后點擊登錄按鈕

回到命令行，可見已完成登錄

發布非范圍包

npm publish

發布范圍包

需先在 npm 官網創建組織

輸入自定義的組織名（需全網唯一）后點擊 Create 按鈕

創建成功后，可見

在 package.json 中，我們定義的包名為

  "name": "@ecclub/util",

現在可以發布包啦！

npm publish --access public

驗證是否發布成功

方法一：在官網（按最新發布）搜索包名

方法二：用命令行驗證

npm view @ecclub/util

方法三：安裝包試用

npm i @ecclub/util

頁面中使用

import { sum } from "@ecclub/util";console.log(sum(1, 2)); // 得到 3

5. 修改 npm 包后重新發布

打包項目

同第 3 步

更新版本號

• 修復bug，例如 1.0.0 → 1.0.1

npm version patch

• 新增功能，例如 1.0.1 → 1.1.0

npm version minor   

• 不兼容舊版本的更新，需升級主版本，如 1.1.0 → 2.0.0

npm version major

可見 package.json 中版本號發生了變化

  "version": "1.2.0",

（也可不執行命令，直接手動修改 package.json 中的版本號）

發布修改后的 npm 包

同第 4 步