البيئة والخصائص

يحمّل Elide ملفات .env كقيم افتراضية لبيئة التطبيق، وملفات .properties كقيم افتراضية لخصائص نظام Java. لا يحتاج التطبيق إلى أي مكتبة dotenv. ويدعم التنسيقان القيم المشفّرة المتوافقة مع dotenvx.

تحميل الإعدادات

أنشئ .env في الدليل الذي تستدعي منه ⁦Elide:⁩

APP_NAME=greeter
APP_PORT=8080
APP_MESSAGE="Hello from ${APP_NAME}"

أنشئ app.ts:

console.log(process.env.APP_MESSAGE);
console.log(process.env.APP_PORT);

elide run app.ts

Hello from greeter
8080

لمتغير البيئة الموروث الأسبقية، حتى لو كانت قيمته فارغة:

APP_PORT=9090 elide run app.ts
APP_PORT= elide run app.ts

يتلقى الاستدعاء الثاني APP_PORT فارغًا بدلًا من 8080. اقرأ متغيرات البيئة عبر process.env، أو os.environ في Python، أو واجهة البيئة الخاصة بلغتك. تتلقى العمليات الفرعية البيئة الفعلية أيضًا. عندما تُرشِّح سياسة بيئة المتغيرات الموروثة، لا ترث عمليات Java المُطلقة ومهام المشروع وعمليات Node الفرعية إلا اللقطة المسموح بها. تُطبَّق إدخالات البيئة الصريحة للمهمة أو لـ JVM بعد ذلك؛ وتحلّ خريطة env صريحة لعملية Node فرعية محل الوراثة. لا يمنح تحميل الملفات قدرات إضافية في البيئة المعزولة ولا يوسّع وصول ملف البيان إلى البيئة؛ وتظل ضوابط --allow-env الحالية سارية.

الاكتشاف التلقائي للملفات

في كل دليل محدد، يقرأ Elide هذه الملفات بالترتيب:

تُتجاهل الملفات التلقائية المفقودة. أما الملفات الموجودة التي تتعذر قراءتها أو تحليلها فتسبب خطأ. التنسيقان منفصلان: متغير البيئة المسمى app.mode لا يضبط خاصية Java app.mode.

افتراضيًا، لا يفحص المشغّل إلا دليل الاستدعاء. ولا يغيّر موقع السكربت ذلك الدليل. تشغيل elide run services/api/app.ts لا يحدد services/api/.env تلقائيًا.

مع --project PATH، يحدد Elide دليل المشروع ذاك، أو الدليل الأب عندما يشير PATH إلى ملف البيان الخاص به. يحمّل أولًا الأدلة المحيطة التي تحتوي على elide.pkl، من الأبعد إلى الأقرب، ثم الدليل المحدد. وفي كل دليل، يأتي الملف المحلي بعد الملف الأساسي. والأدلة اللاحقة تتجاوز السابقة. لا تساهم الأدلة الأسلاف العشوائية ولا الدليل المنزلي ولا أعضاء مساحة العمل غير المرتبطين في إعدادات المشغّل.

elide --project services/api run app.ts

تستخدم مهام المشروع أيضًا طبقات البيئة المحيطة وطبقة مساحة العمل وطبقة العضو. حدّد المشروع صراحةً عندما يجب أن تكون إعداداته المحيطة متاحة عند البدء. راجع إعداد المشروع.

لا يحدد Elide تلقائيًا .env.production أو .env.test أو .properties.production أو أسماء مشابهة. ولا تحدد NODE_ENV ولا ملفات تعريف التنفيذ المسماة ولا ملفات تعريف dotenvx ملفات الإعداد. اختر هذه الملفات صراحةً.

اختيار الملفات صراحةً

يحل --env-file محل الاكتشاف التلقائي لملفات dotenv. ويحل --properties-file بشكل مستقل محل الاكتشاف التلقائي لملفات الخصائص. كرّر أيًّا من الخيارين لتكديس الملفات؛ وعند تكرار الأسماء تفوز الوسائط اللاحقة. المسارات نسبية إلى دليل الاستدعاء، حتى عند تمرير --project.

