npm in gitlab : Packages and Registries #198

Open WangShuXian6 opened 2 months ago

软件包和注册表

https://docs.gitlab.com/ee/user/packages/ https://docs.gitlab.com/ee/user/packages/package_registry/ https://www.youtube.com/watch?v=ui2nNBwN35c GitLab Single Project Package Registry Demo GitLab 包注册表 package registry充当私有或公共注册表对于各种常见的包管理器。您可以发布和共享包，可以很容易地将其用作下游项目中的依赖项。

通过仓库源的方式发布和使用 gitlab npm 包

注意，该方式不适合通过编译压缩打包的带样式的包，因为样式文件在 pnpm 中链接错误。同时通过 npm i 安装会失败

如果 React TypeScript 包不需要编译为 JavaScript，可以直接发布 TypeScript 源码，并在使用时依赖项目的 TypeScript 编译器来处理代码

仅适合不包含样式的文件

第 1 步：初始化项目

创建项目文件夹并初始化 npm 包：

mkdir example_project
cd example_project
npm init -y

安装 React 和 TypeScript 类型声明：

npm install react react-dom
npm install --save-dev @types/react @types/react-dom typescript

第 2 步：编写 React 组件

创建 src 文件夹，并在其中添加您的组件。例如，创建 src/MyComponent.tsx 文件：

   // src/MyComponent.tsx
import React from 'react'

interface MyComponentProps {
  text: string
}

export const MyComponent = ({ text }: MyComponentProps) => {
  return <div>{text}</div>
}

创建一个入口文件，例如 src/index.ts，用于导出组件：

   // src/index.ts
export * from './MyComponent'
   //export { default as MyComponent } from './MyComponent';

第 3 步：配置 `package.json`

在 package.json 文件中，确保 main 和 types 指向源码中的 TypeScript 文件，而不是编译后的文件。例如：

注意所有的依赖的版本必须低于或等于使用该包的项目的依赖

{
  "name": "example_project",
  "version": "1.0.0",
  "main": "src/index.ts",
  "types": "src/index.ts",
  "dependencies": {
    "react": "^17.0.0",
    "react-dom": "^17.0.0"
  },
  "devDependencies": {
    "@types/react": "^17.0.0",
    "@types/react-dom": "^17.0.0"
  }
}

第 4 步：创建 TypeScript 配置文件：

npx tsc --init

tsconfig.json

  "compilerOptions": {
    "target": "ES6",
    "module": "ES6",
    "jsx": "react",
    "declaration": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]

在这个配置文件中：

target: 设置生成的代码目标为 ES6。
module: 设置模块系统为 ES6，可以被现代前端项目识别。
jsx: 指定 React 的 JSX 支持。
declaration: 即使没有编译为 JavaScript，也可以生成 .d.ts 声明文件（用于类型提示）。
strict: 启用严格的类型检查。
esModuleInterop: 确保 CommonJS 和 ES6 模块之间的兼容性。
skipLibCheck: 跳过类型库检查，避免因依赖的类型库版本不一致而产生的报错。
include: 仅包含 src 文件夹中的代码。

发布时忽略 `tsconfig.json`

在发布 npm 包时，如果不希望 tsconfig.json 被包含，可以在 package.json 的 files 字段中指定要发布的文件：

{
  "files": [
    "src/**/*"
  ]
}

或者使用 .npmignore 文件，将 tsconfig.json 排除：

tsconfig.json

总结

虽然不编译为 JavaScript，但 tsconfig.json 文件在开发阶段和使用包的项目中都非常有用。它不会影响包的运行，只会为开发者提供更好的开发体验，并为消费项目提供一致的配置。

第 5 步：将代码推送到 GitLab 并添加标签

初始化 Git 并添加远程仓库：

git init
git add .
git commit -m "Initial commit"
git remote add origin https://gitlab.com/your_username/example_project.git
git push -u origin main

为发布添加标签：
```
git tag v1.0.0
git push origin v1.0.0
```

第 6 步：发布并使用该包

在项目中安装并直接使用未编译的源码包：

npm install git+https://gitlab.com/your_username/example_project.git#v1.0.0

网络异常时，可以直接在 package.json 中声明依赖项 dependencies

