Blog

You are currently viewing كودي شغال محلياً بس لا يشتغل على السيرفر — ليش وكيف أحل؟

كودي شغال محلياً بس لا يشتغل على السيرفر — ليش وكيف أحل؟

كودي شغال محلياً بس لا يشتغل على السيرفر
ليش وكيف أحل؟

دليل عملي للمطورين — الأسباب الحقيقية والحلول خطوة بخطوة

“يشتغل عندي!” — جملة سمعها كل مطور في حياته. تكتب الكود، تجرّبه محلياً ويشتغل بشكل مثالي، ثم ترفعه على السيرفر وكل شي ينهار. المشكلة مو في الكود نفسه في الغالب — بل في الفرق بين بيئة التطوير وبيئة الإنتاج. في هذا المقال نكشف أبرز الأسباب ونعطيك الحل لكل واحد.

جدول المقارنة بين البيئتين

العنصر محلياً (Local) السيرفر (Server)
نظام التشغيل Windows / macOS Linux غالباً
إصدار اللغة آخر إصدار عندك إصدار قديم أحياناً
المكتبات مثبّتة كلها قد تكون ناقصة
متغيرات البيئة في ملف .env تحتاج تُضاف يدوياً
الصلاحيات Admin كاملة مقيّدة في الغالب
قاعدة البيانات SQLite / محلية PostgreSQL / MySQL

الأسباب الحقيقية — مع الحل لكل سبب

١

متغيرات البيئة مفقودة على السيرفر

السبب الأكثر شيوعاً بفارق كبير. محلياً عندك ملف .env فيه كل شي — مفاتيح API، بيانات قاعدة البيانات، روابط الخدمات. لما ترفع الكود على السيرفر، هذا الملف ما يُرفع (وهذا صح لأسباب أمنية) — لكن الكود يبحث عنه ويفشل.

# محلياً يشتغل لأن .env موجود DB_HOST=localhost API_KEY=abc123 # على السيرفر — هذي المتغيرات غير موجودة! Error: DB_HOST is not defined
الحل: أضف كل متغيرات البيئة يدوياً على السيرفر. في Linux: export DB_HOST=your-db-host. على منصات مثل Heroku أو Railway: أضفها من لوحة التحكم تحت “Environment Variables”. وتأكد إنك ما ترفع ملف .env على GitHub أبداً.
٢

اختلاف إصدار اللغة أو المكتبات

عندك Node.js 20 محلياً، السيرفر عليه Node.js 16. أو عندك Python 3.11 وهم عندهم 3.8. تغييرات بسيطة في الإصدارات تكسر الكود بدون أي رسالة خطأ واضحة أحياناً.

# تحقق من الإصدار محلياً node –version # v20.11.0 python –version # Python 3.11.4 # على السيرفر node –version # v16.20.0 ← مختلف!
الحل: وثّق إصدار اللغة في ملف المشروع — في Node استخدم engines في package.json، وفي Python استخدم .python-version مع pyenv. والأفضل استخدم Docker لتحديد البيئة بدقة كاملة.
٣

مكتبات مثبّتة عندك بس غير موثّقة

ثبّت مكتبة عالمياً على جهازك (npm install -g something) ونسيت تضيفها لملف package.json. محلياً يشتغل لأنها موجودة — على السيرفر تفشل لأنها ما اتثبّتت.

# المشكلة — المكتبة مثبّتة عالمياً فقط Error: Cannot find module ‘some-package’ # الحل — تأكد إن كل شي في package.json npm install some-package –save pip freeze > requirements.txt
الحل: قبل ما ترفع أي كود، اعمل npm ci أو pip install -r requirements.txt في بيئة نظيفة وتأكد إن كل شي يشتغل. هذا يحاكي ما سيحدث على السيرفر بالضبط.
٤

اختلاف نظام التشغيل — Windows vs Linux

من أخفى المشاكل وأكثرها إرباكاً. Windows يتعامل مع مسارات الملفات بـ \ وLinux بـ /. وWindows غير حساس لحالة الأحرف في أسماء الملفات، بينما Linux حساس — Image.png وimage.png ملفان مختلفان!

// على Windows يشتغل require(‘./Components/Header’) // ✓ // على Linux Server يفشل! require(‘./components/header’) // ✓ لازم تطابق حالة الأحرف Error: Cannot find module ‘./Components/Header’
الحل: كن دقيقاً في أسماء الملفات والمجلدات من البداية. استخدم أسماء lowercase دايماً للمجلدات والملفات. وإذا تقدر، طوّر على Linux أو استخدم Docker.
٥

اختلاف قاعدة البيانات

