Unity और npm पैकेज

हर Arkvory रिपॉज़िटरी https://<host>/npm/<repository>/ पर एक npm-संगत रजिस्ट्री है। Unity Package Manager इसे स्कोप्ड रजिस्ट्री के रूप में पढ़ता है, और npm इसमें प्रकाशित करता है तथा इससे इंस्टॉल करता है। स्टूडियो इसे उन SDK, टूल और मॉड्यूल के लिए इस्तेमाल करते हैं जो कई Unity प्रोजेक्ट साझा करते हैं, हर एक के अपने संस्करण के साथ।

पैकेज tarball साधारण आर्टिफ़ैक्ट हैं, इसलिए रिपॉज़िटरी अनुमतियाँ, कोटा, SHA-256 जाँच, बैकअप और मिरर उन पर लागू होते हैं।

शुरू करने से पहले

आपको चाहिए:

HTTPS वाला सर्वर पता (HTTPS देखें)।
एक रिपॉज़िटरी, उदाहरण के लिए games। इसका रजिस्ट्री पता https://arkvory.example/npm/games/ है।
एक कुंजी। डेवलपर read स्कोप वाला व्यक्तिगत एक्सेस टोकन इस्तेमाल करते हैं। प्रकाशित करने वाले बिल्ड एजेंट read-write स्कोप वाला व्यक्तिगत टोकन या एक सेवा कुंजी इस्तेमाल करते हैं। खाते और कुंजियाँ देखें।

Arkvory पैकेज डेटा में हर tarball का पता क्लाइंट को भेजता है। पता उस होस्ट नाम से बनाया जाता है जिससे क्लाइंट आया। जब कोई रिवर्स प्रॉक्सी HTTPS समाप्त करता है, तो उसे Host हेडर पास करना चाहिए और X-Forwarded-Proto: https भेजना चाहिए, जैसे इंस्टॉलेशन के nginx उदाहरण में। अन्यथा क्लाइंट को tarball के http:// पते मिलते हैं।

Unity प्रोजेक्ट में रजिस्ट्री जोड़ें

प्रोजेक्ट का Packages/manifest.json खोलें और एक स्कोप्ड रजिस्ट्री जोड़ें:

json

{
  "scopedRegistries": [
    {
      "name": "Arkvory",
      "url": "https://arkvory.example/npm/games/",
      "scopes": ["com.proanima"]
    }
  ],
  "dependencies": {
    "com.proanima.tools": "1.2.0"
  }
}

Unity को कुंजी दें। इसे प्रोजेक्ट में न रखें। अपने उपयोगकर्ता फ़ोल्डर में .upmconfig.toml फ़ाइल बनाएँ (Windows पर %USERPROFILE%\.upmconfig.toml, macOS और Linux पर ~/.upmconfig.toml):

toml

[npmAuth."https://arkvory.example/npm/games/"]
token = "<your Arkvory key>"
alwaysAuth = true

Unity को रीस्टार्ट करें। Package Manager विंडो में, रजिस्ट्री के पैकेज देखने के लिए My Registries खोलें।

टिप्पणियाँ:

scopes पैकेज नामों के उपसर्ग हैं। Unity उन पैकेजों को Arkvory से लेता है जिनके नाम किसी स्कोप से शुरू होते हैं, और बाकी सभी पैकेज Unity रजिस्ट्री से लेता है।
.upmconfig.toml में पता manifest के url जैसा ही होना चाहिए, अंतिम स्लैश सहित।
alwaysAuth = true ज़रूरी है। रजिस्ट्री लॉगिन चैलेंज नहीं भेजती, इसलिए Unity को हर अनुरोध के साथ टोकन भेजना चाहिए।
Unity पैकेज नाम छोटे अक्षरों में उल्टे डोमेन नाम होते हैं, जैसे com.company.package। Unity @scope/ वाले नामों का समर्थन नहीं करता।

Packages/manifest.json को प्रोजेक्ट के साथ कमिट करें। हर डेवलपर अपना .upmconfig.toml रखता है।

पैकेज प्रकाशित करें

एक पैकेज शीर्ष पर package.json वाला एक फ़ोल्डर है। इसे npm से प्रकाशित करें।