"react-admin-suite":"git+https://gitlab.com/your_username/example_project.git#v1.0.0"

然后安装

npm i

在项目中使用组件：

import { MyComponent } from 'example_project';

function App() {
  return <MyComponent text="Hello from MyComponent!" />;
}

第 7 步：发布新版本

对包进行更改后，可以通过增加新标签的方式发布新版本。例如，将版本更新为 v1.1.0：

更新 package.json 文件：将 version 字段改为 1.1.0。
提交更改：

   git add .
   git commit -m "Update to version 1.1.0"

创建新标签并推送：

   git tag v1.1.0
   git push origin v1.1.0

~~### 第 8 步：在 package.json 中自动发布版本（可选）~~ 待优化 ~~可以在 package.json 的 scripts 字段中添加一条命令，以便自动化发布流程：~~

{
  "name": "example_project",
  "version": "1.1.0",
  "scripts": {
    "release": "git add . && git commit -m 'Release $npm_package_version' && git tag v$npm_package_version && git push origin main && git push --tags"
  }
}

~~然后，您可以运行以下命令自动更新标签和推送：~~

git add .
git commit -m "Save changes before version update"
npm version patch # 或 npm version minor / npm version major
npm run release

~~这会自动更新 package.json 的版本号、创建提交并打上相应标签，推送到 GitLab。~~

windows 会报错 `error: pathspec '$npm_package_version'' did not match any file(s) known to git`

这个错误通常是因为 Shell 没有正确解析 $npm_package_version 环境变量。在某些 Shell 中，例如 Windows 的默认命令提示符（cmd），环境变量的格式不同。npm_package_version 是一个 npm 自动注入的环境变量，但不同系统的引用方式可能有所不同。

解决方法

使用跨平台变量格式

如果您的操作系统是 Windows，请尝试使用以下格式替换 $npm_package_version：

%npm_package_version%

您的 release 脚本可以修改为以下形式：

"scripts": {
 "release": "git add . && git commit -m \"Release %npm_package_version%\" && git tag v%npm_package_version% && git push  origin main && git push --tags"
}

2. 使用 cross-env 模块（推荐，跨平台） 测试不可用，需要修复

~~使用 cross-env 模块，您可以在不同平台上统一变量格式。安装 cross-env：~~

   npm install cross-env --save-dev

~~然后，将 release 脚本更新为以下格式：~~

   "scripts": {
     ~~"release": "cross-env VERSION=$npm_package_version git add . && git commit -m \"Release $VERSION\" && git tag v$VERSION && git push  origin main && git push --tags"~~
   }

~~这样，cross-env 会自动处理变量格式，使其适用于不同操作系统。~~

直接在 npm 命令中使用 npm version

如果您主要使用 npm version 来触发 release，可以简化脚本，因为 npm version 会自动处理版本变量并生成相应的标签。更新 release 脚本如下：

   "scripts": {
     "release": "npm version patch && git push  origin main && git push --tags"
   }

运行 npm run release 将直接更新 package.json 中的版本号、生成标签并推送到 Git 仓库。这是最简洁的一种方法，因为 npm version 内置了对版本号和标签的管理。

总结

根据您的操作系统选择相应的方法。如果您希望跨平台兼容，使用 cross-env 是最灵活的解决方案。

注意事项

TypeScript 配置：确保使用该包的项目的 tsconfig.json 文件中配置了 include 或 exclude 以包含外部模块的 .ts 和 .tsx 文件。大多数情况下，默认配置即可处理。
Peer Dependencies：由于包依赖 React，您可以在 package.json 中将其列为 peerDependencies，确保使用者自行安装正确版本的 React。

示例 `peerDependencies` 配置：

{
  "peerDependencies": {
    "react": "^17.0.0",
    "react-dom": "^17.0.0"
  }
}

通过这种方式，您可以直接发布 TypeScript 源码，无需编译为 JavaScript，也无需 dist 文件夹。

总结

通过这些步骤，您已经完成了从 0 到 1 的 npm 包发布流程，包含代码编写、初始化 Git 仓库、标签版本发布等。每次更新版本时，只需修改代码、提交、更新标签并推送即可发布新版本。

WangShuXian6 / blog