Firebase Cloud Functions — چیست، تریگرها و چگونه توابع بنویسیم

Firebase Cloud Functions چیست و چگونه ساخته شده

Firebase Cloud Functions یک پلتفرم محاسباتی است که بر پایه Google Cloud Functions (GCF) ساخته شده و برای اکوسیستم Firebase تطبیق داده شده است. توابع کد ساده JavaScript یا TypeScript هستند که از ماژول صادر شده و برای نوع خاصی از رویداد ثبت می‌شوند. وقتی رویداد رخ می‌دهد (مثلاً کاربر ثبت‌نام می‌کند یا فایلی را آپلود می‌کند)، Firebase Cloud Functions کد مربوطه را اجرا کرده و زمینه رویداد را به آن منتقل می‌کند.

معماری Cloud Functions از اصل مسئولیت واحد پیروی می‌کند: یک تابع یک نوع رویداد را پردازش کرده و یک عملیات اتمی انجام می‌دهد. برای مثال، تابع sendWelcomeEmail هنگام ایجاد کاربر جدید در Firebase Authentication فراخوانی شده و پیام خوش‌آمدگویی ارسال می‌کند. چنین ایزوله‌ای دیباگ، تست و استفاده مجدد از توابع را در پروژه‌های مختلف ساده می‌کند.

هر تابع در یک کانتینر ایزوله با چرخه حیات موقت اجرا می‌شود. حداکثر زمان اجرا به‌طور پیش‌فرض ۶۰ ثانیه است (توابع HTTPS — ۹ دقیقه). اگر تابع در محدوده زمانی قرار نگیرد، درخواست با خطای ۵۰۰ پایان می‌یابد. برای عملیات طولانی از Cloud Tasks یا Pub/Sub با تلاش مجدد استفاده کنید. کانتینرها می‌توانند برای فراخوانی‌های بعدی مجدد استفاده شوند (keep-alive) که تأخیر در استارت‌های سرد پس از اولین فراخوانی را کاهش می‌دهد.

محیط اجرا و نسخه‌های Node.js

Firebase Cloud Functions از چند نسخه Node.js پشتیبانی می‌کند: ۱۸، ۲۰ و ۲۲ (توصیه‌شده برای پروژه‌های جدید). انتخاب نسخه در فیلد engines فایل package.json تنظیم می‌شود. Firebase CLI به‌طور خودکار محیط اجرا را بر اساس نسخه مشخص‌شده پیکربندی می‌کند. مهم: Firebase Cloud Functions اجرای کانتینرهای دلخواه Docker را پشتیبانی نمی‌کند — محیط به‌طور کامل توسط Google Cloud Functions مشخص شده است.

برای پروژه‌های جدید Node.js 22 توصیه می‌شود، زیرا شامل آخرین بهینه‌سازی‌های V8، کار بهبودیافته با ماژول‌های ESM و پشتیبانی WebSocket در سطح پلتفرم است. اگر پروژه از وابستگی‌هایی استفاده می‌کند که برای نسخه خاصی از Node ساخته شده‌اند (مثلاً ماژول‌های بومی C++)، سازگاری باید جداگانه بررسی شود — همه ماژول‌های بومی در محیط GCF کامپایل نمی‌شوند.

تفاوت بین Firebase Cloud Functions و Google Cloud Functions

Firebase Cloud Functions لایه‌ای بر روی Google Cloud Functions با SDK نصب‌شده Firebase و یکپارچه‌سازی با سرویس‌های Firebase است. توسعه‌دهنده کد را با استفاده از SDK firebase-functions می‌نویسد که تریگرهای تایپ‌شده برای همه سرویس‌های Firebase فراهم می‌کند. Google Cloud Functions پلتفرمی سطح پایین‌تر است که در آن تریگرها به‌صورت صریح از طریق Eventarc یا Pub/Sub پیکربندی می‌شوند.

