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

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

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

שימוש ב-package.json

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

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

שימוש ב-GOOGLE_NODEJS_VERSION

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

כדי להגדיר שה-buildpack ישתמש ב-Node.js 16 בעת פריסת האפליקציה:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=16.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

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

שימוש ב-Yarn

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

שימוש ב-Pnpm

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

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

כדי להשתמש במודול 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 כי זה יוציא את npm או yarn מהנתיב.

משתני סביבה

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

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

NPM_CONFIG_<key>

לצפייה במסמכי התיעוד

לדוגמה: הפונקציה NPM_CONFIG_FLAG=value מעבירה את -flag=value לפקודות npm.

NODE_ENV

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

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

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= לא מריץ סקריפטים.