Firebase Cloud Functions — nó là gì, trình kích hoạt và cách viết hàm

Firebase Cloud Functions là gì và chúng hoạt động như thế nào

Firebase Cloud Functions là một nền tảng tính toán được xây dựng trên Google Cloud Functions (GCF), thích ứng với hệ sinh thái Firebase. Các hàm là mã JavaScript hoặc TypeScript thông thường được xuất từ một mô-đun và đăng ký cho một loại sự kiện cụ thể. Khi một sự kiện xảy ra (ví dụ: người dùng đăng ký hoặc tải lên tệp), Firebase Cloud Functions thực thi mã tương ứng, chuyển cho nó ngữ cảnh sự kiện.

Kiến trúc của Cloud Functions tuân theo nguyên tắc trách nhiệm duy nhất: một hàm xử lý một loại sự kiện và thực hiện một thao tác nguyên tử. Ví dụ: hàm sendWelcomeEmail được kích hoạt khi người dùng mới được tạo trong Firebase Authentication và gửi email chào mừng. Sự cô lập như vậy giúp đơn giản hóa việc gỡ lỗi, kiểm tra và tái sử dụng các hàm trong các dự án khác nhau.

Mỗi hàm chạy trong một vùng chứa biệt lập với vòng đời tạm thời. Thời gian thực thi tối đa mặc định là 60 giây (hàm HTTPS — 9 phút). Nếu một hàm không hoàn thành trong thời gian chờ, yêu cầu sẽ thất bại với lỗi 500. Đối với các hoạt động kéo dài, hãy sử dụng Cloud Tasks hoặc Pub/Sub với tính năng thử lại. Các vùng chứa có thể được tái sử dụng cho các lần gọi tiếp theo (keep-alive), giúp giảm độ trễ khi khởi động nguội sau lần gọi đầu tiên.

Môi trường thực thi và các phiên bản Node.js

Firebase Cloud Functions hỗ trợ nhiều phiên bản Node.js: 18, 20 và 22 (khuyến nghị cho dự án mới). Phiên bản được chỉ định trong trường engines của tệp package.json. Firebase CLI tự động cấu hình môi trường thực thi dựa trên phiên bản đã chỉ định. Quan trọng: Firebase Cloud Functions không hỗ trợ chạy các vùng chứa Docker tùy ý — môi trường được cố định chặt chẽ bởi Google Cloud Functions.

Đối với các dự án mới, Node.js 22 được khuyến nghị vì nó bao gồm các tối ưu hóa V8 mới nhất, hỗ trợ mô-đun ESM được cải thiện và hỗ trợ WebSocket ở cấp nền tảng. Nếu một dự án sử dụng các phụ thuộc được xây dựng cho một phiên bản Node cụ thể (ví dụ: mô-đun C++ gốc), khả năng tương thích phải được kiểm tra riêng lẻ — không phải tất cả các mô-đun gốc đều biên dịch được trong môi trường GCF.

Sự khác biệt giữa Firebase Cloud Functions và Google Cloud Functions

Firebase Cloud Functions là một lớp bọc xung quanh Google Cloud Functions với SDK Firebase được cài đặt sẵn và tích hợp với các dịch vụ Firebase. Nhà phát triển viết mã bằng SDK firebase-functions, cung cấp các trình kích hoạt được định kiểu cho tất cả các dịch vụ Firebase. Google Cloud Functions là một nền tảng cấp thấp hơn, nơi các trình kích hoạt được cấu hình rõ ràng thông qua Eventarc hoặc Pub/Sub.

Sự khác biệt chính: trong Firebase Cloud Functions, một trình kích hoạt được đăng ký theo cách khai báo thông qua functions.firestore.document('path').onWrite(), trong khi trong Google Cloud Functions, nó được cấu hình thông qua Eventarc với bộ lọc thuộc tính sự kiện. Firebase Cloud Functions cũng đi kèm với Admin SDK được khởi tạo tự động với thông tin xác thực tài khoản dịch vụ của dự án, cung cấp quyền truy cập đầy đủ vào tất cả các dịch vụ Firebase mà không cần thiết lập bổ sung.

Các loại trình kích hoạt: những sự kiện nào được hỗ trợ

