Trong quá trình xây dựng và vận hành Zalo Mini App, nhà phát triển có thể gặp nhiều lỗi liên quan đến kết nối mạng, API, hiển thị hình ảnh, quyền ứng dụng, đóng gói phiên bản hoặc triển khai CI/CD. Nếu không xác định đúng nguyên nhân, các lỗi này có thể làm gián đoạn trải nghiệm người dùng và kéo dài thời gian phát triển. Bài viết dưới đây, Abenla sẽ tổng hợp các lỗi kỹ thuật phổ biến khi phát triển Zalo Mini App, đồng thời gợi ý hướng xử lý phù hợp.

1. Lỗi Network Error khi gọi API

Network Error là lỗi phổ biến khi Zalo Mini App gọi API từ ứng dụng đến server của doanh nghiệp thông qua axios hoặc fetch.

Một số nguyên nhân thường gặp gồm:

CORS chưa được cấu hình đúng.
API sử dụng HTTP thay vì HTTPS.
Domain API hết hạn chứng chỉ SSL.
Server không cho phép custom header.
Thiết bị, đường truyền hoặc server gặp sự cố mạng.

Cách xử lý lỗi CORS

Dấu hiệu thường thấy của lỗi CORS là API có thể gọi thành công bằng Postman, cURL hoặc localhost nhưng không hoạt động trên Zalo Mini App.

Đây là cơ chế bảo mật của trình duyệt web, không phải lỗi riêng của Mini App. Vì vậy, việc xử lý cần được thực hiện tại server.

Server cần trả về header Access-Control-Allow-Origin với origin phù hợp của Mini App:

https://h5.zdn.vn

Ví dụ cấu hình không hợp lệ:

Access-Control-Allow-Origin: https://h5.zdn.vn,http://localhost:3000

Ví dụ cấu hình hợp lệ là kiểm tra origin từ request và chỉ trả về một giá trị tương ứng:

Access-Control-Allow-Origin: https://h5.zdn.vn

Hoặc trong môi trường localhost:

Access-Control-Allow-Origin: http://localhost:3000

Ngoài ra, nếu server đã cấu hình CORS cho GET, POST, PUT hoặc DELETE nhưng chưa cấu hình cho method OPTIONS, request tiền kiểm tra vẫn có thể bị lỗi. Khi đó, cần đảm bảo header CORS cũng được trả về cho request OPTIONS.

Lưu ý về HTTPS và SSL

Zalo Mini App chạy trong môi trường bảo mật nên các API không sử dụng HTTPS hoặc dùng IP trực tiếp có thể không hoạt động.

Ví dụ không nên dùng:

fetch(“https://118.63.103.143:443”);

fetch(“http://my-server.com/api”);

Nên dùng domain có SSL hợp lệ:

fetch(“https://my-server.com/api”);

2. Minified React Error

Các lỗi có dạng Minified React error #… thường xuất hiện khi mã React gặp vấn đề nhưng nội dung lỗi đã được rút gọn trong quá trình build để giảm dung lượng ứng dụng.

Nguyên nhân có thể bao gồm:

Sử dụng Hooks không đúng quy tắc.
Cập nhật state trong lúc render.
Render component không hợp lệ.
Truyền dữ liệu không đúng kiểu vào component.

Để xử lý, nhà phát triển nên mở đường link được hiển thị trong thông báo lỗi React. Trang này sẽ giải mã mã lỗi và cung cấp mô tả chi tiết để xác định nguyên nhân.

3. Hình ảnh không hiển thị trên Zalo Mini App

Một lỗi thường gặp là hình ảnh hiển thị bình thường trên localhost nhưng không xuất hiện khi chạy trên Zalo Mini App thực tế.

Ví dụ không nên sử dụng:

Hoặc:

Thay vào đó, cần import hình ảnh để Vite đóng gói file cùng mã nguồn ứng dụng:

import coffee from “./coffee.jpg”;

<img src={coffee} />;

Cách này giúp Zalo Mini App xác định đúng đường dẫn và đảm bảo hình ảnh được đưa vào bản build.

4. Gọi API Server-to-Server trực tiếp từ Mini App

Một số API được thiết kế để server của doanh nghiệp gọi đến server Zalo, không nên gọi trực tiếp từ phía Zalo Mini App.

Ví dụ:

Decode token để lấy số điện thoại hoặc vị trí.
Gửi thông báo đến người dùng.
Các API thuộc nhóm OpenAPI.
Một số API của Checkout SDK như getOrderStatus hoặc updateOrderStatus.

Các API này thường yêu cầu private key hoặc app secret. Nếu gọi trực tiếp từ Mini App, thông tin nhạy cảm có thể bị lộ, đồng thời request có thể bị chặn bởi CORS hoặc giới hạn IP.

Cách xử lý đúng là đưa logic gọi API về server của doanh nghiệp. Mini App chỉ gửi request đến server nội bộ, sau đó server sẽ xử lý giao tiếp với hệ thống Zalo.

5. API gọi thành công nhưng không có dữ liệu khi phát triển

Trong quá trình phát triển bằng Zalo Mini App Studio, Extension hoặc CLI, Simulator và trình duyệt chủ yếu hỗ trợ xem giao diện. Một số luồng cần chạy trong môi trường Zalo thực tế mới hoạt động đầy đủ.

Ví dụ:

getAccessToken
getPhoneNumber
createOrder

Để lấy dữ liệu thật, nhà phát triển nên sử dụng chế độ Device. Chế độ này cho phép Mini App chạy trong ứng dụng Zalo trên điện thoại và kết nối với hot reload server trên máy tính.

6. Lỗi trên phiên bản Live nhưng không xác định được nguyên nhân

Khi Zalo Mini App đã phát hành nhưng phát sinh lỗi, nhà phát triển có thể kiểm tra bằng hai cách.

Thêm tham số zDebug=true

Thêm zDebug=true vào Deep Link của Mini App để hiển thị công cụ Debug trên phiên bản Live.

Ví dụ:

https://zalo.me/s/194839900003483517/?zDebug=true

Khi bật Debug, bạn có thể kiểm tra:

Console logs.
Network requests.
Element inspector.
Các thông tin hỗ trợ gỡ lỗi khác.

Kết nối Android qua USB để debug

Nhà phát triển cũng có thể kết nối thiết bị Android với máy tính bằng cáp USB và dùng Google Chrome để debug.

Phương pháp này hỗ trợ kiểm tra lỗi chi tiết hơn, bao gồm:

Profiling.
Breakpoints.
Kiểm tra network.
Phân tích luồng xử lý của ứng dụng.

7. Lỗi chỉ xảy ra với người dùng ngoài nhóm Developer hoặc Admin

Nếu Zalo Mini App sử dụng một số API như:

getPhoneNumber
getLocation
openMediaPicker
requestCameraPermission
keepScreen
Nhóm API Native Storage

thì nhà phát triển cần gửi yêu cầu cấp quyền cho Mini App ID.

Trong giai đoạn phát triển, tài khoản Developer hoặc Admin có thể sử dụng các API này mà không cần chờ xét duyệt. Tuy nhiên, người dùng thông thường sẽ gặp lỗi nếu Mini App chưa được cấp quyền tương ứng.

Để xử lý, hãy vào mục Quản lý > Quản lý quyền hoặc thực hiện bước cấp quyền khi gửi xét duyệt phiên bản.

8. Lỗi “Trang này không tìm thấy hoặc không hợp lệ”

Lỗi này thường xảy ra khi người dùng mở phiên bản Development hoặc Testing bằng tài khoản Zalo không thuộc nhóm Developer hoặc Admin của Mini App.

Cách xử lý:

Đăng nhập lại bằng tài khoản được thêm vào nhóm Developer hoặc Admin.
Hoặc mở phiên bản Live của Zalo Mini App.

9. Lỗi “Ứng dụng đang trong giai đoạn phát triển”

Thông báo này xuất hiện khi người dùng mở phiên bản Live của Zalo Mini App nhưng ứng dụng chưa có bản Live được phát hành.

Nhà phát triển cần hoàn tất quy trình gửi xét duyệt và phát hành phiên bản Live trước khi chia sẻ Mini App đến người dùng thông thường.

10. Không tìm thấy Zalo Mini App trên Mini App Store hoặc thanh tìm kiếm

Một số Mini App có thể không hiển thị trên Mini App Store hoặc thanh tìm kiếm Zalo do nền tảng tạm tắt khả năng tìm kiếm.

Nguyên nhân có thể là:

Mini App sử dụng form đăng nhập truyền thống bằng tên đăng nhập và mật khẩu.
Mini App chỉ phù hợp cho nhóm người dùng nội bộ như trường học hoặc doanh nghiệp.
Mini App có vấn đề trong quá trình xét duyệt nhưng vẫn được đồng ý phát hành theo mục đích riêng.
Mini App cần được truy cập bằng Deep Link, QR Code hoặc Shortcut thay vì tìm kiếm công khai.

Nếu muốn mở lại khả năng tìm kiếm, doanh nghiệp cần:

Điều chỉnh luồng đăng nhập hoặc khắc phục vấn đề còn tồn tại.
Gửi một phiên bản mới để xét duyệt.
Nêu rõ yêu cầu mở tìm kiếm và hiển thị công khai trong mô tả gửi xét duyệt.

11. Không thể cut, copy hoặc paste trong Extension

Trên macOS, việc cut, copy hoặc paste trong Zalo Mini App Extension có thể bị ảnh hưởng do Extension sử dụng iframe trong Visual Studio Code.

Cách xử lý tạm thời:

Bôi đen phần nội dung cần sao chép.
Chọn menu Edit > Copy.
Thực hiện tương tự với thao tác Cut hoặc Paste.

12. Lỗi Cannot find module ‘@vitejs/plugin-react-refresh’

Lỗi này xuất hiện khi dự án đã chuyển từ @vitejs/plugin-react-refresh sang @vitejs/plugin-react nhưng chưa cập nhật cấu hình Vite.

Ví dụ cấu hình cũ:

import reactRefresh from “@vitejs/plugin-react-refresh”;

plugins: [

reactRefresh(),

];

Cấu hình mới:

import react from “@vitejs/plugin-react”;

plugins: [

react(),

];

Sau khi thay đổi, kiểm tra lại file vite.config.js hoặc vite.config.ts để đảm bảo plugin được import và sử dụng đúng.

13. Lỗi vượt quá giới hạn deploy trong tháng

Thông báo sau cho biết Mini App đã sử dụng hết quota deploy:

You have reached your 30-day deployment limit. Please try again later.

Giới hạn deploy gồm:

300 lần mỗi tháng đối với phiên bản Development.
60 lần mỗi tháng đối với phiên bản Testing.

Khi đã dùng hết quota, nhà phát triển cần chờ đến chu kỳ tiếp theo hoặc tối ưu quy trình kiểm thử để hạn chế số lần deploy không cần thiết.

14. Lỗi dung lượng file quá lớn

Mỗi phiên bản Zalo Mini App có giới hạn dung lượng:

Tổng dung lượng ứng dụng không quá 10MB.
Mỗi file không quá 3MB.

Khi gặp lỗi dung lượng, có thể xử lý bằng cách:

Đưa ảnh, video và static resource lên server riêng hoặc CDN.
Nén file hình ảnh, video và tài nguyên tĩnh.
Sử dụng code splitting cho các file script có dung lượng lớn.
Loại bỏ thư viện không cần thiết trong dự án.

15. Lỗi CI/CD khi deploy Zalo Mini App

Một lỗi CI/CD thường gặp là:

Error: Permission denied. Please login again. (Tips: Run ‘zmp login’)

Nguyên nhân có thể đến từ việc cấu hình sai thông tin xác thực.

Cần kiểm tra:

ZALO_APP_SECRET và ZALO_REFRESH_TOKEN có khớp với ZALO_APP_ID hay không.
Không nhầm lẫn giữa MINI_APP_ID và ZALO_APP_ID.
Biến ZMP_TOKEN trong file .env có bị ghi đè bởi biến môi trường trên runner hay không.

Nhà phát triển có thể thử chạy lệnh deploy hoặc login trực tiếp trên máy tính cá nhân để kiểm tra trước khi triển khai trên CI/CD.

16. Lỗi ES2015

Một số thư viện sử dụng tính năng JavaScript mới có thể không tương thích với target ES2015 mặc định của Zalo Mini App.

Ví dụ lỗi:

Transforming async generator functions to the configured target environment (“es2015”) is not supported yet

Hoặc:

Transforming for-await loops to the configured target environment (“es2015”) is not supported yet

Cách xử lý gồm:

Nâng target trong file vite.config.js hoặc vite.config.ts.
Thay thư viện khác có khả năng tương thích tốt hơn.
Cân nhắc sử dụng fetch thay cho một số thư viện nặng.
Ưu tiên các thành phần ZaUI thay vì thư viện không phù hợp với môi trường Mini App.

Lưu ý, việc nâng target có thể làm giảm khả năng tương thích với thiết bị cũ.

17. Lỗi xem hoặc tải file PDF

Việc mở PDF trong Zalo Mini App có thể hoạt động khác nhau giữa Android và iOS, tùy thuộc vào header Content-Disposition của file.

Do khác biệt kỹ thuật giữa nền tảng, việc thiết kế luồng tải file PDF có thể gây trải nghiệm không ổn định. Thay vì yêu cầu người dùng tải file, nhà phát triển nên ưu tiên hiển thị PDF trực tiếp trong Mini App.

Một giải pháp thường được sử dụng là thư viện react-pdf@5.x, giúp tăng khả năng tương thích với các thiết bị cũ.

18. Lỗi import zmp-sdk từ Cocos Creator

Cocos Creator có cơ chế import thư viện JavaScript khác với Mini App thông thường. Khi gặp lỗi import zmp-sdk, có thể thử cú pháp sau:

import “reflect-metadata”;

import sdk, { SDKCreator } from “zmp-sdk”;

(sdk[“default”] as SDKCreator).getAccessToken();

Ngoài ra, nhà phát triển có thể cân nhắc sử dụng zmp-sdk từ CDN nếu phù hợp với dự án.

19. TailwindCSS không cập nhật style mới ở Device Mode

Lỗi này thường xảy ra khi dự án sử dụng Vite 2.6.x và chạy Device Mode mà không bật kết nối trực tiếp.

Cách khắc phục là nâng cấp Vite:

npm i vite@^2.9

Nếu dùng Zalo Mini App Extension, sau khi nâng cấp cần chạy lệnh:

Developer: Reload Window

để thay đổi có hiệu lực.

20. Lỗi “adb is not recognized” khi dùng Device Mode

Kết nối trực tiếp với Device Mode yêu cầu máy tính cài đặt Android Debug Bridge, hay còn gọi là adb.

Nếu gặp lỗi:

adb is not recognized

hoặc:

command not found: adb

nguyên nhân thường là máy chưa cài adb hoặc chưa thiết lập biến môi trường cho adb.

Sau khi cài đặt, hãy kiểm tra bằng lệnh:

adb

Nếu terminal hiển thị thông tin phiên bản Android Debug Bridge, adb đã sẵn sàng để sử dụng.

21. Một số lưu ý khi gặp lỗi khác

Nếu chưa tìm thấy lỗi trong danh sách trên, nhà phát triển nên:

Cập nhật ZMP SDK, ZaUI, CLI, Extension và ứng dụng Zalo lên phiên bản mới nhất.
Kiểm tra lại thay đổi gần nhất trong mã nguồn hoặc cấu hình deploy.
Tìm kiếm lỗi trong cộng đồng Zalo Mini App.
Tạo yêu cầu hỗ trợ mới để nhận hướng dẫn từ đội ngũ kỹ thuật.

Việc phát triển Zalo Mini App có thể phát sinh nhiều lỗi kỹ thuật liên quan đến API, quyền truy cập, cấu hình mạng, đóng gói hoặc triển khai phiên bản. Tuy nhiên, khi xác định đúng nguyên nhân và xử lý theo từng nhóm lỗi, đội ngũ phát triển có thể rút ngắn thời gian khắc phục và đảm bảo Mini App vận hành ổn định. Abenla hy vọng bài viết này sẽ giúp nhà phát triển dễ dàng tra cứu các lỗi phổ biến trong quá trình xây dựng Zalo Mini App, từ đó tối ưu hiệu suất ứng dụng.

Xem thêm:

Thông tin liên hệ:

Công ty TNHH ABENLA