elide --env-file .env --env-file .env.production run app.ts
elide --properties-file config/base.properties --properties-file config/production.properties run Main.java
elide --env-file config/service.env --properties-file config/service.properties run Main.java

الملفات الصريحة إلزامية: الملف المفقود خطأ. اختيار .env.production وحده لا يحمّل معه .env أو .env.local. أدرج كل ملف تريده.

elide --no-env --no-properties run app.ts

الجمع بين --no-env و --env-file، أو بين --no-properties و --properties-file، خطأ في الاستخدام. يمكنك تعطيل تنسيق مع اختيار ملفات للتنسيق الآخر صراحةً.

تحترم عمليات تشغيل ملفات مصدر Java المستقلة أيضًا اختيارات الملفات الصريحة و --no-env و --no-properties دون إعادة اكتشاف الملفات التلقائية.

الأسبقية

أسبقية البيئة، من الأدنى إلى الأعلى:

1. ملفات dotenv المحددة، بترتيب الاكتشاف أو الوسائط.
2. بيئة العملية الموروثة، بما فيها القيم الفارغة.
3. تعيينات البيئة الصريحة لمهمة أو عملية فرعية معينة، ضمن نطاق ذلك التنفيذ.

أسبقية خصائص Java، من الأدنى إلى الأعلى:

1. ملفات الخصائص المحددة، بترتيب الاكتشاف أو الوسائط.
2. تعيينات JVM بـ -D التي يمررها المشغِّل عندما يعمل Elide على JVM موجودة.
3. تعيينات الخصائص الصريحة في واجهة سطر أوامر Elide، مثل --vm app.mode=production.

القيم الافتراضية للخصائص التي توفرها VM لا تُعد تعيينات من المشغِّل. تتلقى التطبيقات الخصائص قبل تهيئتها. وتتلقى عمليات تشغيل Java الفرعية القيم الافتراضية لخصائص التطبيق قبل وسائط JVM الصريحة الخاصة بها. تعمل المهمة ذات خصائص VM المختلفة في VM منفصلة؛ ولا تغيّر خصائصها الحالة العامة لمحرّك البناء.

صياغة dotenv

تدعم ملفات dotenv التعليقات، والقيم بين علامات الاقتباس، والقيم متعددة الأسطر، والقيم الفارغة، والاستيفاء ${NAME}. تحافظ علامات الاقتباس المفردة على المحتوى حرفيًا. وتسمح علامات الاقتباس المزدوجة بالاستيفاء.

# Application defaults
APP_NAME=greeter
APP_MESSAGE="Hello from ${APP_NAME}"
APP_LITERAL='${APP_NAME}'
APP_EMPTY=
APP_MULTILINE="first line
second line"
APP_COMMAND='$(echo hello)'

APP_LITERAL هي السلسلة الحرفية ${APP_NAME}. و APP_COMMAND هي السلسلة الحرفية $(echo hello)؛ لا ينفّذ Elide استبدالات أوامر الصدفة في ملفات الإعداد.

يحدث الاستيفاء أثناء تحليل كل ملف. ويمكنه استخدام المتغيرات الموروثة والتعيينات السابقة في الملف نفسه. ولا يُعاد تشغيله بعد أن تتجاوز ملفات لاحقة القيم. إذا عرّف .env القيمتين APP_NAME=greeter و APP_MESSAGE="Hello from ${APP_NAME}"، ثم غيّر .env.local القيمة APP_NAME إلى api، فستبقى الرسالة Hello from greeter. لا تعتمد على الاستيفاء عبر ملفات منفصلة.

خصائص Java

لتطبيقات Java أو Kotlin، أنشئ .properties:

app.name=greeter
app.message=Hello world
app.empty=
app.multiline=first\
  second
app.unicode=\u263A
app.literal=${APP_NAME}

اقرأها باستخدام System.getProperty("app.name") في Java أو Kotlin. على سبيل المثال، احفظ Main.java:

class Main {
  public static void main(String[] args) {
    System.out.println(System.getProperty("app.message"));
  }
}

elide run Main.java
elide --vm app.message="Hello from the CLI" run Main.java