Firebase Cloud Functions hỗ trợ 8 loại trình kích hoạt, mỗi loại tương ứng với một dịch vụ Firebase hoặc Google Cloud cụ thể. Trình kích hoạt là một điều kiện khi được đáp ứng sẽ tự động gọi một hàm. Nhà phát triển không quản lý trực tiếp vòng đời của hàm: Firebase CLI đăng ký trình kích hoạt trong Google Cloud Eventarc và nền tảng đám mây chạy hàm khi sự kiện xảy ra.

Các trình kích hoạt phổ biến nhất là trình kích hoạt Firestore: onWrite, onCreate, onUpdate, onDelete. Chúng được kích hoạt khi các tài liệu trong bộ sưu tập Firestore thay đổi. Hàm nhận được ảnh chụp nhanh của tài liệu trước và sau khi thay đổi, cho phép so sánh các giá trị và chỉ phản hồi với những thay đổi cụ thể. Ví dụ: khi trạng thái đơn hàng thay đổi từ “đang chờ xử lý” thành “đã gửi”, thông báo đẩy có thể được gửi đến người dùng.

Trình kích hoạt Authentication (onCreate, onDelete) được kích hoạt khi tài khoản người dùng được tạo hoặc xóa. Chúng được sử dụng để khởi tạo dữ liệu người dùng: tạo tài liệu người dùng trong Firestore, gửi email chào mừng, ghi vào phân tích. Lưu ý: hàm không thể hủy việc tạo người dùng — nó thực thi sau khi tài khoản đã được tạo. Để xác thực trước, hãy sử dụng Blocking Functions có sẵn trên Identity Platform.

Trình kích hoạt HTTPS và CORS

Hàm HTTPS (onRequest) cho phép tạo các điểm cuối REST API hoàn chỉnh có thể truy cập qua HTTP. Không giống như các trình kích hoạt dựa trên sự kiện, hàm HTTPS được gọi thông qua URL có dạng https://{region}-{project}.cloudfunctions.net/{functionName}. Điều quan trọng là cấu hình CORS chính xác nếu điểm cuối được gọi từ trình duyệt hoặc ứng dụng di động. SDK Firebase không tự động bao gồm các tiêu đề CORS — chúng phải được thêm thủ công thông qua middleware.

Đối với khách hàng di động (Android, iOS), CORS không cần thiết vì các máy khách HTTP gốc không bị giới hạn bởi chính sách Cross-Origin. CORS chỉ liên quan đến các yêu cầu web. Nếu hàm HTTPS của bạn được gọi từ cả ứng dụng và web, hãy thêm xử lý CORS phổ quát: res.set('Access-Control-Allow-Origin', '*') cho phát triển hoặc danh sách các tên miền được phép cho sản xuất.

Lên lịch với Pub/Sub và Cloud Scheduler

Để thực thi định kỳ (tác vụ cron), hãy sử dụng kết hợp Cloud Scheduler và Pub/Sub. Cloud Scheduler gửi một tin nhắn đến một chủ đề Pub/Sub theo lịch trình và trình kích hoạt onPublish của Cloud Functions xử lý tin nhắn đó. Firebase CLI không hỗ trợ cú pháp cron trực tiếp — lịch trình được cấu hình thông qua bảng điều khiển Google Cloud hoặc Terraform ở định dạng unix-cron: 0 3 * * * (hàng ngày lúc 3:00).

Ví dụ về tác vụ: bản tin hàng ngày, dọn dẹp dữ liệu cũ, tạo báo cáo, đồng bộ hóa với các API bên ngoài. Quan trọng: Cloud Scheduler là một dịch vụ trả phí của Google Cloud (khoảng $2 mỗi tháng cho mỗi tác vụ). Mỗi lần kích hoạt được tính là một lần gọi hàm riêng biệt và được tính phí theo giá Cloud Functions tiêu chuẩn.

Cách viết và triển khai hàm

Phát triển Cloud Functions bắt đầu bằng cách khởi tạo dự án qua Firebase CLI: firebase init functions. Lệnh này tạo một thư mục functions/ với mẫu index.js (hoặc index.ts), tệp package.json và cấu hình TypeScript (nếu được chọn). Sau khi khởi tạo, chỉ cần viết một hàm, xuất nó từ mô-đun và chạy firebase deploy --only functions để triển khai.