पैकेज के फ़ोल्डर में एक .npmrc फ़ाइल बनाएँ:

ini

registry=https://arkvory.example/npm/games/
//arkvory.example/npm/games/:_authToken=${ARKVORY_TOKEN}

एनवायरनमेंट में कुंजी सेट करें और प्रकाशित करें:

bash

export ARKVORY_TOKEN="$(cat ~/.arkvory/key)"
npm publish

powershell

$env:ARKVORY_TOKEN = (Get-Content C:\Private\arkvory.key -Raw).Trim()
npm publish

_authToken वाली पंक्ति रजिस्ट्री के पते से शुरू होनी चाहिए, https: के बिना। कुंजी को .npmrc से बाहर रखें: npm एनवायरनमेंट से ${ARKVORY_TOKEN} बदल देता है।

.npmrc में registry पंक्ति के बजाय, आप रजिस्ट्री को पैकेज के package.json में सेट कर सकते हैं:

json

{
  "name": "com.proanima.tools",
  "version": "1.2.0",
  "publishConfig": { "registry": "https://arkvory.example/npm/games/" }
}

रजिस्ट्री क्या जाँचती है:

नाम और संस्करण। tarball के अंदर package.json में name और version प्रकाशित वाले से मेल खाने चाहिए। संस्करण SemVer 2.0.0 का पालन करता है, उदाहरण के लिए 1.2.0 या 2.0.0-beta.1। रजिस्ट्री संस्करण का डेटा इस फ़ाइल से पढ़ती है, उस JSON से नहीं जो क्लाइंट भेजता है।
चेकसम। क्लाइंट जो लंबाई, shasum और integrity घोषित करता है, वे बाइट से मेल खाने चाहिए। बेमेल होने पर 422 integrity_mismatch लौटता है।
tarball। उसमें <folder>/package.json होना चाहिए, जैसा npm pack बनाता है। आर्काइव में दूसरा package.json अस्वीकार कर दिया जाता है, क्योंकि npm और रजिस्ट्री अलग फ़ाइलें पढ़ सकते हैं।
संस्करण अपरिवर्तनीय है। वही tarball दोबारा प्रकाशित करने पर सफलता मिलती है और कुछ नहीं बदलता (200)। मौजूद संस्करण के लिए दूसरी सामग्री 409 लौटाती है, कारण version_exists के साथ। सुधार को अगले संस्करण के रूप में प्रकाशित करें।

npm publish प्रकाशित करने से पहले रजिस्ट्री से पैकेज पढ़ता है, इसलिए प्रकाशन कुंजी को upload.create के साथ-साथ content.read और artifact.list भी दें। अनुमतियाँ देखें।

npm publish लौटते ही संस्करण उपलब्ध हो जाता है। किसी संस्करण का tarball <name>-<version>.tgz आर्टिफ़ैक्ट के रूप में npm लेबल के साथ सहेजा जाता है। स्कोप वाले नाम के लिए, @team/util बन जाता है util-<version>.tgz।

पैकेज इंस्टॉल करें

Unity में, manifest में निर्भरता जोड़ें या Package Manager विंडो में My Registries के अंतर्गत पैकेज चुनें।

npm के लिए, प्रोजेक्ट या अपने उपयोगकर्ता की .npmrc में रजिस्ट्री सेट करें। एक स्कोप के लिए रजिस्ट्री सामान्य विकल्प है, क्योंकि Arkvory सार्वजनिक npm रजिस्ट्री को अनुरोध अग्रेषित नहीं करता:

ini

@team:registry=https://arkvory.example/npm/games/
//arkvory.example/npm/games/:_authToken=${ARKVORY_TOKEN}

bash

npm install @team/util
npm view @team/util versions
npm search tools

अगर आप पूरे प्रोजेक्ट के लिए registry= को Arkvory पर सेट करते हैं, तो npm हर पैकेज वहीं ढूँढता है, जिनमें lodash जैसे सार्वजनिक पैकेज भी शामिल हैं, और 404 के साथ विफल हो जाता है। स्कोप्ड रजिस्ट्री या ऐसा प्रोजेक्ट इस्तेमाल करें जिसमें केवल आपके अपने पैकेज हों।