تفاوت کلیدی: در Firebase Cloud Functions تریگر به‌صورت اعلامی از طریق فراخوانی functions.firestore.document('path').onWrite() ثبت می‌شود، و در Google Cloud Functions — از طریق پیکربندی Eventarc با فیلتر کردن بر اساس ویژگی‌های رویداد. Firebase Cloud Functions همچنین به‌طور خودکار با Admin SDK ارائه می‌شود که با مجوزهای حساب سرویس پروژه مقداردهی شده و دسترسی کامل به همه سرویس‌های Firebase را بدون پیکربندی اضافه می‌دهد.

انواع تریگرها: چه رویدادهایی پشتیبانی می‌شوند

Firebase Cloud Functions از ۸ دسته تریگر پشتیبانی می‌کند که هر کدام با سرویس خاصی از Firebase یا Google Cloud مطابقت دارد. تریگر شرطی است که با برآورده شدن آن تابع به‌طور خودکار فراخوانی می‌شود. توسعه‌دهنده چرخه حیات تابع را مستقیم مدیریت نمی‌کند: Firebase CLI تریگر را در Google Cloud Eventarc ثبت می‌کند و پلتفرم ابری هنگام وقوع رویداد خودش تابع را اجرا می‌کند.

محبوب‌ترین تریگرها — تریگرهای Firestore: onWrite، onCreate، onUpdate، onDelete. آن‌ها هنگام تغییر اسناد در مجموعه‌های Firestore فعال می‌شوند. تابع تصویر لحظه‌ای سند را قبل و بعد از تغییر دریافت می‌کند که امکان مقایسه مقادیر و واکنش فقط به تغییرات خاص را فراهم می‌کند. برای مثال، هنگام تغییر وضعیت سفارش از "pending" به "shipped" می‌توان اعلان push برای کاربر ارسال کرد.

تریگرهای Authentication (onCreate، onDelete) هنگام ایجاد یا حذف حساب فعال می‌شوند. از آن‌ها برای مقداردهی داده‌های کاربر استفاده می‌شود: ایجاد سند کاربر در Firestore، ارسال ایمیل خوش‌آمدگویی، ثبت در آنالیتیکس. مهم: تابع نمی‌تواند ایجاد کاربر را لغو کند — بعد از اینکه حساب قبلاً ایجاد شده اجرا می‌شود. برای اعتبارسنجی اولیه از توابع مسدودکننده (Blocking Functions) استفاده کنید که در پلتفرم Identity Platform موجود هستند.

تریگرهای HTTPS و CORS

توابع HTTPS (onRequest) امکان ایجاد نقاط پایانی کامل REST API قابل دسترس از طریق HTTP را فراهم می‌کنند. برخلاف تریگرهای رویدادی، توابع HTTPS از طریق URL با فرمت https://{region}-{project}.cloudfunctions.net/{functionName} فراخوانی می‌شوند. پیکربندی صحیح CORS مهم است اگر نقطه پایانی از مرورگر یا برنامه موبایل فراخوانی شود. Firebase SDK هدرهای CORS را به‌طور خودکار اضافه نمی‌کند — باید آن‌ها را به‌صورت دستی از طریق middleware اضافه کرد.

برای کلاینت‌های موبایل (Android، iOS) CORS لازم نیست، زیرا کلاینت‌های HTTP بومی به سیاست Cross-Origin محدود نیستند. CORS فقط برای درخواست‌های وب اهمیت دارد. اگر تابع HTTPS شما هم از برنامه و هم از وب فراخوانی می‌شود، پردازش جهانی CORS اضافه کنید: res.set('Access-Control-Allow-Origin', '*') برای development یا فهرست دامنه‌های مجاز برای production.

زمان‌بندی با Pub/Sub و Cloud Scheduler

برای اجرای دوره‌ای (وظایف cron) از ترکیب Cloud Scheduler و Pub/Sub استفاده کنید. Cloud Scheduler طبق برنامه زمانی پیام را به تاپیک Pub/Sub ارسال می‌کند و تریگر onPublish این پیام را پردازش می‌کند. Firebase CLI از سینتکس مستقیم cron پشتیبانی نمی‌کند — برنامه زمانی از طریق کنسول Google Cloud یا Terraform در قالب unix-cron تنظیم می‌شود: 0 3 * * * (هر روز در ساعت ۳:۰۰).