تطوّر محلياً على SQLite لأنها سهلة ومو تحتاج إعداد، لكن السيرفر يستخدم PostgreSQL أو MySQL. بعض الاستعلامات تشتغل على SQLite لكن ترفض على PostgreSQL بسبب فروقات في الـ SQL syntax.

— يشتغل على SQLite SELECT strftime(‘%Y-%m-%d’, date_col) FROM orders; — يفشل على PostgreSQL! ERROR: function strftime does not exist — الصيغة الصحيحة في PostgreSQL SELECT to_char(date_col, ‘YYYY-MM-DD’) FROM orders;
الحل: استخدم نفس قاعدة البيانات في التطوير والإنتاج. إذا ستستخدم PostgreSQL على السيرفر، ثبّته محلياً كذلك. Docker يجعل هذا سهلاً جداً.
٦

صلاحيات الملفات والمجلدات

محلياً أنت Admin وتقدر تكتب في أي مكان. على السيرفر، المستخدم اللي يشغّل التطبيق قد ما يملك صلاحية الكتابة في بعض المجلدات — خصوصاً لما يحاول يكتب ملفات مؤقتة أو Logs.

# تحقق من صلاحيات المجلد على السيرفر ls -la /var/www/myapp/storage # أعطِ صلاحية الكتابة لمستخدم التطبيق chmod -R 775 /var/www/myapp/storage chown -R www-data:www-data /var/www/myapp
الحل: تأكد إن مستخدم السيرفر يملك صلاحية القراءة والكتابة على المجلدات اللي يحتاجها التطبيق. راجع رسائل الخطأ في الـ Server Logs لمعرفة أي مجلد يسبب المشكلة.

الحل الجذري — Docker

ليش Docker يحل المشكلة من جذورها؟
Docker يضع كودك مع كل بيئة تشغيله داخل “حاوية” — نفس نظام التشغيل، نفس الإصدارات، نفس المكتبات، في كل مكان. جهازك، جهاز زميلك، السيرفر — كلهم يشغّلون نفس الشي بالضبط.
١

أنشئ ملف Dockerfile في مشروعك

FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . EXPOSE 3000 CMD [“node”, “server.js”]
٢

أنشئ ملف docker-compose.yml لإدارة الخدمات

services: app: build: . ports: [“3000:3000”] env_file: .env db: image: postgres:15 environment: POSTGRES_DB: myapp
٣

شغّل المشروع بأمر واحد — محلياً وعلى السيرفر

docker compose up –build # نفس الأمر على جهازك أو السيرفر — نفس النتيجة
⚠️ قبل ترفع أي كود على السيرفر: تأكد من هذي القائمة — هل كل متغيرات البيئة موجودة على السيرفر؟ هل إصدار اللغة متطابق؟ هل كل المكتبات موثّقة في ملف التبعيات؟ هل أسماء الملفات بنفس حالة الأحرف؟

أسئلة شائعة

ليش الكود يشتغل محلياً ولا يشتغل على السيرفر؟

السبب الأكثر شيوعاً هو اختلاف البيئة — إصدار مختلف للغة، مكتبات ناقصة، أو متغيرات بيئة غير موجودة على السيرفر. راجع الأسباب الستة في المقال وطبّق الحلول بالترتيب.

كيف أعرف ليش فشل التطبيق على السيرفر؟

أول شي افتح الـ Server Logs — كل خطأ مكتوب هناك بالتفصيل. في Linux: journalctl -u myapp أو راجع ملفات الـ Logs في مجلد التطبيق. رسالة الخطأ ستدلّك مباشرة على السبب.

هل Docker ضروري لكل مشروع؟

مو ضروري لكل مشروع، لكنه الحل الأمثل للمشاريع الجدية. للمشاريع الصغيرة، يكفي توثيق إصدار اللغة والمكتبات بدقة ومزامنة متغيرات البيئة يدوياً.

هل أرفع ملف .env على GitHub؟

لا أبداً — ملف .env يحتوي بيانات حساسة مثل مفاتيح API وكلمات مرور قاعدة البيانات. أضفه لـ .gitignore فوراً. بدلاً من ذلك، أنشئ ملف .env.example يوضح المتغيرات المطلوبة بدون قيمها الحقيقية.

الخلاصة

مشكلة “يشتغل عندي بس مو على السيرفر” في 90% من الحالات سببها اختلاف البيئة — مو خطأ في الكود. ابدأ بفحص متغيرات البيئة، ثم إصدارات اللغة والمكتبات، ثم الفروقات بين الأنظمة. والحل الجذري اللي يوفّر عليك هذا الصداع كله هو Docker — بيئة واحدة تشتغل في كل مكان.

اترك تعليقاً