Arbeiten mit der npm-Registry

URL für npm registry

Wenn Sie unter GitHub auf GitHub.com zugreifen, veröffentlichen Sie Pakete in https://npm.pkg.github.com. In den Beispielen in diesem Artikel wird diese URL verwendet.

Wenn Sie unter einer anderen Domain auf GitHub zugreifen, z. B. octocorp.ghe.com, ersetzen Sie „https://npm.pkg.github.com“ durch https://npm.SUBDOMAIN.ghe.com, wobei SUBDOMAIN die eindeutige Unterdomäne Ihres Unternehmens ist.

Authentifizierung bei GitHub Packages

Du benötigst ein Zugriffstoken, um private, interne und öffentliche Pakete zu veröffentlichen, zu installieren und zu löschen.

Du kannst ein personal access token (classic) verwenden, um dich bei GitHub Packages oder der GitHub-API zu authentifizieren. Wenn du ein personal access token (classic) erstellst, kannst du dem Token je nach Bedarf verschiedene Bereiche zuweisen. Weitere Informationen zu paketbezogenen Bereichen für ein personal access token (classic) findest du unter Informationen zu Berechtigungen für GitHub-Pakete.

Um dich bei einer GitHub Packages-Registrierung innerhalb eines GitHub Actions-Workflows zu authentifizieren, kannst du Folgendes verwenden:

• GITHUB_TOKEN, um Pakete zu veröffentlichen, die mit dem Workflowrepository verbunden sind.
• Ein personal access token (classic) mit mindestens dem read:packages-Bereich für die Installation von Paketen, die anderen privaten Repositorys zugeordnet sind (GITHUB_TOKEN kann verwendet werden, wenn das Repository Lesezugriff auf das Paket enthält. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen).

Authentifizieren in einem GitHub Actions Workflow

Diese Registrierung unterstützt präzise Berechtigungen. Für Registries, die feingranulare Berechtigungen unterstützen, empfehlen wir dringend, Ihren GitHub Actions-Workflow, wenn er ein personal access token zur Authentifizierung bei einer Registry verwendet, so zu aktualisieren, dass GITHUB_TOKEN verwendet wird. Anleitungen zum Aktualisieren Ihrer Workflows, die sich mit einer personal access token bei einer Registry authentifizieren, finden Sie in Veröffentlichen und Installieren eines Pakets mit GitHub Actions.

Sie können einen GITHUB_TOKEN in einem GitHub Actions-Workflow verwenden, um über die REST-API ein Paket zu löschen oder wiederherzustellen, wenn das Token über die Berechtigung admin für das Paket verfügt. Repositorys, die Pakete mithilfe eines Workflows veröffentlichen, und Repositorys, die du explizit mit Paketen verbunden hast, erhalten automatisch die admin-Berechtigung für Pakete im Repository.

Weitere Informationen zum GITHUB_TOKEN findest du unter Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows. Weitere Informationen zu den Best Practices bei der Verwendung einer Registrierung in Actions findest du unter Kompromittierte Runner.

Du kannst außerdem auswählen, ob du Zugriffsberechtigungen auf Pakete unabhängig voneinander für GitHub Codespaces und GitHub Actions erteilen möchtest. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen und Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.

Authentifizieren mit einem personal access token

Du musst ein personal access token (classic) mit den entsprechenden Bereichen verwenden, um Pakete in GitHub Packages zu veröffentlichen und zu installieren. Weitere Informationen finden Sie unter Einführung in GitHub-Pakete.

Sie können sich bei GitHub Packages mit npm authentifizieren, indem Sie entweder Ihre benutzerspezifische Datei ~/.npmrc so bearbeiten, dass sie Ihr personal access token (classic) enthält, oder indem Sie sich in der Befehlszeile bei npm mit Ihrem Benutzernamen und Ihrem personal access token anmelden.

Zur Authentifizierung durch Hinzufügen Ihres personal access token (classic) zu Ihrer Datei ~/.npmrc bearbeiten Sie die Datei ~/.npmrc für Ihr Projekt so, dass sie die folgende Zeile enthält, und ersetzen Sie TOKEN durch Ihr personal access token. Erstelle eine neue ~/.npmrc-Datei, wenn keine vorhanden ist.

//npm.pkg.github.com/:_authToken=TOKEN

Um sich durch Anmeldung bei npm zu authentifizieren, verwenden Sie den npm login Befehl, und ersetzen Sie den Benutzernamen durch Ihren Benutzernamen, TOKEN durch Ihre GitHubpersonal access token (classic)und PUBLIC-EMAIL-ADDRESS durch Ihre E-Mail-Adresse.

Wenn du die npm CLI Version 9 oder höher verwendest und du dich über die Befehlszeile bei einer privaten Registrierung anmeldest oder von dieser abmeldest, solltest du die --auth-type=legacy-Option verwenden, um deine Authentifizierungsdetails aus Eingabeaufforderungen einlesen zu können, anstatt den Standardanmeldeflow über einen Browser zu verwenden. Weitere Informationen finden Sie unter npm-login.

