בניית אפליקציה ב-Node.js

ציון גרסאות של Node.js

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

שימוש ב-package.json

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

"engines": {
  "node": "24.x.x"
}

שימוש ב-GOOGLE_NODEJS_VERSION

אפשר גם לציין את גרסת Node.js באמצעות משתנה הסביבה GOOGLE_NODEJS_VERSION. אם שתי התצורות מוגדרות, הערך של GOOGLE_NODEJS_VERSION מקבל קדימות על פני הנכס engines.node. אם לא מציינים גרסה, ה-buildpack משתמש בגרסת ה-LTS העדכנית ביותר של Node.js.

כדי להגדיר שה-buildpack ישתמש ב-Node.js 24 כשפורסים את האפליקציה, מריצים את הפקודה הבאה:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=24.x.x

אתם גם יכולים להשתמש במתאר של פרויקט project.toml כדי לקודד את משתנה הסביבה לצד קובצי הפרויקט. במאמר פיתוח אפליקציות באמצעות משתני סביבה מפורטות ההוראות.

טיפים

  • השדה engines.node יכול להכיל מגבלת semver. הספרייה הספציפית שבה אנחנו משתמשים ל-buildpacks של Node.js היא Masterminds/semver
  • אין להשתמש בסימן 'גדול מ' (>) בשדה engines.node.
  • כשפורסים את האפליקציה בסביבה הסטנדרטית של App Engine, המאפיין engines.node חייב להיות תואם לזמן הריצה שמצוין ב-app.yaml. מידע נוסף על אפשרות ההגדרה engines.node בקובץ package.json זמין בתיעוד הרשמי של NPM בנושא engines topic.
  • כשפורסים פונקציה ב-Cloud Run Functions, הנכס engines.node צריך להיות תואם לסביבת זמן הריצה שבה אתם פורסים את הפונקציה.

התקנת יחסי תלות

‫NPM הוא מנהל החבילות שמוגדר כברירת מחדל בכל הגרסאות של Node.js. בקטע הבא מפורטים יחסי התלות התואמים לאפליקציות Node.js.

מנהל חבילות NPM

  • ‫NPM הוא מנהל החבילות שמוגדר כברירת מחדל.
  • כשאפשר, כדאי להשתמש ב-package-lock.json כדי לשפר את ביצועי המטמון.
  • כברירת מחדל, מותקנות רק חבילות שמוגדרות ביחסי התלות של סביבת הייצור.
  • כדי לציין את גרסת ה-NPM, משתמשים בשדה engines.npm בקובץ package.json. מידע נוסף זמין במאמרי העזרה בנושא NPM.

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

  • אם כוללים את הקובץ yarn.lock בפרויקט, buildpack משתמש ב-Yarn.
  • מציינים את גרסת ה-Yarn בשדה engines.yarn בקובץ package.json.
  • אם הפרויקט שלכם כולל תיקייה .yarn/cache, Buildpack תומך במצב Yarn2 PnP.

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

  • ה-buildpack משתמש ב-Pnpm אם כוללים את הקובץ pnpm-lock.yaml בפרויקט.
  • מציינים את גרסת ה-Pnpm בשדה engines.pnpm בקובץ package.json.
  • תוכלו לראות דוגמה שעובדת באפליקציה sample-node-pnpm.

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

ה-buildpack של Node.js תומך במנהל החבילות Bun‏, google.nodejs.bun buildpack, להתקנת יחסי תלות. כדי להשתמש במנהל החבילות של Bun:

  • יוצרים קובץ bun.lock או bun.lockb בספריית הבסיס לזיהוי אוטומטי.
  • אפשר גם להגדיר במפורש את משתנה הסביבה GOOGLE_PACKAGE_MANAGER לערך bun. בשיטה הזו, לא צריך ליצור ולתחזק קובצי נעילה.
  • הפרויקט צריך לכלול קובץ package.json. תוכלו לציין את גרסת ה-Bun שבה צריך להשתמש בשדה engines.bun או packageManager בקובץ package.json. אם לא מציינים גרסה, כברירת מחדל ב-buildpack נעשה שימוש בגרסה היציבה האחרונה.

מידע נוסף על פריסה ב-Cloud Run זמין במאמר ציון תלות ב-Node.js.

למידע נוסף על מנהל החבילות של Bun, אפשר לעיין במסמכי התיעוד של Bun.

