متغيّرات البيئة

تتيح لك متغيّرات البيئة ضبط واجهتك دون تضمين القيم في كود المصدر. استخدمها لعناوين URL للـ API والمفاتيح العامة (Stripe القابل للنشر و Google Maps وغيرها) وأعلام الميزات وأي شيء يتغيّر بين المشاريع أو البيئات.

صفحة Variables (Ship → Frontend → Variables، المسار /variables) لها تبويبان:

Backend Secrets (التبويب الافتراضي) — أسرار تشغيل مشفّرة يُشار إليها بالاسم في endpoints وسير العمل. لا تُشحن إلى المتصفح أبداً. راجع أسرار الخلفية.
Frontend (Build) — متغيّرات البيئة العامة وقت البناء في هذه الصفحة، تُدمَج في حزمة العميل.

متغيّرات Frontend (Build) عامة

تُدمَج متغيّرات بيئة Frontend (Build) في بناؤك وتُشحن إلى المتصفح. لا تضع أسراراً هنا أبداً — لا مفاتيح API خاصة ولا بيانات اعتماد قاعدة بيانات ولا أسرار JWT. لأسرار وقت التشغيل استخدم أسرار الخلفية؛ للمفاتيح المكتوبة الأنواع للأطراف الثالثة استخدم بيانات الاعتماد.

إضافة متغيّرات

افتح تبويب Variables

في لوحة تحكم مشروعك، اذهب إلى Frontend → Variables وانتقل إلى تبويب Frontend (Build).

أضف أزواج مفتاح-قيمة

انقر Add variable. أدخل المفتاح (مثلاً VITE_STRIPE_KEY) والقيمة. تتطلب معظم الأطر بادئة محددة — راجع الجدول أدناه.

أعد النشر

تُدمَج متغيّرات البيئة وقت البناء. انقر Redeploy (أو شغّل نشراً جديداً من بيئة التطوير) لتطبيق التغييرات.

البادئة المطلوبة حسب الإطار

يكشف إطارك فقط متغيّرات البيئة ذات بادئة محددة للمتصفح. هذا يمنع تسرّب متغيّرات الخلفية بالخطأ.

Parameter	Type	Description
`Vite / Vue / SvelteKit`	`VITE_*`	يُوصَل إليها كـ import.meta.env.VITE_MY_KEY في كودك
`Create React App`	`REACT_APP_*`	يُوصَل إليها كـ process.env.REACT_APP_MY_KEY
`Next.js (client)`	`NEXT_PUBLIC_*`	يُوصَل إليها كـ process.env.NEXT_PUBLIC_MY_KEY
`Astro`	`PUBLIC_*`	يُوصَل إليها كـ import.meta.env.PUBLIC_MY_KEY

المتغيّرات دون البادئة الصحيحة لا تُضمَّن في البناء — ستكون undefined في المتصفح.

المتغيّرات التلقائية

تضبط HeroMate بضعة متغيّرات لك تلقائياً. لا تحتاج إضافتها يدوياً:

المتغيّر	القيمة
`VITE_DYPAI_URL`	عنوان URL الأساسي لـ API مشروعك
`VITE_DYPAI_PROJECT_ID`	UUID مشروعك

يقرأ @dypai-ai/client-sdk هذه تلقائياً عندما تستدعي createClient().

إعداد نموذجي

JavaScript

# API endpoints and public keys
VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
VITE_GOOGLE_MAPS_KEY=AIza...
VITE_POSTHOG_KEY=phc_...

# Feature flags
VITE_ENABLE_BETA_DASHBOARD=true

# Third-party URLs
VITE_SUPPORT_URL=https://help.yourapp.com

ثم في كودك:

JavaScript

const stripeKey = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY
const mapsKey = import.meta.env.VITE_GOOGLE_MAPS_KEY

تعديل المتغيّرات أو حذفها

تعديل: انقر أيقونة القلم بجانب متغيّر، غيّر القيمة، احفظ. أعد النشر للتطبيق.
حذف: انقر أيقونة سلة المهملات. يُزال المتغيّر في النشر التالي.

ثلاثة أماكن للإعداد

لدى HeroMate ثلاثة مخازن متميزة. اختر المناسب لكل قيمة:

