رفع مشکل افزونه ناپ کامرس | راهنمای جامع عیب‌یابی و حل خطاها

آشنایی با مشکلات رایج افزونه‌ها در ناپ کامرس

پیش از هر اقدامی برای رفع مشکل افزونه ناپ کامرس، بهتر است با انواع خطاهایی که ممکن است با آنها مواجه شوید آشنا شوید. این آشنایی به شما کمک می‌کند تا سریع‌تر و دقیق‌تر مشکل را شناسایی کنید.

خطاهای نصب و فعال‌سازی

این دسته از خطاها زمانی رخ می‌دهند که قصد نصب یا فعال‌سازی یک افزونه جدید را دارید. رایج‌ترین این خطاها عبارتند از:

• افزونه در لیست افزونه‌ها نمایش داده نمی‌شود.
• خطای ۵۰۰ یا خطای سرور داخلی هنگام نصب.
• خطای عدم تطابق نسخه (Version mismatch).
• افزونه نصب می‌شود اما فعال نمی‌شود.

خطاهای عملکردی (Runtime Errors)

این خطاها زمانی رخ می‌دهند که افزونه نصب و فعال است اما به درستی کار نمی‌کند. از جمله:

• افزونه باعث کندی یا هنگ کردن فروشگاه می‌شود.
• تنظیمات افزونه ذخیره نمی‌شود.
• افزونه با سایر افزونه‌ها تداخل دارد.
• افزونه خطای اتصال به سرویس‌های خارجی (مانند درگاه پرداخت) می‌دهد.

خطاهای امنیتی و مجوزها

برخی خطاها به دلیل محدودیت‌های امنیتی یا مجوزهای نادرست رخ می‌دهند:

• خطای دسترسی (Access Denied) هنگام تنظیم افزونه.
• خطای لایسنس (License expired or invalid).
• خطای مربوط به مجوزهای پوشه‌ها و فایل‌ها.

گام‌های اولیه برای رفع مشکل افزونه ناپ کامرس

قبل از هر گونه عیب‌یابی عمیق، این مراحل اولیه را انجام دهید. بسیاری از مشکلات با این اقدامات ساده برطرف می‌شوند.

مرحله ۱: راه‌اندازی مجدد برنامه (Restart Application)

ناپ کامرس دارای یک مکانیزم کش داخلی است. گاهی پس از نصب یا تغییر تنظیمات افزونه، تغییرات به درستی اعمال نمی‌شوند و با یک راه‌اندازی مجدد مشکل برطرف می‌شود. برای این کار:

• به پنل مدیریت بروید.
• به بخش Configuration > Local plugins بروید.
• روی دکمه Restart application که در بالای صفحه قرار دارد کلیک کنید.

مرحله ۲: بارگذاری مجدد لیست افزونه‌ها (Reload List)

اگر افزونه‌ای که نصب کرده‌اید در لیست نمایش داده نمی‌شود، ممکن است سیستم لیست افزونه‌ها را به روز نکرده باشد. روی دکمه Reload list of plugins کلیک کنید تا لیست مجدداً اسکن شود.

مرحله ۳: بررسی لاگ‌های سیستم (System Logs)

ناپ کامرس تمام خطاها را در بخش لاگ ثبت می‌کند. برای مشاهده لاگ‌ها:

• به پنل مدیریت بروید.
• به مسیر System > Log بروید.
• خطاهای مرتبط با افزونه مورد نظر را پیدا کنید.
• پیام خطا را کپی کرده و برای جستجوی راه‌حل از آن استفاده کنید.

مرحله ۴: پاک کردن کش (Clear Cache)

کش مرورگر و کش سیستم می‌تواند باعث نمایش اطلاعات قدیمی شود. کش مرورگر خود را پاک کنید و در صورت امکان، کش ناپ کامرس را نیز از بخش System > Maintenance > Clear cache پاک کنید.

رفع مشکلات رایج نصب و فعال‌سازی افزونه

در این بخش، به صورت تخصصی به رفع مشکل افزونه ناپ کامرس در مرحله نصب و فعال‌سازی می‌پردازیم.

مشکل ۱: افزونه در لیست نمایش داده نمی‌شود

دلایل احتمالی:

• فایل‌های افزونه به درستی در پوشه /plugins کپی نشده‌اند.
• ساختار پوشه افزونه نامناسب است (مثلاً یک پوشه اضافی وجود دارد).
• نسخه افزونه با نسخه ناپ کامرس شما سازگار نیست.

راه‌حل‌ها:

• با استفاده از FTP، مسیر /plugins را بررسی کنید و مطمئن شوید که پوشه افزونه در آنجا قرار دارد.
• اگر فایل ZIP را به صورت دستی استخراج کرده‌اید، بررسی کنید که آیا یک پوشه اضافی ایجاد شده است یا خیر. گاهی لازم است فایل‌ها را از پوشه داخلی خارج کرده و مستقیم در /plugins قرار دهید.
• نسخه افزونه را با نسخه ناپ کامرس خود مقایسه کنید. اگر نسخه افزونه برای نسخه ۴.۶۰ است و شما نسخه ۴.۸۰ را دارید، باید نسخه سازگار را دانلود کنید.
• روی دکمه Reload list of plugins کلیک کنید.