يطبع الاستدعاء الأول Hello world؛ ويطبع الثاني Hello from the CLI. قيمة app.multiline هي firstsecond؛ وقيمة app.unicode هي ☺؛ وتبقى app.literal بالقيمة ${APP_NAME}.

تستخدم الخصائص صياغة ⁦Java:⁩ تعليقات # و !، والفواصل المهرَّبة، وأسطر الاستمرار، وتهريبات \uXXXX. علامات الاقتباس جزء من القيمة، وليست اقتباس dotenv. لا تستوفي الخصائص تعابير dotenv ولا تنفّذ أوامر. للمحتوى غير ASCII القابل للنقل، استخدم تهريبات Unicode؛ إذ يفك قارئ الخصائص ترميز البايتات بترميز Windows-1252.

يجب ألا تكون أسماء الخصائص فارغة وألا تحتوي على NUL أو =. يمكن أن تحتوي القيم على = لكن ليس على NUL. نطاقات أسماء الخصائص java.* و elide* و org.graalvm* مقيّدة، باستثناء elide.diag.*. لا يتجاوز التشفير هذه القيود. وتتبع إعدادات polyglot.* مسار خيارات المحرّك. استخدم خيارات VM في واجهة سطر الأوامر لإعدادات مثل حجم الذاكرة المكدسة (heap)؛ فملف الخصائص ليس ملف وسائط JVM.

عندما يعمل Elide على JVM بدأت بالفعل، يوفّر تحميل الملفات طبقات بيئة للتطبيقات والعمليات الفرعية. ولا يعيد كتابة System.getenv() في تلك JVM ولا يغيّر إعدادات بدئها بأثر رجعي.

القيم المشفّرة

يفك Elide تشفير قيم encrypted: المتوافقة مع dotenvx في ملفات dotenv وخصائص Java. يمكن أن تظهر القيم النصية الصريحة والمشفّرة في الملف نفسه، وتتبع قواعد الأسبقية نفسها. القيمة المشفّرة التي تحل محلها قيمة صريحة لاحقة، أو قيمة بيئة موروثة، لا تحتاج إلى مفتاح فك تشفير.

استخدم أداة تشفير متوافقة لإنشاء النص المشفّر. يتولى Elide فك التشفير عند تحميل الإعدادات؛ ولا يوفّر أمر تشفير. على سبيل المثال، مع تثبيت ⁦dotenvx:⁩

dotenvx encrypt -f .env.production
elide --env-file .env.production run app.ts

اختر تخزين .env.keys المحلي في dotenvx عند السؤال. يحتفظ مسار التشفير الخاص به بالنص المشفّر في ملف dotenv المحدد ويكتب المفتاح الخاص في .env.keys. بالنسبة إلى .env.production، يُسمى المفتاح DOTENV_PRIVATE_KEY_PRODUCTION. لا يزال Elide يتطلب --env-file .env.production؛ فلاحقة المفتاح لا تحدد الملف.

توفير المفاتيح الخاصة

يقبل Elide المتغيرات الموروثة DOTENV_PRIVATE_KEY و DOTENV_PRIVATE_KEY_* ذات اللاحقة، أو المفاتيح في .env.keys بجوار مصادر الإعداد المحددة. وتتشارك البيئة والخصائص البحث نفسه عن المفاتيح.

1. يفحص Elide .env.keys بجوار مصادر dotenv المحددة، ثم بجوار مصادر الخصائص المحددة، بترتيب المصادر. يُفحص كل دليل مرة واحدة؛ وتحل التعيينات اللاحقة في ملفات المفاتيح محل السابقة التي تحمل الاسم نفسه.
2. تتجاوز تعيينات DOTENV_PRIVATE_KEY* الموروثة الأسماء المطابقة من ملفات المفاتيح.
3. تُجرَّب المفاتيح المتاحة على القيم المشفّرة الفعلية. ولا تقصر لاحقة المفتاح فك التشفير على اسم ملف إعداد معين.

لا تُقرأ ملفات المفاتيح إلا عندما تحتاج قيمة مشفّرة فعلية إلى فك التشفير. والتشغيل بقيم صريحة فقط لا يتطلب .env.keys. ولا يبحث العثور على المفاتيح في الأدلة الأسلاف العشوائية ولا في دليلك المنزلي.

