به‌طور پیش‌فرض، Firebase Crashlytics به‌طور خودکار پروژه Flutter شما را ابزاربندی می‌کند تا فایل‌های نماد ضروری را بارگذاری کند و مطمئن شود گزارش‌های خرابی مبهم‌سازی‌نشده و قابل‌خواندن برای انسان هستند.
متأسفانه، مواردی وجود دارد که می‌تواند منجر به پیکربندی کامل پروژه نشود. این راهنما آنچه را که خودکارسازی انجام می‌دهد شرح می‌دهد و اولین
گام‌ها را برای اشکال‌زدایی راه‌اندازی پروژه شما ارائه می‌دهد.
پلاتفرم‌های Apple
پیکربندی خود را برای بارگذاری فایل‌های dSYM بررسی کنید
افزودن افزایه Crashlytics Flutter و اجرای فرمان
flutterfire configure تلاش می‌کند تا یک دستور اجرا به فضای کاری Xcode پروژه شما اضافه کند که فایل‌های نماد dSYM لازم را پیدا و در Crashlytics بارگذاری می‌کند. بدون این فایل‌ها، هشدار «dSYM وجود ندارد» را در داشبورد Crashlytics خواهید دید و استثناها تا زمانی که فایل‌های گم‌شده بارگذاری شوند در زیرینه نگهداری خواهند شد.
اگر این مشکل را دارید، ابتدا مطمئن شوید که اسکریپت اجرا را نصب کرده‌اید:
فایل فضای کاری Xcode را در فهرستگان iOS پروژه خود پیدا کنید و باز کنید
(FLUTTER_PROJECT_NAME/ios/Runner.xcworkspace).
مشخص کنید که آیا یک اسکریپت اجرایی با عنوان
[firebase_crashlytics] Crashlytics Upload Symbols به
مراحل ساخت هدف «اجراکننده» اضافه شده است یا نه.
اگر این اسکریپت اجرا وجود ندارد، می‌توانید آن را به‌صورت دستی اضافه کنید:
«شناسه برنامه Firebase» را برای برنامه Apple خود پیدا کنید. در اینجا دو مکان مختلف وجود دارد که می‌توانید این شناسه را پیدا کنید:
در کنسول Firebase، به
settings > تنظیمات پروژه بروید.
به کارت برنامه‌های شما بروید، سپس روی
«برنامه Apple Firebase» کلیک کنید تا اطلاعات برنامه، ازجمله شناسه برنامه آن را ببینید.
در دایرکتوری سطح بالای پروژه Flutter خود، فایل
firebase_options.dart را پیدا کنید. شناسه برنامه Firebase برای برنامه Apple شما
با برچسب appId مشخص شده است.
روی add >
مرحله جدید اجرای متن کلیک کنید.
مطمئن شوید که این مرحله جدید اجرای دستورگان آخرین مرحله ساخت پروژه شما است. درغیراین‌صورت، Crashlytics نمی‌تواند dSYM را به‌درستی پردازش کند.
بخش جدید اجرای دستورگان را ازهم باز کنید.
در فیلد فیلم‌نامه (واقع در زیر برچسب پوسته)،
فیلم‌نامه‌های اجرایی زیر را اضافه کنید.
این دستورگان‌ها فایل‌های dSYM شما را پردازش می‌کنند و فایل‌ها را در
Crashlytics بارگذاری می‌کنند.
Xcode در مکان‌های مشخص‌شده به‌دنبال این فایل‌های ورودی می‌گردد تا مطمئن شود
فایل‌های ساخت برای اجرای دستورگان دردسترس هستند. همچنین، اگر
User Script Sandboxing (جعبه ایمن اسکریپت کاربر) فعال باشد، Xcode فقط به اسکریپت اجرا اجازه می‌دهد به فایل‌های مشخص‌شده در Input Files (فایل‌های ورودی) دسترسی داشته باشد.
ارائه مکان فایل‌های dSYM پروژه شما به
Crashlytics امکان می‌دهد dSYMها را پردازش کند.
ارائه مکان فایل ساخته‌شده برنامه
GoogleService-Info.plist
به Crashlytics امکان می‌دهد dSYM را با
برنامه Firebase شما مرتبط کند.
ارائه مکان فایل اجرایی برنامه به اسکریپت اجرا امکان می‌دهد
از بارگذاری‌های تکراری dSYM یکسان جلوگیری کند. توجه داشته باشید که
باینری‌های برنامه بارگذاری نمی‌شوند.
اجرای دستورگان برای بارگذاری خودکار dSYM وجود دارد
اگر دستور اجرای اسکریپت وجود دارد، به
راهنمای مختص Apple برای عیب‌یابی مشکلات dSYM مراجعه کنید.
اگر انتخاب کنید که فایل‌های dSYM خود را ازطریق فرایند شرح‌داده‌شده بارگذاری کنید، باید مراحل تکمیلی زیر را انجام دهید:
«شناسه برنامه Firebase» را برای برنامه Apple خود پیدا کنید. در اینجا دو مکان مختلف وجود دارد که می‌توانید این شناسه را پیدا کنید:
در کنسول Firebase، به
settings > تنظیمات پروژه بروید.
به کارت برنامه‌های شما بروید، سپس روی
«برنامه Apple Firebase» کلیک کنید تا اطلاعات برنامه، ازجمله شناسه برنامه آن را ببینید.
در دایرکتوری سطح بالای پروژه Flutter خود، فایل
firebase_options.dart را پیدا کنید. شناسه برنامه Firebase برای برنامه Apple شما
با برچسب appId مشخص شده است.
هنگام اجرای دستورگان upload-symbols، از
-ai FIREBASE_APPLE_APP_ID به‌جای
-gsp /path/to/GoogleService-Info.plist استفاده کنید.
پیکربندی نسخه Flutter و Crashlytics(درصورت استفاده از پرچم --split-debug-info) را بررسی کنید
اگر پروژه Flutter شما از پرچم --split-debug-info (و به‌صورت اختیاری،
همچنین از پرچم --obfuscate) استفاده می‌کند، برای نمایش ردیابی پشته خوانا برای برنامه‌تان، مراحل اضافی لازم است.
مطمئن شوید که پروژه شما از پیکربندی نسخه توصیه‌شده (Flutter 3.12.0+ و Crashlytics افزایه Flutter 3.3.4+) استفاده می‌کند تا پروژه شما بتواند به‌طور خودکار نمادهای Flutter (فایل‌های dSYM) را در Crashlytics تولید و بارگذاری کند.
Android
پیکربندی وابستگی را بررسی کنید
فرمان flutterfire configure تلاش می‌کند وابستگی‌های لازم را به
فایل‌های ساخت Gradle پروژه شما اضافه کند. بدون این وابستگی‌ها، گزارش‌های خرابی در
کنسول Firebase ممکن است درصورت روشن بودن مبهم‌سازی، مبهم شوند.
مطمئن شوید خطوط زیر در سطح پروژه build.gradle
و در سطح برنامه build.gradle وجود داشته باشد:
در فایل ساخت سطح پروژه (android/build.gradle)، خط زیر را بررسی کنید:
در فایل ساخت سطح برنامه (android/app/build.gradle)، خط زیر را بررسی کنید:
// ... other importsandroid{// ... your android config}dependencies{// ... your dependencies}// This section must appear at the bottom of the fileapplyplugin:'com.google.gms.google-services'applyplugin:'com.google.firebase.crashlytics'
بررسی کنید که از CLI برای بارگذاری نمادهای Flutter استفاده می‌کنید (درصورت استفاده از پرچم --split-debug-info)
اگر پروژه Flutter شما از پرچم --split-debug-info (و به‌صورت اختیاری،
همچنین از پرچم --obfuscate) استفاده می‌کند، برای نمایش ردیابی پشته خوانا برای برنامه‌تان، مراحل اضافی لازم است.
برای بارگذاری نمادهای اشکال‌زدایی Flutter، از Firebase CLI (نسخه ۱۱.۹.۰ و بالاتر) استفاده کنید. باید نمادهای اشکال‌زدایی را قبل‌از گزارش خرابی از ساخت کد مبهم‌سازی‌شده بارگذاری کنید.
از فهرست راهنمای ریشه پروژه Flutter خود، فرمان زیر را اجرا کنید:
تاریخ آخرین بهروزرسانی 2026-10-07 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2026-10-07 بهوقت ساعت هماهنگ جهانی."],[],[]]