مشکل ۲: خطای ۵۰۰ هنگام نصب افزونه

دلایل احتمالی:

• مشکل در مجوزهای پوشه‌ها.
• عدم تطابق نسخه PHP یا کمبود حافظه (Memory Limit).
• وجود خطا در کد افزونه.

راه‌حل‌ها:

• مجوزهای پوشه‌های /plugins، /wwwroot و /App_Data را به ۷۵۵ یا ۷۷۷ تغییر دهید.
• در فایل web.config یا php.ini مقدار memory_limit را به ۲۵۶M یا بیشتر افزایش دهید.
• لاگ‌های سیستم را بررسی کنید تا خطای دقیق را مشاهده کنید. معمولاً خطا در فایل‌های لاگ با نام log.txt یا در بخش System > Log ثبت می‌شود.

مشکل ۳: افزونه نصب می‌شود اما فعال نمی‌شود

دلایل احتمالی:

• افزونه به یک افزونه وابسته (Dependency) نیاز دارد که نصب نشده است.
• لایسنس افزونه منقضی شده یا نامعتبر است.
• تداخل با سایر افزونه‌ها.

راه‌حل‌ها:

• مستندات افزونه را مطالعه کنید و از نصب افزونه‌های وابسته اطمینان حاصل کنید.
• اگر افزونه پولی است، کلید لایسنس را بررسی کنید و در صورت نیاز از فروشنده لایسنس جدید دریافت کنید.
• سایر افزونه‌ها را به صورت موقت غیرفعال کنید و سپس سعی کنید افزونه مورد نظر را فعال کنید. اگر مشکل برطرف شد، یعنی تداخل وجود دارد.

رفع مشکلات عملکردی و تنظیمات افزونه

گاهی افزونه نصب و فعال می‌شود اما به درستی کار نمی‌کند. در ادامه به رفع مشکل افزونه ناپ کامرس در این حالت می‌پردازیم.

مشکل ۴: تنظیمات افزونه ذخیره نمی‌شود

دلایل احتمالی:

• مشکل در اتصال به پایگاه داده.
• اعتبار اطلاعات وارد شده (مانند کلید API) نادرست است.
• مشکل در مجوزهای نوشتن در پایگاه داده.

راه‌حل‌ها:

• اتصال به پایگاه داده را بررسی کنید. اطمینان حاصل کنید که پایگاه داده در دسترس است.
• اطلاعات وارد شده را دقیقاً مطابق با مستندات افزونه بررسی کنید. برای مثال، کلید API را دوباره از سرویس‌دهنده دریافت کنید.
• مجوزهای کاربر پایگاه داده را بررسی کنید. کاربر باید مجوز INSERT، UPDATE و DELETE را داشته باشد.
• لاگ‌های سیستم را برای مشاهده خطای دقیق بررسی کنید.

مشکل ۵: افزونه باعث کندی فروشگاه می‌شود

دلایل احتمالی:

• افزونه درخواست‌های زیادی به پایگاه داده یا سرویس‌های خارجی ارسال می‌کند.
• کد افزونه بهینه نیست.
• منابع سرور (CPU، RAM) محدود است.

راه‌حل‌ها:

• تنظیمات کش افزونه را بررسی کنید و در صورت امکان کش را فعال کنید.
• از افزونه‌های به‌روز و معتبر استفاده کنید.
• منابع سرور را افزایش دهید یا از هاست با منابع بالاتر استفاده کنید.
• از ابزارهای تحلیل عملکرد مانند MiniProfiler برای شناسایی بخش‌های کند افزونه استفاده کنید.

مشکل ۶: تداخل افزونه با سایر افزونه‌ها

دلایل احتمالی:

• استفاده از توابع یا کلاس‌های مشابه.
• تغییر در همان بخش‌های سیستم (مانند پرداخت یا ارسال).

راه‌حل‌ها:

• سایر افزونه‌ها را به صورت موقت غیرفعال کنید و سپس افزونه مورد نظر را تست کنید. اگر مشکل برطرف شد، یعنی تداخل وجود دارد.
• با توسعه‌دهنده افزونه تماس بگیرید و مشکل را گزارش دهید.
• از افزونه‌های جایگزین استفاده کنید.

رفع مشکلات امنیتی و مجوزها

برخی خطاها به دلیل محدودیت‌های امنیتی یا مجوزهای نادرست رخ می‌دهند. در این بخش به رفع مشکل افزونه ناپ کامرس مربوط به امنیت می‌پردازیم.

مشکل ۷: خطای دسترسی (Access Denied)

دلایل احتمالی:

• نقش کاربر مجوز لازم برای مدیریت افزونه را ندارد.
• تنظیمات امنیتی سرور (مانند mod_security) مانع از دسترسی می‌شود.