Wenn GitHub Packages nicht Ihre Standard-Paket-Registry für die Verwendung mit npm ist und Sie den Befehl npm audit verwenden möchten, empfehlen wir, das Flag --scope mit dem Namespace zu verwenden, der das Paket hostet (das persönliche Konto oder die Organisation , dem bzw. der das Paket zugeordnet wird), wenn Sie sich bei GitHub Packages authentifizieren.

$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN

Veröffentlichen eines Pakets

• Für Paketnamen und Bereiche dürfen nur Kleinbuchstaben verwendet werden.
• Der Tarball für eine npm-Version muss kleiner als 256 MB sein.

Die GitHub Packages Registrierung speichert npm-Pakete innerhalb Ihrer Organisation oder Ihres persönlichen Kontos und ermöglicht es Ihnen, ein Paket einem Repository zuzuordnen. Du kannst wählen, ob Berechtigungen von einem Repository geerbt oder präzise Berechtigungen unabhängig von einem Repository festgelegt werden sollen.

Wenn du ein Paket zum ersten Mal veröffentlichst, ist die Sichtbarkeit standardmäßig auf privat eingestellt. Informationen zum Ändern der Sichtbarkeit oder zum Festlegen von Zugriffsberechtigungen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen. Weitere Informationen zum Verknüpfen eines veröffentlichten Pakets mit einem Repository finden Sie unter Verbinden eines Repositorys mit einem Paket.

Sie können ein Paket mit einem Repository verbinden, sobald das Paket veröffentlicht wird, indem Sie ein repository-Feld in die package.json-Datei einschließen. Sie können diese Methode auch verwenden, um mehrere Pakete mit demselben Repository zu verbinden. Weitere Informationen findest du unter Veröffentlichen mehrerer Pakete im selben Repository.

Du kannst die Bereichszuordnung für dein Projekt entweder mithilfe einer lokalen .npmrc-Datei im Projekt oder mithilfe der publishConfig-Option in der Datei package.json einrichten. GitHub Packages unterstützt nur bereichsbezogene npm-Pakete. Die Namen bereichsbezogener Pakete weisen das Format @NAMESPACE/PACKAGE-NAME auf. Bereichsbezogene Pakete beginnen immer mit dem Symbol @. Möglicherweise musst du den Namen in der Datei package.json aktualisieren, um den bereichsbezogenen Namen zu verwenden. Wenn du beispielsweise der Benutzer octocat bist und dein Paket den Namen test hat, weise den bereichsbezogenen Paketnamen wie folgt zu: "name": "@octocat/test".

Nachdem Du ein Paket veröffentlicht hast, kannst Du das Paket auf GitHub ansehen. Weitere Informationen finden Sie unter Pakete anzeigen.

Veröffentlichen eines Pakets mit einer lokalen .npmrc-Datei

Du kannst eine .npmrc-Datei verwenden, um die Bereichszuordnung für dein Projekt zu konfigurieren. Verwenden Sie in der Datei .npmrc die URL GitHub Packages und den Kontoinhaber, damit GitHub Packages weiß, wohin Paketanforderungen geleitet werden sollen. Durch die Verwendung einer .npmrc Datei wird verhindert, dass andere Entwickler das Paket versehentlich in npmjs.org statt in GitHub Packagesnpmjs.org veröffentlichen.

1. Authentifizieren bei GitHub Packages. Weitere Informationen findest Du unter Authentifizieren bei GitHub Packages.

2. Erstelle oder bearbeite eine .npmrc-Datei in demselben Verzeichnis wie deine package.json-Datei, um eine Zeile einzuschließen, die die GitHub Packages-URL und den Namespace angibt, in dem das Paket gehostet wird. Ersetze NAMESPACE durch den Namen des Benutzer- oder Organisationskontos , auf das das Paket ausgerichtet wird.

   @NAMESPACE:registry=https://npm.pkg.github.com
   

3. Füge die NPMRC-Datei dem Repository hinzu, in dem GitHub Packages dein Projekt finden kann. Weitere Informationen finden Sie unter Eine Datei zu einem Repository hinzufügen.

4. Überprüfe den Namen deines Pakets in der Datei package.json deines Projekts. Das Feld name muss den Bereich und den Namen des Pakets enthalten. Wenn Ihr Paket beispielsweise als "test" bezeichnet wird und Sie es in der Organisation "Meine Organisation" GitHub veröffentlichen, sollte das name Feld in Ihrem package.json Feld lauten @my-org/test.

5. Überprüfe das repository-Feld in der Datei package.json deines Projekts. Das Feld repository muss mit der URL für Ihr GitHub-Repository übereinstimmen. Wenn ihre Repository-URL beispielsweise github.com/my-org/test lautet, sollte das Repositoryfeld https://github.com/my-org/test.git lauten.