نمونه وظایف: ارسال منظم روزانه، پاک‌سازی داده‌های قدیمی، تولید گزارش‌ها، همگام‌سازی با APIهای خارجی. مهم: Cloud Scheduler سرویس پولی Google Cloud است (حدود $۲ در ماه برای هر job). هر فعال‌شدن به‌عنوان یک فراخوانی جداگانه تابع محاسبه شده و بر اساس قیمت‌های استاندارد Cloud Functions هزینه دریافت می‌شود.

چگونه توابع را بنویسیم و مستقر کنیم

توسعه Cloud Functions با مقداردهی پروژه از طریق Firebase CLI شروع می‌شود: firebase init functions. این دستور پوشه functions/ را با قالب index.js (یا index.ts)، فایل package.json و پیکربندی TypeScript (در صورت انتخاب) ایجاد می‌کند. پس از مقداردهی، کافی است تابع را بنویسید، آن را از ماژول صادر کرده و firebase deploy --only functions را برای استقرار اجرا کنید.

هر تابع از طریق فراخوانی متد تریگر مربوطه ثبت می‌شود. نمونه تابع HTTPS: exports.helloWorld = functions.https.onRequest((req, res) => { res.send("Hello!"); }). توابع Firebase از مدل ناهمگام استفاده می‌کنند: برای تریگرهای رویدادی (نه HTTPS) تابع باید Promise برگرداند. Firebase قبل از بستن کانتینر منتظر اتمام Promise می‌ماند. اگر Promise برگردانده نشود، تابع ممکن است قبل از اتمام عملیات ناهمگام قطع شود.

توسعه محلی از طریق Firebase Emulator Suite انجام می‌شود که شامل شبیه‌ساز Cloud Functions است. دستور firebase emulators:start سرور محلی با توابع را اجرا می‌کند که در آدرس http://localhost:5001 قابل دسترس است. شبیه‌ساز از بارگذاری مجدد داغ (hot reload) هنگام تغییر کد پشتیبانی کرده و کاملاً از محیط production ایزوله است، که امکان تست توابع بدون خطر تأثیر بر داده‌های واقعی را فراهم می‌کند.

مدیریت وابستگی‌ها و پیکربندی

وابستگی‌ها Cloud Functions از طریق package.json مدیریت می‌شوند. Firebase فقط وابستگی‌های production را نصب می‌کند (dependencies، نه devDependencies). اندازه بسته توابع بر زمان استارت سرد تأثیر می‌گذارد: توصیه می‌شود تعداد وابستگی‌ها را به حداقل برسانید. برای کار با Firebase Admin SDK وابستگی firebase-admin از قبل نصب شده است — نیازی به افزودن دستی نیست.

داده‌های محرمانه (کلیدهای API، توکن‌ها) نباید در کد تابع ذخیره شوند. از functions.config() برای ذخیره پیکربندی استفاده کنید: firebase functions:config:set stripe.key="sk_...". مقادیر رمزنگاری شده و در runtime از طریق functions.config().stripe.key در دسترس هستند. برای پیکربندی‌های سریالی‌شده حجیم از Secret Manager گوگل کلود استفاده کنید.

مدیریت خطا و ثبت لاگ

ثبت لاگ در Cloud Functions از طریق console.log، console.warn و console.error انجام می‌شود. همه لاگ‌ها به‌طور خودکار در Google Cloud Logging جمع‌آوری شده و در کنسول Firebase (بخش Functions > Logs) در دسترس هستند. برای ثبت لاگ ساختاریافته از کتابخانه winston یا pino استفاده کنید که قالب‌بندی JSON و سطوح لاگ را پشتیبانی می‌کنند.

مدیریت خطا برای قابلیت اطمینان حیاتی است: استثنای مدیریت‌نشده در Promise تابع را با خطا پایان می‌دهد، پس از آن Firebase به‌طور خودکار فراخوانی (retry) را با تأخیر نمایی تکرار می‌کند. تعداد تلاش‌ها قابل پیکربندی است: از ۰ تا بی‌نهایت. برای تریگرهای رویدادی توصیه می‌شود retry را فعال کنید تا پردازش هر رویداد حتی هنگام خرابی موقت سرویس‌های خارجی تضمین شود.

استارت سرد و مقیاس‌پذیری