راه‌حل‌ها:

• به بخش Configuration > Access control list (ACL) بروید و مطمئن شوید که نقش شما مجوز Manage plugins را دارد.
• اگر از سرور اختصاصی استفاده می‌کنید، تنظیمات mod_security را بررسی کنید و در صورت نیاز، برخی قوانین را غیرفعال کنید.

مشکل ۸: خطای لایسنس (License Error)

دلایل احتمالی:

• لایسنس منقضی شده است.
• لایسنس برای دامنه یا IP دیگری صادر شده است.
• لایسنس نامعتبر است.

راه‌حل‌ها:

• با فروشنده افزونه تماس بگیرید و لایسنس جدید دریافت کنید.
• اطمینان حاصل کنید که دامنه شما با دامنه ثبت شده در لایسنس مطابقت دارد.
• اگر از نسخه آزمایشی استفاده می‌کنید، تاریخ انقضا را بررسی کنید.

عیب‌یابی پیشرفته با استفاده از ابزارهای ناپ کامرس

ناپ کامرس ابزارهای قدرتمندی برای رفع مشکل افزونه ناپ کامرس در اختیار شما قرار می‌دهد. در ادامه به این ابزارها اشاره می‌کنیم.

استفاده از حالت DEBUG

با فعال کردن حالت DEBUG در فایل appsettings.json، می‌توانید خطاهای دقیق‌تری را مشاهده کنید. برای این کار:

• فایل appsettings.json را در ریشه پروژه باز کنید.
• مقدار EnableDebug را به true تغییر دهید.
• فروشگاه را مجدداً راه‌اندازی کنید.

با این کار، پیام‌های خطای دقیق‌تری در مرورگر نمایش داده می‌شود که به شما در رفع مشکل افزونه ناپ کامرس کمک می‌کند.

بررسی فایل‌های لاگ اختصاصی افزونه

برخی افزونه‌ها فایل‌های لاگ اختصاصی خود را در پوشه /App_Data/Logs یا پوشه خود افزونه ایجاد می‌کنند. این فایل‌ها را بررسی کنید تا اطلاعات بیشتری درباره خطا به دست آورید.

استفاده از ابزارهای شخص ثالث

ابزارهایی مانند Nop.Plugin.Misc.Metrics می‌توانند اطلاعات دقیقی درباره عملکرد افزونه‌ها و زمان اجرای آنها ارائه دهند. این ابزارها به شناسایی افزونه‌های کند یا مشکل‌دار کمک می‌کنند.

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

بهترین روش برای رفع مشکل افزونه ناپ کامرس، پیشگیری از بروز آنها است. با رعایت نکات زیر، می‌توانید از بسیاری از مشکلات جلوگیری کنید:

• همیشه از آخرین نسخه ناپ کامرس و افزونه‌ها استفاده کنید. به‌روزرسانی‌ها معمولاً باگ‌ها را برطرف می‌کنند.
• افزونه‌ها را فقط از منابع معتبر دانلود کنید. مارکت‌پلیس رسمی ناپ کامرس بهترین منبع است.
• پیش از نصب هر افزونه، از فروشگاه خود پشتیبان بگیرید. این کار به شما امکان می‌دهد در صورت بروز مشکل، به حالت قبلی بازگردید.
• تعداد افزونه‌ها را محدود کنید. هر چه تعداد افزونه‌ها بیشتر باشد، احتمال تداخل و کندی بیشتر می‌شود.
• مستندات افزونه را به دقت مطالعه کنید. بسیاری از مشکلات به دلیل عدم رعایت دستورالعمل‌های نصب و تنظیم رخ می‌دهند.
• از محیط تست (Staging) استفاده کنید. قبل از نصب هر افزونه در فروشگاه زنده، آن را در محیط تست امتحان کنید.

نتیجه‌گیری نهایی

رفع مشکل افزونه ناپ کامرس مهارتی ضروری برای هر مدیر فروشگاه اینترنتی است. با آشنایی با خطاهای رایج، استفاده از ابزارهای عیب‌یابی و رعایت اصول پیشگیری، می‌توانید به سرعت مشکلات را شناسایی و برطرف کنید. در این مقاله جامع، تمام مراحل عیب‌یابی از گام‌های اولیه تا راه‌حل‌های پیشرفته را پوشش دادیم. به یاد داشته باشید که همیشه می‌توانید از جامعه کاربران ناپ کامرس یا توسعه‌دهندگان افزونه‌ها برای دریافت کمک بیشتر استفاده کنید.

اگر با مشکل خاصی مواجه شده‌اید که در این مقاله به آن اشاره نشده، خوشحال می‌شویم در بخش نظرات به شما کمک کنیم. موفق و پیروز باشید!

توجه: این مقاله بر اساس تجربه کاربران حرفه‌ای و مستندات رسمی ناپ کامرس تهیه شده است. برای آخرین تغییرات، همواره به مستندات رسمی و انجمن‌های تخصصی مراجعه کنید.