קדימות של מנהל חבילות

ה-buildpack של Node.js קובע את מנהל החבילות על סמך ההגדרה לפי סדר העדיפויות הבא:

  1. ה-buildpack בודק קודם אם יש קובצי נעילה בסדר הבא:

    • Yarn – yarn.lock
    • pnpm - pnpm-lock.yaml
    • לחמנייה – bun.lock או bun.lockb
    • NPM - package-lock.json

  2. אם אתם לא משתמשים בקובצי נעילה, ה-buildpack של Node.js משתמש בערך שאתם מקצים למשתנה הסביבה GOOGLE_PACKAGE_MANAGER.

  3. אם לא משתמשים בקובץ נעילה או לא מגדירים את משתנה הסביבה, כברירת מחדל ה-buildpack משתמש ב-NPM.

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

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

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

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

@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 בגרסה 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 בנושא מודולים פרטיים.

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

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

אפשר להשתמש רק בשיטה אחת. חשוב לשים לב שמשתנה הסביבה GOOGLE_NODE_RUN_SCRIPTS מקבל קדימות ומבטל כל הגדרה שצוינה ל-gcp-build ב-package.json.

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

שימוש ב-GOOGLE_NODE_RUN_SCRIPTS

תוכלו להעביר את משתנה הסביבה GOOGLE_NODE_RUN_SCRIPTS ל-build כדי לקבוע אילו סקריפטים ירוצו. אפשר לציין סקריפט אחד או יותר, או להעביר משתנה סביבה ריק כדי למנוע את ההפעלה של התנהגות ברירת מחדל, למשל GOOGLE_NODE_RUN_SCRIPTS=. מידע נוסף זמין במאמר משתני סביבה.

שימוש ב-package.json

אם מוסיפים את gcp-build בקובץ package.json, תגרום לכך שרק הפקודה npm run gcp-build תופעל – כלומר, ביטול של התנהגות ברירת המחדל. אפשר לציין פקודה אחת או יותר, או לציין מחרוזת ריקה במקום זאת כדי שאף פקודה לא תרוץ, למשל "gcp-build":"".

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

נקודת כניסה לאפליקציה

ה-buildpack של Node.js מריץ את הפקודה שצוינה בשדה scripts.start בקובץ package.json. אם לא מגדירים את השדה scripts.start, ה-buildpack מריץ את הפקודה npm start.

אנחנו ממליצים להשתמש ב-Procfile כי זה יוציא את מנהל החבילות מהנתיב ויאפשר ביצוע ישיר.

משתני סביבה

אתם יכולים להגדיר משתני סביבה כדי להגדיר גרסאות build של קובץ אימג' של קונטיינר.

כדי להתאים אישית את הקונטיינר, ה-buildpack של Node.js תומך במשתני הסביבה הבאים.

NODE_ENV

מציין את סביבת הפיתוח במהלך ה-build. מוגדרת ל-npm install.

לדוגמה: NODE_ENV=development מתקין את dependencies ואת devDependencies שצוינו ב-package.json.

NPM_CONFIG_<key>

מציינים את פרמטר ההגדרה, לדוגמה, NPM_CONFIG_FLAG=value passes -flag=value לפקודות npm.

מידע על משתנה הסביבה הזה זמין בקטע Config במסמכי התיעוד של NPM.

GOOGLE_PACKAGE_MANAGER

אפשר להגדיר את משתנה הסביבה הזה לשימוש במנהל חבילות נתמך. לדוגמה, GOOGLE_PACKAGE_MANAGER=bun מאלץ את השימוש ב-Bun גם אם לא יוצרים קובץ נעילה. המשתנה הזה תומך בערכים כמו npm,‏ yarn,‏ pnpm או bun.

GOOGLE_NODE_RUN_SCRIPTS

מציין רשימה ממוינת של סקריפטים של NPM מ-package.json שיש להריץ אחרי התקנת התלויות. הרשימה צריכה להיות מופרדת בפסיקים ופועלת לפי הסדר שבו רשומים הסקריפטים.

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

לדוגמה:

  • המשתנה GOOGLE_NODE_RUN_SCRIPTS=lint,build מריץ את npm run lint ולאחר מכן את npm run build.
  • המשתנה GOOGLE_NODE_RUN_SCRIPTS= לא מריץ סקריפטים.