استارت سرد (cold start) تأخیر در اولین فراخوانی تابع پس از دوره عدم فعالیت است، زمانی که کانتینر با کد بارگذاری و دوباره مقداردهی می‌شود. طبق Firebase documentation (2026)، استارت سرد بسته به اندازه بسته، تعداد وابستگی‌ها و منطقه از ۲۰۰ میلی‌ثانیه تا ۲ ثانیه طول می‌کشد. برای رابط کاربری، تأخیر بیش از ۱ ثانیه محسوس است و ممکن است بر user experience تأثیر بگذارد.

راه‌های به حداقل رساندن استارت سرد: به حداقل رساندن وابستگی‌ها، استفاده از TypeScript با کامپایل به CommonJS، کاهش اندازه بسته توابع، تنظیم حداقل تعداد نمونه‌های فعال. Firebase Cloud Functions v2 (2nd gen) امکان تنظیم minInstances — حداقل تعداد کانتینرهای گرم را فراهم می‌کند که همیشه آماده پردازش درخواست‌ها هستند. برای گرم نگه داشتن کانتینرها هزینه‌ای برای زمان بیکاری دریافت می‌شود.

مقیاس‌پذیری Cloud Functions به‌طور خودکار انجام می‌شود: با افزایش تعداد درخواست‌ها، Firebase کانتینرهای جدید ایجاد می‌کند. به‌طور پیش‌فرض حداکثر تعداد نمونه‌های موازی ۳۰۰۰ است (سهمیه پروژه Google Cloud). هر نمونه یک درخواست را همزمان پردازش می‌کند. اگر تابع سریع باشد (کمتر از ۱۰۰ میلی‌ثانیه)، یک نمونه می‌تواند تا ۱۰ درخواست در ثانیه پردازش کند که توان عملیاتی اوج تا ۳۰ ۰۰۰ درخواست در ثانیه برای هر پروژه می‌دهد.

پیکربندی minInstances و maxInstances

minInstances پارامتری است که تعداد مشخصی کانتینر را رزرو کرده و آن‌ها را گرم نگه می‌دارد. برای توابع HTTPS حیاتی توصیه می‌شود که تأخیر استارت سرد در آن‌ها غیرقابل قبول است. برای مثال، برای نقطه پایانی احراز هویت minInstances: 1 تنظیم کنید. maxInstances محدودیتی بر حداکثر تعداد نمونه‌های موازی است که برای جلوگیری از رشد کنترل‌نشده هزینه‌ها هنگام افزایش ناگهانی ترافیک مفید است.

پیکربندی در کد انجام می‌شود: functions.runWith({ minInstances: 1, maxInstances: 10 }). مهم: minInstances هزینه را افزایش می‌دهد، زیرا کانتینر به‌طور مداوم کار می‌کند. برای پروژه‌های آزمایشی باید minInstances را غیرفعال کرد. برای production توصیه می‌شود minInstances برای همه توابع HTTPS عمومی و ۰ برای تریگرهای رویدادی که در آن‌ها تأخیر ۱ ثانیه حیاتی نیست.

مناطق استقرار

منطقه استقرار بر تأخیر تا کاربران نهایی و هزینه ترافیک خروجی تأثیر می‌گذارد. Firebase Cloud Functions در بیش از ۳۰ منطقه Google Cloud در دسترس است. برای برنامه‌های موبایل منطقه‌ای را انتخاب کنید که به مخاطب هدف شما نزدیک‌تر است: us-central1 برای آمریکا، europe-west1 برای اروپا، asia-east2 برای آسیا. منطقه پس از استقرار بدون استقرار مجدد تابع قابل تغییر نیست.

تغییر منطقه از طریق پارامتر region در کد انجام می‌شود: functions.region('europe-west1'). همه توابع در یک فایل می‌توانند مناطق متفاوتی داشته باشند. برای پروژه‌های جهانی توصیه می‌شود توابع را در چند منطقه مستقر کرده و از Cloud Load Balancing برای توزیع ترافیک استفاده کنید، هرچند برای اکثر برنامه‌های موبایل یک منطقه با انتخاب صحیح کافی است.

نمونه‌های کد برای Firebase Cloud Functions

