ציון יחסי תלות ב-Node.js

מותר לפונקציה להשתמש במודולים חיצוניים של Node.js וגם בנתונים מקומיים. התלויות ב-Node.js מנוהלות באמצעות npm ומופיעות בקובץ מטא-נתונים בשם package.json. אפשר להשתמש ב-npm,‏ yarn,‏ pnpm או ב-Bun כדי להתקין תלות ב-Node.js.

‫Node.js Functions Framework הוא יחס תלות נדרש לכל הפונקציות. למרות שפונקציות Cloud Run מתקינות אותו בשמכם כשיוצרים את הפונקציה, מומלץ לכלול אותו כתלות מפורשת כדי שההגדרה תהיה ברורה.

אם הפונקציה שלכם מסתמכת על יחסי תלות פרטיים, מומלץ לשכפל את functions-framework למאגר הפרטי שלכם. כדי להימנע מהתקנת החבילה מהאינטרנט הציבורי, צריך לכלול את functions-framework המשוכפל כהסתמכות בפונקציה.

כדי לציין תלות בפונקציה, מוסיפים אותה לקובץ package.json.

אם חבילת ה-buildpack של Node.js מזהה קובץ נעילה, כמו package-lock.json,‏ yarn.lock,‏ pnpm-lock.yaml,‏ bun.lock או bun.lockb בפרויקט, היא נותנת עדיפות לקובץ הנעילה הזה כשמתקינים תלות באמצעות npm ci,‏ yarn install,‏ pnpm install או bun install.

בדוגמה הבאה מוצגת תלות בקובץ package.json:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

מערכת Cloud Run מייבאת את התלות בפונקציה:

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

שימוש ב-npm להתקנת מודולים של Node.js באופן מקומי

הדרך הקלה ביותר להתקין מודול Node.js באופן מקומי היא להשתמש בפקודה npm install בתיקייה שמכילה את הפונקציה של Cloud Run. לדוגמה, הפקודה הבאה מוסיפה את המודול uuid:

npm install uuid

הפעולה הזו משלבת שני שלבים:

  1. הגרסה האחרונה של המודול מסומנת כתלות בקובץ package.json. חשוב מאוד: פונקציות Cloud Run מתקינות רק מודולים שמוצהרים בקובץ package.json.
  2. המודול יורד לתיקייה node_modules. כך תוכלו להשתמש במודול כשאתם מפתחים באופן מקומי.

אם npm לא מותקן במחשב, מתקינים את npm.

הגדרת יחסי תלות בפריסה

אפשר להתקין יחסי תלות של סביבת ייצור עבור NPM,‏ Yarn או Pnpm:

מנהל חבילות NPM

כשפורסים את הפונקציה, Cloud Run functions מתקין את יחסי התלות שמוצהרים בקובץ package.json באמצעות הפקודה npm install:

npm install --production

מנהל החבילות Yarn

בסביבת זמן הריצה Node.js 8 ומעלה, אם קיים קובץ yarn.lock, פונקציות Cloud Run משתמשות במקום זאת בפקודה yarn install:

yarn install --production

מערכת ניהול החבילות Pnpm

בסביבת זמן הריצה Node.js 8 ומעלה, אם קיים קובץ pnpm-lock.yaml, פונקציות Cloud Run משתמשות במקום זאת בפקודה pnpm install:

pnpm install

מנהל החבילות של Bun

ה-buildpack של Node.js תומך במנהל החבילות Bun. עם מנהל החבילות של Bun, אתם יכולים להתקין יחסי תלות תוך שמירה על מבנה הפרויקט וגרסת זמן הריצה הקיימים של Node.js. אפשר לבחור כל אחד מהמנגנונים הבאים כדי להתקין תלויות באמצעות Bun:

  • זיהוי אוטומטי: ה-buildpack של Node.js מזהה את מנהל החבילות של Bun כשכוללים קובץ bun.lock או bun.lockb בפרויקט. כדי להגדיר זיהוי אוטומטי באמצעות Bun, פועלים לפי השלבים הבאים:

    1. יוצרים את קובץ הנעילה:

      bun install --lockfile-only

    2. מריצים את הפקודה הבאה כדי לפרוס ל-Cloud Run:

       gcloud run deploy --source . --base-image=nodejs24

  • הסכמה מפורשת: מגדירים את משתנה הסביבה GOOGLE_PACKAGE_MANAGER לערך bun. בשיטה הזו, לא צריך ליצור ולתחזק קובצי נעילה. מריצים את הפקודה הבאה כדי לפרוס ל-Cloud Run:

    gcloud run deploy --source . --base-image=nodejs24 --set-build-env-vars GOOGLE_PACKAGE_MANAGER=bun

ה-buildpack משתמש ב-Bun כדי להתקין יחסי תלות, אבל סביבת זמן הריצה של Node.js עדיין מפעילה את האפליקציה. הפרויקט צריך לכלול קובץ package.json. פרטים נוספים על דרישות ההגדרה זמינים במאמר יצירת אפליקציית Node.js בתיעוד של Buildpacks.

ביצוע שלבי build בהתאמה אישית במהלך הפריסה

אחרי הפריסה, אפשר לבצע שלב בנייה מותאם אישית במהלך תהליך build של הפונקציה על ידי הוספת סקריפט gcp-build בקובץ package.json.

כשמריצים את הסקריפט הזה, התלויות בשדות dependencies ו-devDependencies בקובץ package.json זמינות. אחרי שמריצים את שלב הבנייה המותאם אישית, פונקציות Cloud Run מסירות את התיקייה node_modules ויוצרות אותה מחדש. הפונקציות מתקינות רק את יחסי התלות של הסביבה הפרודקטיבית שהוגדרו בשדה dependencies בקובץ package.json.