6. Das Paket veröffentlichen:

   npm publish
   

Veröffentlichen eines Pakets mithilfe von publishConfig in der Datei package.json

Du kannst das publishConfig-Element in der Datei package.json verwenden, um die Registrierung anzugeben, in der das Paket veröffentlicht werden soll. Weitere Informationen findest du unter publishConfig in der npm-Dokumentation.

1. Bearbeite die Datei package.json für dein Paket, und füge einen publishConfig-Eintrag ein.

   "publishConfig": {
     "registry": "https://npm.pkg.github.com"
   },
   

2. Überprüfe das repository-Feld in der Datei package.json deines Projekts. Das Feld repository muss mit der URL für Ihr GitHub-Repository übereinstimmen. Wenn ihre Repository-URL beispielsweise github.com/my-org/test lautet, sollte das Repositoryfeld https://github.com/my-org/test.git lauten.

3. Das Paket veröffentlichen:

   npm publish
   

Veröffentlichen mehrerer Pakete im gleichen Repository

Wenn Sie mehrere Pakete veröffentlichen und mit demselben Repository verknüpfen möchten, können Sie die URL des GitHub Repositorys in das repository Feld der package.json Datei für jedes Paket einschließen. Weitere Informationen findest du unter Erstellen einer package.json-Datei und Erstellen von Node.js-Modulen in der npm-Dokumentation.

Um sicherzustellen, dass die URL des Repositorys korrekt ist, ersetzen Sie REPOSITORY durch den Namen des Repositorys, das das Paket enthält, das Sie veröffentlichen möchten, und OWNER durch den Namen des persönlichen Kontos oder der Organisation, das GitHub das Repository besitzt.

GitHub Packages entspricht dem Repository basierend auf der URL.

"repository":"https://github.com/OWNER/REPOSITORY",

Installieren eines Pakets

Sie können Pakete von GitHub Packages installieren, indem Sie die Pakete als Abhängigkeiten in der Datei package.json Ihres Projekts hinzufügen. Weitere Informationen zum Verwenden einer package.json-Datei in deinem Projekt findest du unter Arbeiten mit package.json in der npm-Dokumentation.

Du kannst Pakete standardmäßig aus einer Organisation hinzufügen. Weitere Informationen findest du unter Installieren von Paketen aus anderen Organisationen.

Außerdem müssen Sie die Datei .npmrc Ihrem Projekt hinzufügen, damit alle Anfragen zur Installation von Paketen über GitHub Packages geleitet werden. Wenn Sie alle Paketanfragen über GitHub Packages leiten, können Sie sowohl Pakete mit als auch ohne Bereich von npmjs.org verwenden. Weitere Informationen finden Sie unter npm-scope in der npm-Dokumentation.

1. Authentifizieren bei GitHub Packages. Weitere Informationen findest Du unter Authentifizieren bei GitHub Packages.

2. Erstelle oder bearbeite eine .npmrc-Datei in demselben Verzeichnis wie deine package.json-Datei, um eine Zeile einzuschließen, die die GitHub Packages-URL und den Namespace angibt, in dem das Paket gehostet wird. Ersetze NAMESPACE durch den Namen des Benutzer- oder Organisationskontos , auf das das Paket ausgerichtet wird.

   @NAMESPACE:registry=https://npm.pkg.github.com
   

3. Füge die NPMRC-Datei dem Repository hinzu, in dem GitHub Packages dein Projekt finden kann. Weitere Informationen finden Sie unter Eine Datei zu einem Repository hinzufügen.

4. Konfiguriere package.json in deinem Projekt, um das Paket zu verwenden, das du installierst. Um Ihre Paketabhängigkeiten zur Datei package.json für GitHub Packages hinzuzufügen, geben Sie den vollständig qualifizierten Paketnamen an, z. B. @my-org/server. Gib für Pakete aus npmjs.com den vollständigen Namen (z. B. @babel/core oder lodash) an. Ersetze ORGANIZATION_NAME/PACKAGE_NAME durch deine Paketabhängigkeit.

   {
     "name": "@my-org/server",
     "version": "1.0.0",
     "description": "Server app that uses the ORGANIZATION_NAME/PACKAGE_NAME package",
     "main": "index.js",
     "author": "",
     "license": "MIT",
     "dependencies": {
       "ORGANIZATION_NAME/PACKAGE_NAME": "1.0.0"
     }
   }
   

5. Installiere das Paket.

   npm install
   

Pakete von anderen Organisationen installieren

Standardmäßig können Sie nur Pakete aus einer Organisation verwenden GitHub Packages . Wenn Sie Paketanforderungen an mehrere Organisationen und Benutzer weiterleiten möchten, können Sie Ihrer .npmrc-Datei zusätzliche Zeilen hinzufügen, wobei Sie NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation ersetzen, auf die das Paket beschränkt ist.

@NAMESPACE:registry=https://npm.pkg.github.com
@NAMESPACE:registry=https://npm.pkg.github.com