نمونه‌های عملی Cloud Functions را در TypeScript بررسی می‌کنیم. کد از Firebase Functions SDK v2 (2nd gen) با سینتکس ماژولی ES استفاده می‌کند. نمونه‌ها شامل پردازش رویداد ایجاد کاربر، تولید تصویر بندانگشتی هنگام آپلود عکس و نقطه پایانی HTTPS ساده برای REST API هستند. همه توابع ناهمگام با بازگشت Promise برای تکمیل صحیح کانتینر هستند.

قبل از اجرا مطمئن شوید که Firebase CLI به نسخه ۱۳+ به‌روزرسانی شده است: npm install -g firebase-tools. توابع v2 به طرح تعرفه Blaze نیاز دارند. مقداردهی: firebase init functions با انتخاب TypeScript.

پردازش ثبت‌نام کاربر

اولین نمونه — ایجاد سند در Firestore هنگام ثبت‌نام کاربر جدید. تابع با رویداد auth.user().onCreate فعال شده و پروفایل پایه را در مجموعه users/{uid} می‌نویسد. این امکان تضمین اینکه برای هر کاربر ثبت‌نام‌شده سندی با فیلدهای لازم وجود داشته باشد را فراهم می‌کند.

import * as functions from "firebase-functions"
import * as admin from "firebase-admin"

admin.initializeApp()

export const createUserProfile = functions.auth
    .user()
    .onCreate(async (user) => {
        const profile = {
            email: user.email,
            displayName: user.displayName ?? "User",
            createdAt: admin.firestore.Timestamp.now(),
            role: "free",
            avatarUrl: null,
        }

        await admin.firestore()
            .collection("users")
            .doc(user.uid)
            .set(profile)

        console.log(`Profile created for ${user.uid}`)
    })

تابع createUserProfile ناهمگام است — Promise را برمی‌گرداند که Firebase قبل از تکمیل منتظر آن می‌ماند. اگر نوشتن در Firestore با خطا پایان یابد (مثلاً به دلیل نبود مجوز)، تابع به‌طور خودکار تکرار می‌شود (اگر retry فعال باشد). فیلد role با مقدار "free" امکان پیاده‌سازی محدودیت‌های طرح رایگان را مستقیماً در Security Rules فایربیس فراهم می‌کند، با مقایسه resource.data.role با سطح دسترسی موردنیاز.

تولید تصویر بندانگشتی هنگام آپلود عکس

دومین نمونه — تریگر Storage برای تولید خودکار تصویر کوچک (thumbnail) پس از آپلود عکس. تابع یک نسخه کاهش‌یافته به ابعاد ۲۰۰×۲۰۰ پیکسل ایجاد کرده و آن را در مسیر فایل اصلی با پیشوند thumb_ ذخیره می‌کند. برای پردازش تصاویر از کتابخانه sharp استفاده می‌شود که همه فرمت‌های رایج را پشتیبانی کرده و در محیط Node.js بدون وابستگی‌های سیستمی کار می‌کند.

import * as path from "path"
import * as os from "os"
import * as sharp from "sharp"

export const generateThumbnail = functions.storage
    .object()
    .onFinalize(async (object) => {
        if (!object.contentType?.startsWith("image/")) return

        const filePath = object.name!
        const thumbPath = filePath.replace(
            /(\.\w+)$/, "_thumb$1"
        )

        const bucket = admin.storage().bucket()
        const tempDir = os.tmpdir()
        const tempFile = path.join(tempDir, path.basename(filePath))

        await bucket.file(filePath).download({ destination: tempFile })
        await sharp(tempFile)
            .resize(200, 200, { fit: "cover" })
            .toFile(tempFile.replace(/(\.\w+)$/, "_thumb$1"))

        await bucket.upload(tempFile.replace(
            /(\.\w+)$/, "_thumb$1"
        ), { destination: thumbPath })
    })

تابع generateThumbnail Content-Type شیء را بررسی کرده و موارد غیرتصویر را نادیده می‌گیرد که منابع را صرفه‌جویی می‌کند. برای کار با sharp وابستگی باید به package.json اضافه شود. تصویر بندانگشتی با پارامتر fit: "cover" ایجاد می‌شود که تصویر را در مرکز به مربع ۲۰۰×۲۰۰ پیکسل برش می‌دهد. پس از ایجاد، تصویر بندانگشتی با نام تغییر‌یافته به همان باکت آپلود می‌شود.