אם אין סקריפט gcp-build ב-package.json, פונקציות Cloud Run מתקינות רק יחסי תלות של סביבת הייצור.

שימוש בחבילות מערכת

סביבת זמן הריצה של Node.js כוללת גם מספר חבילות מערכת בסביבת ההפעלה.

הכללת מודולים מקומיים של Node.js

אפשר גם לכלול מודולים מקומיים של Node.js כחלק מהפונקציה. כדי לעשות את זה, צריך להצהיר על המודול ב-package.json באמצעות הקידומת file:. בדוגמה הבאה, mymodule הוא שם המודול ו-mymoduledir הוא הספרייה שמכילה את המודול:

  {
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

הקוד של המודול המקומי הזה צריך להיות מאוחסן במקום אחר ולא בתיקייה node_modules שבספריית הבסיס של הפונקציה.

טעינת מודולים של Node.js

משתמשים בפונקציה Node.js require() כדי לטעון כל מודול Node.js שהתקנתם. אפשר גם להשתמש בפונקציה require() כדי לייבא קבצים מקומיים שאתם פורסים לצד הפונקציה.

שימוש במודולים פרטיים

כדי להשתמש במודול npm פרטי, צריך לספק הגדרות לאימות עם המאגר בקובץ .npmrc בספרייה של הפונקציה. אם אתם משתמשים ב-Yarn בגרסה 2 ומעלה כמנהל החבילות, שם הקובץ הוא .yarnrc.yml.

מודולים פרטיים מ-Artifact Registry

מאגר חבילות Node.js ב-Artifact Registry יכול לארח מודולים פרטיים של הפונקציה. כשפורסים פונקציה של Cloud Run Functions, תהליך ה-build יוצר באופן אוטומטי פרטי כניסה ל-Artifact Registry עבור חשבון השירות של Cloud Build. צריך לכלול רק את המאגר של Artifact Registry ב-.npmrc בלי ליצור פרטי כניסה נוספים. לדוגמה:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

הגישה הזו רלוונטית גם למנהל החבילות Yarn v1. אם אתם משתמשים ב-Yarn בגרסה 2 ומעלה, אתם צריכים רק לציין את מאגר Artifact Registry ב-.yarnrc.yml בלי פרטי כניסה נוספים. לדוגמה:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

מודולים פרטיים ממאגרים אחרים

במסמכי התיעוד של npm מוסבר איך ליצור טוקנים מותאמים אישית לקריאה בלבד. אנחנו לא ממליצים להשתמש בקובץ .npmrc שנוצר בספריית הבית כי הוא מכיל טוקן לקריאה ולכתיבה. הרשאות כתיבה לא נדרשות במהלך הפריסה, והן עלולות להוות סיכון אבטחה.

אל תכללו את הקובץ .npmrc אם אתם לא משתמשים במאגרי קוד פרטיים, כי הוא עלול להאריך את זמן הפריסה של הפונקציות.

פורמט קובץ

אם אתם משתמשים בקובץ .npmrc כדי להגדיר אסימון אימות בהתאמה אישית, הוא צריך לכלול את השורה הבאה.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

מחליפים את:

  • ‫REGISTRY_DOMAIN: שם הדומיין של מאגר npm הפרטי. אם המאגר מתארח ב-npmjs.org, צריך להגדיר את השדה הזה לערך registry.npmjs.org.

  • ‫AUTH_TOKEN: אסימון ההרשאה של מאגר npm. זה יכול להיות ערך הטקסט המילולי של הטוקן או מחרוזת הטקסט ${NPM_TOKEN}, שבה npm מוחלף בערך הטוקן בפועל מהסביבה.

    אפשר להגדיר את משתנה הסביבה $NPM_TOKEN באמצעות הארגומנט --set-build-env-vars בפקודה gcloud functions deploy. לפרטים נוספים על טוקן האימות של NPM, אפשר לעיין במדריך NPM בנושא מודולים פרטיים.

איך בונים פונקציה עם יחסי תלות שהועתקו

תלויות שהועתקו הן תלויות שקוד המקור שלהן נכלל ישירות בחבילת קוד המקור שלכם ונבנה מחדש לצד הקוד שלכם. כדי ליצור עותקים של יחסי תלות ב-Node.js ולדלג על ההתקנה שלהם במהלך הפריסה, משתמשים במשתנה הסביבה GOOGLE_VENDOR_NPM_DEPENDENCIES של סביבת build.

דרישות מוקדמות להעתקת יחסי תלות

  1. מוודאים שיש לכם פונקציה פעילה עם כל התלויות שרוצים להעתיק בקובץ package.json.

  2. כדי להתקין את יחסי התלות האלה באופן מקומי, מריצים את הפקודה:

        npm install

  3. מסירים את node_modules מהקובץ .gcloudignore בספריית העבודה.

  4. פורסים את הפונקציה ומוודאים שגרסת Node.js המקומית זהה לגרסה שצוינה במהלך הפריסה.

  5. מפעילים את הפונקציה ואת יחסי התלות שהועתקו באמצעות הפקודה הבאה:

      gcloud run deploy SERVICE \
    --source . \
    --function FUNCTION_ENTRY_POINT \
    --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true

    מחליפים את:

    • ‫SERVICE: השם של פונקציית Cloud Run שפורסתם
    • ‫FUNCTION_ENTRY_POINT: עם נקודת הכניסה לפונקציה בקוד המקור.

אם מציינים מנוע npm בקובץ package.json, הגרסה שצוינה של npm מורדת בזמן ה-build. כדי למנוע את ההתנהגות הזו, מסירים את השורה מהקובץ package.json.