في CI، احقن متغير المفتاح الخاص المطابق عبر مخزن أسرار CI، ثم شغّل Elide كالمعتاد:

# DOTENV_PRIVATE_KEY_PRODUCTION is supplied by the CI environment.
elide --env-file .env.production run app.ts

أبقِ .env.keys خارج التحكم بالإصدارات، واحتفظ بنسخة احتياطية منه بشكل منفصل، وقيّد الوصول إلى الملف. راجع الإعدادات قبل حفظها في المستودع: تشفير بعض القيم لا يعني أن كل القيم مشفّرة. تجنّب طباعة أسرار التطبيق أو تمرير المفاتيح الخاصة حرفيًا في أوامر الصدفة والسجلات.

تُستخدم إدخالات .env.keys لفك التشفير فقط؛ ولا تُضاف إلى إعدادات التطبيق. إدخالات DOTENV_PUBLIC_KEY* في ملفات الإعداد بيانات وصفية وتُحذف من قيم التطبيق المحمّلة. وضع تعيينات DOTENV_PRIVATE_KEY* في ملف dotenv أو ملف خصائص للتطبيق خطأ. تظل متغيرات المفاتيح الخاصة الموروثة خاضعة لقواعد الظهور المعتادة للبيئة الموروثة.

خصائص Java المشفّرة

يمكن أن تحتوي خاصية Java على قيمة نص مشفّر متوافقة دون علامات اقتباس:

app.secret=encrypted:...

علامة الحذف عنصر نائب للنص المشفّر الفعلي، وليست قيمة مشفّرة صالحة. يحلل Elide خصائص Java أولًا، ثم يفك تشفير القيمة المفكوكة الترميز بالمفاتيح نفسها المستخدمة مع dotenv. لا تفترض أن واجهة سطر أوامر dotenvx تستطيع تحليل ملفات خصائص Java أو إعادة كتابتها. يُستخدم النص المفكوك التشفير كقيمة: لا يُعاد تحليله كإعدادات، ولا يُستوفى، ولا يُنفَّذ.

الأوامر والاختبارات والأخطاء

ينطبق التحميل التلقائي على run و serve و dev و install و build و test و project و classpath و publish و java و python و repl والتنفيذ المباشر للملفات. تتخطى أوامر المساعدة والإصدار والإكمال التلقائي والأوامر الإدارية غير المرتبطة الاكتشاف التلقائي للإعدادات. ولا تحمّل أوامر الأدوات مثل javac و kotlinc هذه الملفات تلقائيًا. وتطلب خيارات الملفات الصريحة تحميل الإعدادات في الأوامر التي تصل إلى مشغّل التطبيق.

للاختبارات القابلة لإعادة الإنتاج، اختر الملفات صراحةً أو عطّل التنسيقين كليهما:

elide --env-file .env.test --no-properties test
elide --no-env --no-properties test

لا تمسح هذه الخيارات متغيرات البيئة الموروثة. اضبطها أو أزلها بشكل منفصل في مشغّل الاختبارات. يحتفظ الاستدعاء المحلول بلقطة إعداداته؛ ابدأ استدعاءً جديدًا لالتقاط الملفات أو المفاتيح المعدّلة.

تفشل الملفات المحددة غير القابلة للقراءة، والصياغة المشوّهة، والإدخالات المحظورة، والمفاتيح غير الصالحة، والقيم الفعلية التي يتعذر فك تشفيرها، قبل تنفيذ التطبيق أو المهمة المعنية. تُبلغ رسائل التشخيص عن فئة الخطأ ومسار المصدر دون طباعة أسطر المصدر أو القيم أو النص المشفّر أو المفاتيح الخاصة. أصلح المصدر المُبلَّغ عنه أو عطّل تنسيقه صراحةً. ولا تُنشر أي إعدادات محلولة جزئيًا من تنسيق فشل.

للمتغيرات التي تضبط Elide نفسه، راجع متغيرات بيئة التشغيل. ولتفاصيل الخيارات، راجع مرجع سطر الأوامر.