المخزن	أين	الرؤية	استخدمه لـ
متغيّرات Frontend (Build)	Frontend → Variables → Frontend (Build)	عامة — تُدمَج في حزمة المتصفح	عنوان URL الأساسي للـ API ومفاتيح عامة (`pk_`) وأعلام ميزات
Backend Secrets	Frontend → Variables → Backend Secrets	خاصة — مشفّرة، لا تُشحن إلى المتصفح أبداً	أسرار تشغيل بالاسم، تُقرأ في endpoints كـ `ctx.secrets.X` / `${ secrets.X }`
Credentials	Build → Credentials	خاصة — مشفّرة ومكتوبة الأنواع	مفاتيح مزوّدي الأطراف الثالثة (Stripe `sk_` و OpenAI و Slack…) التي تستخدمها عقد التكامل

عقدة Code تستخدم env_vars لا Credentials

تقرأ عقدة سير العمل javascript_code env_vars النص العادي الخاصة بها عبر ctx.env — لا يمكنها اختيار Credentials مكتوبة الأنواع. للقيم الحساسة وقت التشغيل، فضّل أسرار الخلفية.

الحدود

يجب أن تكون المفاتيح UPPER_SNAKE_CASE
قيم Frontend (Build) مكشوفة في حزمة العميل وقت البناء — لا تضع أسراراً هنا أبداً
أسرار الخلفية مشفّرة بـ Fernet وللكتابة فقط ولا تُشحن إلى المتصفح أبداً — استخدمها لأي شيء حسّاس

أين لا تستخدم متغيّرات البيئة

نوع القيمة	ضعها في…
مفتاح API عام (Stripe pk_ و Google Maps و PostHog)	✅ متغيّر Frontend (Build)
عنوان URL الأساسي للـ API	✅ متغيّر Frontend (Build)
علم ميزة	✅ متغيّر Frontend (Build)
مفتاح Stripe السري (sk_)	❌ بيانات الاعتماد
سر تشغيل عام (مفتاح توقيع webhook أو رمز داخلي)	❌ أسرار الخلفية
كلمة مرور قاعدة البيانات	❌ غير مطلوبة أبداً — تتولى HeroMate هذا
مفتاح OpenAI API	❌ بيانات الاعتماد (تستخدمها عقدة Agent)
سر توقيع JWT	❌ غير مطلوب أبداً — تتولى HeroMate هذا

الخطوات التالية

أسرار الخلفية

أسرار تشغيل مشفّرة تقرأها endpoints بالاسم.

بيانات الاعتماد

مفاتيح مزوّدين مكتوبة الأنواع لعقد التكامل.

النطاقات المخصصة

اربط نطاقك (Pro).

متغيّرات البيئة

صفحة Variables (Ship → Frontend → Variables، المسار /variables) لها تبويبان:

Backend Secrets (التبويب الافتراضي) — أسرار تشغيل مشفّرة يُشار إليها بالاسم في endpoints وسير العمل. لا تُشحن إلى المتصفح أبداً. راجع أسرار الخلفية.
Frontend (Build) — متغيّرات البيئة العامة وقت البناء في هذه الصفحة، تُدمَج في حزمة العميل.

متغيّرات Frontend (Build) عامة

إضافة متغيّرات

افتح تبويب Variables

في لوحة تحكم مشروعك، اذهب إلى Frontend → Variables وانتقل إلى تبويب Frontend (Build).

أضف أزواج مفتاح-قيمة

انقر Add variable. أدخل المفتاح (مثلاً VITE_STRIPE_KEY) والقيمة. تتطلب معظم الأطر بادئة محددة — راجع الجدول أدناه.

أعد النشر

تُدمَج متغيّرات البيئة وقت البناء. انقر Redeploy (أو شغّل نشراً جديداً من بيئة التطوير) لتطبيق التغييرات.

البادئة المطلوبة حسب الإطار

يكشف إطارك فقط متغيّرات البيئة ذات بادئة محددة للمتصفح. هذا يمنع تسرّب متغيّرات الخلفية بالخطأ.

