基于Gitea搭建本地npm包服务

0x01 创建 Node 项目

1. 新建文件夹作为自定义代码包的项目目录

2. 使用命令 npm init -y 快速搭建 Node 环境

3. 使用命令 npm install --save-dev tsup typescript 安装打包相关包

   • tsup 用于构建 npm 包
   • typescript 用于构建 npm 包中的类型声明文件 .d.ts

4. 修改 package.json

   {
     "name": "@my/custom-package",
     "version": "1.0.0",
     "description": "",
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",
     "types": "./dist/index.d.ts",
     "exports": {
       ".": {
         "require": "./dist/index.js",
         "import": "./dist/index.mjs",
         "types": "./dist/index.d.ts"
       }
     },
     "files": [
       "dist",
       "README.md"
     ],
     "scripts": {
       "build": "tsup",
       "dev": "tsup --watch",
       "prepublishOnly": "npm run build"
     },
     "publishConfig": {
       "registry": "http://{Gitea 地址}/api/packages/{用户名}/npm/"
     },
     "keywords": [],
     "author": "",
     "license": "ISC",
     "devDependencies": {
       "tsup": "^8.5.1",
       "typescript": "^5.9.3"
     }
   }
   
   

5. 在根目录中创建并编辑以下文件：

   1. .gitignore：用于 Git 提交时忽略指定文件

      node_modules/
      dist/
      .DS_Store
      

   2. tsup.config.js：用于配置 tsup

      import { defineConfig } from "tsup";
      
      export default defineConfig({
        entry: ["src/index.js"], // 入口文件
        format: ["cjs", "esm"], // 同时生成 CommonJS 和 ES Module
        dts: true, // 自动生成 .d.ts 类型声明文件 (让JS包也有类型提示)
        splitting: false, // 代码拆分 (库通常不需要)
        sourcemap: true, // 生成源码映射，方便调试
        clean: true, // 每次打包前清空 dist 目录
      });
      
      

   3. jsconfig.json：用于配置项目中的 JavaScript 检查选项（可选）

      {
        "compilerOptions": {
          "module": "ES2022", // 或 "ESNext" / "ES2020"
          "moduleResolution": "node", // 使别名生效
          "target": "ES2022", // 按需
          "baseUrl": ".",
          "paths": {
            "@/*": ["src/*"]
          }
        },
        "include": ["src/**/*"]
      }
      
      

   4. src/index.js：上文指定的自定义包入口文件，以下为示例

      /**
       * 一个简单的加法函数
       * @param {number} a
       * @param {number} b
       */
      export const add = (a, b) => {
        console.log("Running add function from Gitea package!");
        return a + b;
      };
      
      export const sayHello = (name) => `Hello, ${name}!`;
      
      

6. 使用命令 npm run build 查看打包效果

0x02 创建 Gitea 权限

Gitea 版本为1.24.2

1. 在 Gitea 的“设置”中找到“应用”
2. 选择“生成新的令牌”，编辑新的令牌名称（名称可自定义，如 npm-publish）
3. 令牌权限必须包含“读写 repository”权限
4. 点击“生成令牌”后，复制令牌的内容

0x03 注册与发布

Gitea 官方文档关于 npm 包注册的指南

1. 在本地终端，使用如下命令配置 npm 仓库权限

   npm config set {域}:registry=https://{Gitea地址}/api/packages/{用户名}/npm/
   npm config set -- '//{Gitea地址}/api/packages/{用户名}/npm/:_authToken' "{令牌}"
   

   如

   npm config set `@my:registry=https://192.168.1.2:3000/api/packages/username/npm/`
   '//192.168.1.2:3000/api/packages/username/npm/:_authToken' "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   

2. 在项目中，使用命令 npm run build 打包，使用 npm publish 进行发布

0x04 使用自发布的包

1. 在项目中使用命令 npm install @my/custom-package

2. 在项目文件中加入如下内容：

   import { add, sayHello } from '@my/custom-package';
   
   console.log(sayHello('World'));
   console.log('1 + 2 =', add(1, 2));
   

3. 编译并运行测试

0x05 更新

（1）版本更新

[major].[minor].[patch]，如 1.2.3

1. 补丁更新：npm version patch

   适用于：Bug 修复，不改变现有功能接口

2. 次版本更新：npm version minor

   适用于：新增功能，但向下兼容（不破坏现有代码）

3. 主版本更新：npm version major

   适用于：重大重构或不兼容的 API 变更

4. 指定特定版本号：npm version 1.2.3

• 版本号更新后会自动添加 git 提交记录
  • 取消自动 git 与 tag：npm version [patch|minor|major] --no-git-tag-version
• 需要手动使用命令 npm run build 与 npm publish 进行打包与发布

• 预发布版本：npm version prerelease --preid=beta
  • 效果为：1.0.1-beta.0 -> 1.0.1-beta.1

（2）标签发布

• 最新标签：npm publish --tag latest
• 测试标签：npm publish --tag beta

0x06 引入测试（Vitest）

1. 使用命令 npm install --save-dev vitest 按照 Vitest

2. 在项目根目录创建 vitest.config.ts 来配置 Vitest

   适用于 TypeScript，JavaScript 环境则创建 vitest.config.js

   import { defineConfig } from "vitest/config";
   
   export default defineConfig({
     test: {
       include: ["test/**/*.test.ts"],
       globals: false,
       environment: "node", // node / jsdom
       coverage: {
         provider: "v8",
         reporter: ["text", "json", "html"],
       },
     },
   });
   

   • include 用于指定测试文件路径

   • globals 用于开关全局变量支持

     • true：需要在 tsconfig.json 中添加：

       {
         "compilerOptions": {
           "types": ["vitest/globals"]
         }
       }
       

     • false：需要在测试中手动 import Vitest 的方法

   • environment 用于指定包的运行环境

     • node：Node.js 环境
     • jsdom：浏览器环境，须要使用命令 npm install --save-dev jsdom 安装 jsdom 依赖

   • coverage 用于配置覆盖测试工具

     • 上述配置须要使用命令 npm install -D @vitest/coverage-v8 安装 coverage-v8 依赖

3. 配置 package.json

   {
     "scripts": {
       "test": "vitest",                 // 开发模式：监听文件变化并重新运行
       "test:run": "vitest run",         // CI 模式：运行一次即结束
       "test:ui": "vitest --ui",         // 启动可视化的 UI 界面 (可选)
       "coverage": "vitest run --coverage" // 生成测试覆盖率报告
     }
   }
   

4. 按照上述配置中指定的测试目录，创建 [模块名].test.[ts|js] 文件，并在其中编写测试代码

   参考 《Vitest 快速上手 | SRIGT-博客园》

5. 使用命令 npm run test 测试，npm run coverage 生成覆盖测试报告

内联测试：

• vitest.config.ts 补充以下配置

  export default defineConfig({
    define: {
      'import.meta.vitest': 'undefined', // 生产构建时移除测试代码
    },
    test: {
      includeSource: ['src/**/*.{js,ts}'], 
    },
  });
  

• 源码文件中

  function internalHelper(str: string) {
    return str.toUpperCase();
  }
  
  // 源码内的测试代码
  if (import.meta.vitest) {
    const { it, expect } = import.meta.vitest;
    it('internalHelper works', () => {
      expect(internalHelper('foo')).toBe('FOO');
    });
  }
  

-End-