npm इंस्टॉल करते समय dist.integrity जाँचता है और रजिस्ट्री का पता package-lock.json में लिखता है।

संस्करण और dist-tags

एक dist-tag किसी संस्करण के लिए एक हटाया-धराया जा सकने वाला नाम है। npm publish latest को नए संस्करण पर सेट करता है। दूसरे टैग रिलीज़ चैनलों को अलग करने में मदद करते हैं।

bash

npm publish --tag beta
npm dist-tag add com.proanima.tools@1.3.0 latest
npm dist-tag ls com.proanima.tools
npm dist-tag rm com.proanima.tools beta

bash

npm install com.proanima.tools@beta

नियम	मान
टैग नाम	किसी अक्षर से शुरू होता है। अक्षर, अंक, `.`, `_` और `-`। अधिकतम 64 अक्षर।
वर्जित टैग	संस्करण जैसा दिखने वाला नाम (`v1`, `v2.0`), और `x` या `X`
`latest`	हमेशा किसी संस्करण की ओर इशारा करता है। इसे हटाया नहीं, बदला जा सकता है (`409`)।
टैग बदलना	`npm dist-tag add`, या `--tag` के साथ प्रकाशित करना। नया संस्करण मौजूद होना चाहिए।

एक टैग केवल एक नाम है: यह दूसरे संस्करणों को हटाता या छिपाता नहीं।

प्रकाशित संस्करण को हटाने का कोई तरीका नहीं है। समर्थित नहीं देखें।

खोज

Unity में My Registries की सूची और npm search खोज पता /-/v1/search इस्तेमाल करते हैं। खोज ऐसे पैकेज ढूँढती है जिनके नाम या विवरण में पाठ किसी भी केस में शामिल हो, और ऐसे पैकेज जिनमें वह पाठ पूरे कीवर्ड के रूप में हो। पाठ के बिना, यह सभी पैकेज सूचीबद्ध करती है।

यह हर पैकेज के लिए एक पंक्ति लौटाती है: latest टैग वाला संस्करण, या अन्यथा सबसे नया संस्करण।
परिणाम नाम से क्रमबद्ध होते हैं। लोकप्रियता के आधार पर कोई रैंकिंग नहीं है।
size डिफ़ॉल्ट रूप से 20 है और अधिकतम 250। from ऑफ़सेट है।

bash

curl -fsS -H "Authorization: Bearer $ARKVORY_TOKEN" \
  "https://arkvory.example/npm/games/-/v1/search?text=tools&from=0&size=20"

किसी पैकेज को सीधे पढ़ने के लिए, उसका नाम माँगें। @scope/name को @scope%2fname के रूप में भेजा जा सकता है:

bash

curl -fsS -H "Authorization: Bearer $ARKVORY_TOKEN" https://arkvory.example/npm/games/com.proanima.tools

उत्तर हर संस्करण को उसके package.json की सामग्री के साथ सूचीबद्ध करता है (unity और displayName फ़ील्ड सहित जिन्हें Unity पढ़ता है), साथ में dist-tags और प्रकाशन समय। dist में tarball, shasum (SHA-1) और integrity (SHA-512) होते हैं।

नाम और सीमाएँ

मद	नियम
पैकेज नाम	छोटे अक्षर, अंक, `.`, `_`, `~` और `-`, जो किसी अक्षर या अंक से शुरू हो। अधिकतम 214 अक्षर। npm के लिए `@scope/name` की अनुमति है।
संस्करण	SemVer 2.0.0, अधिकतम 256 अक्षर
tarball में `package.json`	अधिकतम 256 KiB। सभी संस्करणों का डेटा एक ही उत्तर में आता है, इसलिए इसे छोटा रखें।
tarball	इंस्टॉलेशन के अधिकतम ऑब्जेक्ट आकार तक, `ARKVORY_MAX_OBJECT_BYTES` (डिफ़ॉल्ट रूप से लगभग 10 TiB)। जो आर्काइव 100 गुना से अधिक और 64 MiB ज़्यादा फैलता है, वह अस्वीकार कर दिया जाता है।
प्रकाशन अनुरोध का शेष भाग	अधिकतम 8 MiB JSON, अधिकतम 64 स्तर तक नेस्टेड। tarball स्ट्रीम के रूप में पढ़ा जाता है और मेमोरी में नहीं रखा जाता।
एक प्रकाशन अनुरोध	30 मिनट के भीतर पूरा होना चाहिए और 30 सेकंड से अधिक रुकना नहीं चाहिए (`ARKVORY_UPLOAD_DEADLINE_MS`, `ARKVORY_UPLOAD_IDLE_TIMEOUT_MS`)
एक साथ अपलोड	डिफ़ॉल्ट रूप से 2 प्रति सर्वर और 1 प्रति कुंजी। प्रतीक्षारत अनुरोध 20 सेकंड के बाद हार मान लेता है।
खोज पाठ	अधिकतम 256 अक्षर