Parameter	Type	Description
`Vite / Vue / SvelteKit`	`VITE_*`	يُوصَل إليها كـ import.meta.env.VITE_MY_KEY في كودك
`Create React App`	`REACT_APP_*`	يُوصَل إليها كـ process.env.REACT_APP_MY_KEY
`Next.js (client)`	`NEXT_PUBLIC_*`	يُوصَل إليها كـ process.env.NEXT_PUBLIC_MY_KEY
`Astro`	`PUBLIC_*`	يُوصَل إليها كـ import.meta.env.PUBLIC_MY_KEY

المتغيّرات دون البادئة الصحيحة لا تُضمَّن في البناء — ستكون undefined في المتصفح.

المتغيّرات التلقائية

تضبط HeroMate بضعة متغيّرات لك تلقائياً. لا تحتاج إضافتها يدوياً:

المتغيّر	القيمة
`VITE_DYPAI_URL`	عنوان URL الأساسي لـ API مشروعك
`VITE_DYPAI_PROJECT_ID`	UUID مشروعك

يقرأ @dypai-ai/client-sdk هذه تلقائياً عندما تستدعي createClient().

إعداد نموذجي

JavaScript

# API endpoints and public keys
VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
VITE_GOOGLE_MAPS_KEY=AIza...
VITE_POSTHOG_KEY=phc_...

# Feature flags
VITE_ENABLE_BETA_DASHBOARD=true

# Third-party URLs
VITE_SUPPORT_URL=https://help.yourapp.com

ثم في كودك:

JavaScript

const stripeKey = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY
const mapsKey = import.meta.env.VITE_GOOGLE_MAPS_KEY

تعديل المتغيّرات أو حذفها

تعديل: انقر أيقونة القلم بجانب متغيّر، غيّر القيمة، احفظ. أعد النشر للتطبيق.
حذف: انقر أيقونة سلة المهملات. يُزال المتغيّر في النشر التالي.

ثلاثة أماكن للإعداد

لدى HeroMate ثلاثة مخازن متميزة. اختر المناسب لكل قيمة:

المخزن	أين	الرؤية	استخدمه لـ
متغيّرات Frontend (Build)	Frontend → Variables → Frontend (Build)	عامة — تُدمَج في حزمة المتصفح	عنوان URL الأساسي للـ API ومفاتيح عامة (`pk_`) وأعلام ميزات
Backend Secrets	Frontend → Variables → Backend Secrets	خاصة — مشفّرة، لا تُشحن إلى المتصفح أبداً	أسرار تشغيل بالاسم، تُقرأ في endpoints كـ `ctx.secrets.X` / `${ secrets.X }`
Credentials	Build → Credentials	خاصة — مشفّرة ومكتوبة الأنواع	مفاتيح مزوّدي الأطراف الثالثة (Stripe `sk_` و OpenAI و Slack…) التي تستخدمها عقد التكامل

عقدة Code تستخدم env_vars لا Credentials

الحدود

يجب أن تكون المفاتيح UPPER_SNAKE_CASE
قيم Frontend (Build) مكشوفة في حزمة العميل وقت البناء — لا تضع أسراراً هنا أبداً
أسرار الخلفية مشفّرة بـ Fernet وللكتابة فقط ولا تُشحن إلى المتصفح أبداً — استخدمها لأي شيء حسّاس

أين لا تستخدم متغيّرات البيئة

نوع القيمة	ضعها في…
مفتاح API عام (Stripe pk_ و Google Maps و PostHog)	✅ متغيّر Frontend (Build)
عنوان URL الأساسي للـ API	✅ متغيّر Frontend (Build)
علم ميزة	✅ متغيّر Frontend (Build)
مفتاح Stripe السري (sk_)	❌ بيانات الاعتماد
سر تشغيل عام (مفتاح توقيع webhook أو رمز داخلي)	❌ أسرار الخلفية
كلمة مرور قاعدة البيانات	❌ غير مطلوبة أبداً — تتولى HeroMate هذا
مفتاح OpenAI API	❌ بيانات الاعتماد (تستخدمها عقدة Agent)
سر توقيع JWT	❌ غير مطلوب أبداً — تتولى HeroMate هذا

الخطوات التالية

أسرار الخلفية

أسرار تشغيل مشفّرة تقرأها endpoints بالاسم.

بيانات الاعتماد

مفاتيح مزوّدين مكتوبة الأنواع لعقد التكامل.

النطاقات المخصصة

اربط نطاقك (Pro).