Mỗi hàm được đăng ký bằng cách gọi phương thức kích hoạt thích hợp. Ví dụ về hàm HTTPS: exports.helloWorld = functions.https.onRequest((req, res) => { res.send(“Hello!”); }). Firebase Functions sử dụng mô hình không đồng bộ: đối với các trình kích hoạt dựa trên sự kiện (không phải HTTPS), hàm phải trả về một Promise. Firebase đợi Promise hoàn thành trước khi kết thúc vùng chứa. Nếu Promise không được trả về, hàm có thể bị kết thúc trước khi các hoạt động không đồng bộ hoàn tất.

Phát triển cục bộ được thực hiện thông qua Firebase Emulator Suite, bao gồm một trình giả lập Cloud Functions. Lệnh firebase emulators:start khởi động một máy chủ cục bộ với các hàm có thể truy cập tại http://localhost:5001. Trình giả lập hỗ trợ tải lại nóng khi mã thay đổi và hoàn toàn biệt lập với môi trường sản xuất, cho phép kiểm tra mà không gây rủi ro cho dữ liệu thực.

Quản lý phụ thuộc và cấu hình

Các phụ thuộc của Cloud Functions được quản lý thông qua package.json. Firebase chỉ cài đặt các phụ thuộc sản xuất (dependencies, không phải devDependencies). Kích thước gói hàm ảnh hưởng đến thời gian khởi động nguội: khuyến nghị giảm thiểu số lượng phụ thuộc. Phụ thuộc firebase-admin được cài đặt sẵn cho Firebase Admin SDK — không cần thêm thủ công.

Dữ liệu bảo mật (khóa API, mã thông báo) không nên được lưu trữ trong mã hàm. Sử dụng functions.config() để lưu trữ cấu hình: firebase functions:config:set stripe.key=“sk_...”. Các giá trị được mã hóa và có sẵn trong thời gian chạy thông qua functions.config().stripe.key. Đối với cấu hình tuần tự hóa lớn, hãy sử dụng Google Cloud Secret Manager.

Xử lý lỗi và ghi nhật ký

Ghi nhật ký trong Cloud Functions được thực hiện thông qua console.log, console.warn và console.error. Tất cả nhật ký được tự động thu thập trong Google Cloud Logging và có sẵn trong bảng điều khiển Firebase (Functions > Logs). Để ghi nhật ký có cấu trúc, hãy sử dụng các thư viện winston hoặc pino, hỗ trợ định dạng JSON và các cấp độ nhật ký.

Xử lý lỗi rất quan trọng đối với độ tin cậy: một ngoại lệ không được xử lý trong Promise sẽ kết thúc hàm với lỗi, sau đó Firebase tự động thử lại với backoff theo cấp số nhân. Số lần thử lại có thể cấu hình: từ 0 đến vô hạn. Đối với các trình kích hoạt dựa trên sự kiện, khuyến nghị bật tính năng thử lại để đảm bảo mọi sự kiện đều được xử lý ngay cả khi dịch vụ bên ngoài gặp sự cố tạm thời.

Khởi động nguội và mở rộng quy mô

Khởi động nguội (cold start) là độ trễ trong lần gọi hàm đầu tiên sau một thời gian không hoạt động, khi vùng chứa mã được tải và khởi tạo lại. Theo tài liệu Firebase (2026), khởi động nguội mất từ 200 ms đến 2 giây tùy thuộc vào kích thước gói, số lượng phụ thuộc và khu vực. Đối với giao diện người dùng, độ trễ trên 1 giây là đáng chú ý và có thể ảnh hưởng đến trải nghiệm người dùng.

Các cách giảm thiểu khởi động nguội: giảm thiểu phụ thuộc, sử dụng TypeScript biên dịch sang CommonJS, giảm kích thước gói hàm, đặt số lượng phiên bản hoạt động tối thiểu. Firebase Cloud Functions v2 (thế hệ thứ 2) cho phép đặt minInstances — số lượng vùng chứa ấm tối thiểu luôn sẵn sàng xử lý yêu cầu. Giữ các vùng chứa ấm sẽ phát sinh phí cho thời gian nhàn rỗi.