npm publish एक अनुरोध है, और विफलता के बाद यह पहले बाइट से फिर शुरू होता है। कई गीगाबाइट के पैकेजों के लिए, फ़ाइल को arkvoryctl से आर्टिफ़ैक्ट या रॉ फ़ाइल के रूप में अपलोड करें। बार-बार बदलने वाली बड़ी बाइनरी एसेट Git LFS में रखना बेहतर है; कोड और स्थिर संसाधन पैकेजों में रखें।

सर्वर की सीमाएँ एनवायरनमेंट वेरिएबल में हैं।

अनुमतियाँ

व्यक्तिगत टोकन और फ़ाइल कुंजियों को रिपॉज़िटरी पर पढ़ने या लिखने का एक्सेस मिलता है। सेवा कुंजियों को सटीक कार्रवाइयाँ मिलती हैं।

कार्रवाई	सेवा कुंजी कार्रवाइयाँ	व्यक्तिगत टोकन या फ़ाइल कुंजी
इंस्टॉल: पैकेज पढ़ें और tarball डाउनलोड करें	`content.read`	पढ़ने का एक्सेस
खोज, dist-tags की सूची	`artifact.list`	पढ़ने का एक्सेस
प्रकाशित करें, dist-tags जोड़ें और हटाएँ	`upload.create`	लिखने का एक्सेस, टोकन स्कोप `read-write`

जो डेवलपर केवल पैकेज इंस्टॉल करता है, उसे read स्कोप वाला टोकन चाहिए। प्रकाशित करने वाले बिल्ड एजेंट को upload.create, content.read और artifact.list चाहिए। कोई भी प्रकाशित संस्करण नहीं हटा सकता।

रीड गेटवे और मिरर

एक रीड गेटवे इंस्टॉलेशन और खोज परोसता है, क्योंकि वे GET अनुरोध हैं। प्रकाशन को 405 मिलता है।
एक मिरर अपने स्रोत के संस्करण और टैग रखता है। इंस्टॉलेशन और खोज काम करते हैं। प्रकाशन 409 और कारण mirror_read_only के साथ अस्वीकार कर दिया जाता है। मिरर के डेटा में tarball के पते मिरर की ओर इशारा करते हैं।

Unity में मिरर इस्तेमाल करने के लिए, मिरर का पता url में और उसकी कुंजी .upmconfig.toml में रखें।

समर्थित नहीं

किसी संस्करण को हटाना (npm unpublish)। प्रोजेक्ट संस्करणों को पिन करते हैं, और हटाना उनके बिल्ड तोड़ देगा। इसके बजाय सुधरा हुआ संस्करण प्रकाशित करें और टैग बदलें।
npm deprecate, npm login, npm owner, npm access और अन्य प्रबंधन कमांड। अन्य पथों पर डेटा बदलने वाले अनुरोध 405 उत्तर देते हैं, संदेश "This registry supports publish, install and dist-tags" के साथ। npm login के बजाय कंसोल में टोकन बनाएँ और उसे .npmrc में रखें।
/-/all पर सभी पैकेजों की सूची, और npm audit।
सार्वजनिक रजिस्ट्रियों का प्रॉक्सी। Arkvory आपके अपने पैकेज संग्रहीत करता है। npmjs.com या Unity रजिस्ट्री के पैकेज वहीं से लाए जाते हैं।
खोज परिणामों की रैंकिंग।
कंसोल में पैकेजों के लिए एक अनुभाग। Tarball आर्टिफ़ैक्ट में npm लेबल वाले आर्टिफ़ैक्ट के रूप में दिखते हैं।

