Unity 패키지 배포를 Verdaccio에서 Git 기반 UPM으로 전환

배경

Unity 공용 패키지를 UPM으로 배포하기 위해 Verdaccio(사설 npm 저장소)를 썼다. Verdaccio를 쓰면 패키지를 비공개로 관리하고 문서를 함께 둘 수 있다.

Verdaccio 레지스트리는 다음 순서로 구성했다.

1. npm으로 Verdaccio를 전역 설치하고 실행한다. 기본 주소는 http://localhost:4873/이다(Verdaccio 설치).
2. 다른 PC에서 접근하려면 Verdaccio의 config.yaml에서 listen을 0.0.0.0:4873처럼 바꾼다. 기본값은 localhost:4873이라 같은 PC에서만 접근할 수 있다(Verdaccio 설정).
3. 레지스트리에 사용자를 등록하고, 패키지 폴더에서 npm publish --registry <레지스트리 주소>로 배포한다.
4. 패키지를 쓸 프로젝트의 Packages/manifest.json에 scopedRegistries로 레지스트리 주소와 scope를 적고, dependencies에 패키지 이름과 버전을 추가한다.
5. import가 끝나면 Package Manager 창에 패키지가 표시된다.

{
  "scopedRegistries": [
    {
      "name": "Private Registry",
      "url": "http://localhost:4873",
      "scopes": ["com.example"]
    }
  ],
  "dependencies": {
    "com.example.mypackage": "1.0.0"
  }
}

Package Manager는 패키지 이름을 scopes와 비교해 가장 가깝게 맞는 레지스트리에서 받고, 맞는 scope가 없으면 기본 Unity 레지스트리에서 받는다. scope는 역도메인 표기를 쓰고, npm의 @scope 표기는 지원하지 않는다(Unity 매뉴얼: scoped registry 사용).

운영하며 확인한 제약은 다음과 같다.

• 배포할 때마다 패키지 버전을 올려야 한다. npm 레지스트리는 이미 있는 이름과 버전 조합의 publish를 거부하고, unpublish한 버전도 다시 쓸 수 없다(npm publish). 그래서 패키지 버전과 안에 든 에셋의 버전이 어긋날 수 있다.
• 코드가 든 패키지에는 어셈블리 정의 파일(.asmdef)이 있어야 한다. Unity는 Packages 폴더의 스크립트를 asmdef에 속할 때만 컴파일한다. 원래 asmdef가 없던 코드는 배포 전에 Unity에서 만들어 넣는다(Unity 매뉴얼: 패키지의 어셈블리 정의).

각 프로젝트가 패키지를 UPM으로 import하면 프로젝트 Git 저장소 용량과 빌드 시간을 줄일 수 있다.

문제

Verdaccio에는 두 가지 부담이 있었다.

1. 로컬 서버를 직접 운영하므로 헬스 체크가 필요하다.
2. 패키지별 문서를 따로 관리해야 한다.

소스 코드를 GitHub로 관리한다면 Git URL의 쿼리스트링 path로 저장소 하위 경로의 패키지를 지정할 수 있다. 하지만 사용하던 GitLab에서는 이 방식을 쓸 수 없었다. 원인은 확인하지 못했고, 미지원이거나 설치된 GitLab 버전이 낮은 것을 의심한다.

해결

사내 다른 팀이 이미 쓰던 Git 기반 UPM 배포 구조를 따라 패키지 저장소를 구성했다.

• Scope: 다른 팀 패키지와 겹치지 않도록 팀 전용 scope를 따로 등록했다.
• Author: 패키지 매니저에 팀 정보가 제대로 표시되도록 author의 이름·URL 등을 설정했다.
• Dependency: 프로젝트의 dependency를 Verdaccio 레지스트리 대신 Git 저장소를 가리키도록 바꿨다.

설정 후 Unity Package Manager에서 패키지가 정상으로 표시되는 것을 확인했다.