Mở rộng quy mô của Cloud Functions diễn ra tự động: khi khối lượng yêu cầu tăng lên, Firebase tạo các vùng chứa mới. Theo mặc định, số lượng phiên bản song song tối đa là 3000 (hạn ngạch dự án Google Cloud). Mỗi phiên bản xử lý một yêu cầu tại một thời điểm. Nếu một hàm nhanh (dưới 100 ms), một phiên bản có thể xử lý tới 10 yêu cầu mỗi giây, cung cấp thông lượng cao điểm lên tới 30.000 yêu cầu mỗi giây cho mỗi dự án.

Cấu hình minInstances và maxInstances

minInstances là một tham số dự trữ một số lượng vùng chứa cụ thể và giữ chúng ấm. Nó được khuyến nghị cho các hàm HTTPS quan trọng, nơi độ trễ khởi động nguội là không thể chấp nhận được. Ví dụ: đối với điểm cuối xác thực, hãy đặt minInstances: 1. maxInstances giới hạn số lượng phiên bản song song tối đa, hữu ích để ngăn chặn sự gia tăng chi phí không kiểm soát được khi lưu lượng truy cập tăng đột biến.

Cấu hình được thực hiện trong mã: functions.runWith({ minInstances: 1, maxInstances: 10 }). Quan trọng: minInstances làm tăng chi phí vì các vùng chứa chạy liên tục. Đối với các dự án thử nghiệm, minInstances nên được tắt. Đối với sản xuất, minInstances được khuyến nghị cho tất cả các hàm HTTPS công khai và 0 cho các trình kích hoạt dựa trên sự kiện, nơi độ trễ 1 giây không quan trọng.

Khu vực triển khai

Khu vực triển khai ảnh hưởng đến độ trễ đối với người dùng cuối và chi phí lưu lượng truy cập đi. Firebase Cloud Functions có sẵn tại hơn 30 khu vực Google Cloud. Đối với ứng dụng di động, hãy chọn khu vực gần nhất với đối tượng mục tiêu của bạn: us-central1 cho Châu Mỹ, europe-west1 cho Châu Âu, asia-east2 cho Châu Á. Khu vực không thể thay đổi sau khi triển khai mà không triển khai lại hàm.

Việc thay đổi khu vực được thực hiện thông qua tham số region trong mã: functions.region('europe-west1'). Tất cả các hàm trong một tệp có thể có các khu vực khác nhau. Đối với các dự án toàn cầu, khuyến nghị triển khai các hàm ở nhiều khu vực và sử dụng Cloud Load Balancing để phân phối lưu lượng, mặc dù đối với hầu hết các ứng dụng di động, một khu vực duy nhất là đủ nếu được chọn đúng.

Ví dụ mã cho Firebase Cloud Functions

Hãy xem các ví dụ thực tế về Cloud Functions trong TypeScript. Mã sử dụng Firebase Functions SDK v2 (thế hệ thứ 2) với cú pháp mô-đun ES. Các ví dụ bao gồm xử lý sự kiện tạo người dùng, tạo hình thu nhỏ khi tải ảnh lên và một điểm cuối HTTPS đơn giản cho REST API. Tất cả các hàm đều không đồng bộ và trả về một Promise để kết thúc vùng chứa đúng cách.

Trước khi chạy, hãy đảm bảo Firebase CLI đã được cập nhật lên phiên bản 13+: npm install -g firebase-tools. Hàm v2 yêu cầu gói giá Blaze. Khởi tạo: firebase init functions với TypeScript được chọn.

Xử lý đăng ký người dùng