समस्या निवारण

त्रुटियाँ {"error": "...", "code": "...", "request_id": "..."} रूप में होती हैं। npm error छापता है। सर्वर लॉग में अनुरोध ढूँढने के लिए अपने व्यवस्थापक को request_id दें।

लक्षण	कारण	क्या करें
`401` Unity या npm में	क्लाइंट ने कुंजी नहीं भेजी, या कुंजी गलत, समाप्त या निरस्त है	Unity में जाँचें कि `.upmconfig.toml` में पता manifest के `url` के बराबर है और `alwaysAuth = true` है। npm में जाँचें कि `_authToken` पंक्ति `registry` जैसे ही होस्ट और पथ से शुरू होती है।
प्रकाशित करते समय `403`	टोकन में `read` स्कोप है, या कुंजी में `upload.create` नहीं है	लिखने के एक्सेस वाली कुंजी इस्तेमाल करें
किसी पैकेज के लिए `404`	इस रिपॉज़िटरी में ऐसा कोई पैकेज नहीं है, या कुंजी को रिपॉज़िटरी दिखती नहीं	पते में रिपॉज़िटरी और नाम जाँचें। Unity पैकेज के लिए जाँचें कि उसका नाम `scopes` के किसी स्कोप से शुरू होता है।
किसी सार्वजनिक पैकेज के लिए `404`	`registry=` सभी पैकेजों के लिए Arkvory की ओर इशारा करता है	`@scope:registry=` इस्तेमाल करें
`version_exists` के साथ `409`	संस्करण दूसरी सामग्री के साथ मौजूद है	नया संस्करण प्रकाशित करें
`state_conflict` के साथ `409`	आपने `latest` हटाने की कोशिश की	इसके बजाय `latest` को दूसरे संस्करण पर ले जाएँ
`mirror_read_only` के साथ `409`	रिपॉज़िटरी एक मिरर है	मुख्य सर्वर पर प्रकाशित करें
`integrity_mismatch` के साथ `422`	बाइट घोषित `shasum` या `integrity` से अलग हैं	दोबारा पैक करें और प्रकाशित करें। जाँचें कि कोई प्रॉक्सी बॉडी नहीं बदलता।
`400` "package.json names another package or version"	tarball के अंदर `package.json` प्रकाशित नाम या संस्करण से अलग है	पैकेज के साफ़ बिल्ड से `npm publish` चलाएँ
`400` "Only publishing a new version is supported"	कमांड ने बदला हुआ पैकेज भेजा, उदाहरण के लिए `npm deprecate`	ये कमांड समर्थित नहीं हैं
`405`	यह कमांड इस रजिस्ट्री द्वारा समर्थित नहीं है	समर्थित नहीं देखें
`507`	रिपॉज़िटरी कोटा या इंस्टॉलेशन की क्षमता पूरी हो गई है	जगह खाली करें या बड़ा कोटा माँगें
`503`	एक साथ बहुत अधिक अपलोड	प्रतीक्षा करें और दोबारा आज़माएँ
Tarball का डाउनलोड `http://` से होता है और विफल हो जाता है	प्रॉक्सी `X-Forwarded-Proto: https` नहीं भेजती	शुरू करने से पहले में बताए अनुसार प्रॉक्सी ठीक करें

Unity और npm पैकेज ​

शुरू करने से पहले ​

Unity प्रोजेक्ट में रजिस्ट्री जोड़ें ​

पैकेज प्रकाशित करें ​

पैकेज इंस्टॉल करें ​

संस्करण और dist-tags ​

खोज ​

नाम और सीमाएँ ​

अनुमतियाँ ​

रीड गेटवे और मिरर ​

समर्थित नहीं ​

समस्या निवारण ​

संबंधित पेज ​

Unity और npm पैकेज

शुरू करने से पहले

Unity प्रोजेक्ट में रजिस्ट्री जोड़ें

पैकेज प्रकाशित करें

पैकेज इंस्टॉल करें

संस्करण और dist-tags

खोज

नाम और सीमाएँ

अनुमतियाँ

रीड गेटवे और मिरर

समर्थित नहीं

समस्या निवारण

संबंधित पेज