نقطه پایانی HTTPS برای API عمومی

سومین نمونه — تابع HTTPS است که نقطه پایانی REST API را برای بررسی وضعیت سرور پیاده‌سازی می‌کند. تابع درخواست GET را دریافت کرده و JSON با اطلاعات وضعیت سرویس‌های Firebase متصل به پروژه برمی‌گرداند. نقطه پایانی برای مانیتورینگ و سیستم‌های خارجی مفید است که باید قبل از ارسال داده دسترس‌پذیری بک‌اند را بررسی کنند.

import * as express from "express"

const app = express.Router()

app.get("/status", async (req, res) => {
    try {
        const db = admin.firestore()
        await db.collection("_health").doc("check").get()
        res.json({ status: "ok", timestamp: Date.now() })
    } catch (error) {
        res.status(503).json({ status: "error", message: error })
    }
})

export const api = functions.https.onRequest(app)

تابع api از express Router برای مسیریابی استفاده می‌کند که هنگام ایجاد چند نقطه پایانی در یک تابع راحت است. بررسی سلامت (health check) در Firestore در مجموعه _health نوشته می‌شود که امکان بررسی هم‌زمان دسترس‌پذیری Firestore را فراهم می‌کند. برای production توصیه می‌شود احراز هویت درخواست از طریق کلید API یا توکن Firebase Auth اضافه شود تا از سوءاستفاده از نقطه پایانی عمومی جلوگیری شود.

سناریوهای معمول استفاده در برنامه‌های موبایل

Cloud Functions بیشتر برای وظایفی استفاده می‌شود که انجام آن‌ها در کلاینت ممکن یا مطلوب نیست: ارسال اعلان‌های push، تولید پیش‌نمایش تصاویر آپلودشده، یکپارچه‌سازی با سیستم‌های پرداخت خارجی، مدیریت محتوا، همگام‌سازی داده‌ها بین Firebase و سرویس‌های شخص ثالث. مدل بدون سرور این وظایف را اقتصادی می‌کند: هزینه فقط برای زمان واقعی اجرای کد دریافت می‌شود.

یکپارچه‌سازی با سیستم‌های پرداخت سناریوی معمول برای برنامه‌های دارای خرید درون‌برنامه‌ای (in-app) است. Cloud Functions وب‌هوک را از ارائه‌دهنده پرداخت (Stripe، PayPal) دریافت کرده، امضای درخواست را بررسی می‌کند، وضعیت اشتراک را در Firestore به‌روزرسانی کرده و تأییدیه برای کاربر ارسال می‌کند. همه کد روی سرور اجرا می‌شود بدون خطر جعل داده در کلاینت. طبق Stripe documentation (2026)، پردازش وب‌هوک کمتر از ۵۰۰ میلی‌ثانیه طول می‌کشد.

مدیریت هوشمند محتوا از تریگر Storage برای بررسی خودکار تصاویر آپلودشده از طریق Google Cloud Vision API استفاده می‌کند. تابع تصویر را برای تشخیص محتوای ناامن (خشونت، محتوای بزرگسالان) به Vision API ارسال کرده و اگر آستانه عبور شود، فایل را حذف کرده و به مدیر اطلاع می‌دهد. این سناریو برای برنامه‌های UGC با گالری‌های کاربران حیاتی است.

تجمیع داده‌ها — Cloud Functions به‌عنوان جایگزین شمارنده‌های Firebase Realtime Database. به‌جای خواندن و نوشتن شمارنده در کلاینت (که منجر به race conditions می‌شود)، از تریگر Firestore onWrite برای به‌روزرسانی اتمی فیلدهای تجمیع‌شده استفاده کنید. برای مثال، تابع تعداد لایک‌های پست را در هر افزودن یا حذف سند در زیرمجموعه /posts/{postId}/likes/{userId} محاسبه کرده و فیلد likesCount را در سند والد به‌روزرسانی می‌کند.