Ví dụ đầu tiên — tạo một tài liệu trong Firestore khi người dùng mới đăng ký. Hàm được kích hoạt bởi sự kiện auth.user().onCreate và ghi một hồ sơ cơ bản vào bộ sưu tập users/{uid}. Điều này đảm bảo rằng mỗi người dùng đã đăng ký đều có một tài liệu với các trường cần thiết.

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}`)
    })

Hàm createUserProfile là không đồng bộ — nó trả về một Promise mà Firebase chờ đợi trước khi kết thúc. Nếu việc ghi vào Firestore thất bại (ví dụ: do quyền không đủ), hàm sẽ được tự động thử lại (nếu tính năng thử lại được bật). Trường role với giá trị “free” cho phép triển khai các hạn chế của gói miễn phí trực tiếp trong Security Rules của Firestore bằng cách so sánh resource.data.role với mức truy cập yêu cầu.

Tạo hình thu nhỏ khi tải ảnh lên

Ví dụ thứ hai — một trình kích hoạt Storage để tự động tạo hình thu nhỏ sau khi tải ảnh lên. Hàm tạo một bản sao thu nhỏ có kích thước 200×200 pixel và lưu nó vào đường dẫn của tệp gốc với tiền tố thumb_. Xử lý hình ảnh sử dụng thư viện sharp, hỗ trợ tất cả các định dạng phổ biến và hoạt động trong môi trường Node.js mà không cần phụ thuộc hệ thống.

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 })
    })

Hàm generateThumbnail kiểm tra Content-Type của đối tượng và bỏ qua các tệp không phải hình ảnh, tiết kiệm tài nguyên. Để sử dụng sharp, phụ thuộc phải được thêm vào package.json. Hình thu nhỏ được tạo với tham số fit: “cover”, cắt ảnh từ trung tâm thành hình vuông 200×200 pixel. Sau khi tạo, hình thu nhỏ được tải lên lại cùng một bucket với tên đã sửa đổi.

Điểm cuối HTTPS cho API công khai

Ví dụ thứ ba — một hàm HTTPS triển khai điểm cuối REST API để kiểm tra trạng thái máy chủ. Hàm chấp nhận yêu cầu GET và trả về JSON với thông tin về trạng thái của các dịch vụ Firebase được kết nối với dự án. Điểm cuối này hữu ích cho việc giám sát và các hệ thống bên ngoài cần xác minh tính khả dụng của backend trước khi gửi dữ liệu.

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)

Hàm api sử dụng express Router để định tuyến, thuận tiện khi tạo nhiều điểm cuối trong một hàm. Kiểm tra sức khỏe ghi vào Firestore trong bộ sưu tập _health, cho phép xác minh đồng thời tính khả dụng của Firestore. Đối với sản xuất, khuyến nghị thêm xác thực yêu cầu thông qua khóa API hoặc mã thông báo Firebase Auth để ngăn chặn lạm dụng điểm cuối công khai.

Các trường hợp sử dụng điển hình trong ứng dụng di động

Cloud Functions thường được sử dụng nhất cho các tác vụ không thể hoặc không nên thực hiện trên máy khách: gửi thông báo đẩy, tạo bản xem trước của hình ảnh đã tải lên, tích hợp với hệ thống thanh toán bên ngoài, kiểm duyệt nội dung, đồng bộ hóa dữ liệu giữa Firebase và các dịch vụ bên thứ ba. Mô hình không máy chủ làm cho các tác vụ này trở nên hiệu quả về chi phí: bạn chỉ trả tiền cho thời gian thực thi mã thực tế.

Tích hợp hệ thống thanh toán là một kịch bản điển hình cho các ứng dụng có giao dịch mua trong ứng dụng. Cloud Functions nhận webhook từ nhà cung cấp thanh toán (Stripe, PayPal), xác minh chữ ký yêu cầu, cập nhật trạng thái đăng ký trong Firestore và gửi xác nhận cho người dùng. Tất cả mã chạy trên máy chủ mà không có rủi ro giả mạo dữ liệu trên máy khách. Theo tài liệu Stripe (2026), xử lý webhook mất dưới 500 ms.

Kiểm duyệt nội dung thông minh sử dụng trình kích hoạt Storage của Cloud Function để tự động kiểm tra hình ảnh đã tải lên thông qua Google Cloud Vision API. Hàm gửi hình ảnh đến Vision API để phát hiện nội dung không an toàn (bạo lực, nội dung người lớn) và nếu vượt quá ngưỡng, sẽ xóa tệp và thông báo cho quản trị viên. Kịch bản này rất quan trọng đối với các ứng dụng UGC có thư viện người dùng.

Tổng hợp dữ liệu — Cloud Functions như một sự thay thế cho các bộ đếm Firebase Realtime Database. Thay vì đọc và ghi bộ đếm trên máy khách (dẫn đến điều kiện cạnh tranh), hãy sử dụng trình kích hoạt onWrite của Firestore để cập nhật nguyên tử các trường tổng hợp. Ví dụ: một hàm đếm số lượt thích của bài viết mỗi khi một tài liệu được thêm hoặc xóa trong bộ sưu tập con /posts/{postId}/likes/{userId} và cập nhật trường likesCount trong tài liệu cha.