بيئة اختبار مستقرة

# Sandbox SDK — حزمة مستقرة

بيئات Linux معزولة على [Cloudflare Containers](https://developers.cloudflare.com/containers/index.md)، مدفوعة من Workers.

**فضل وثائق Sandbox الرئيسية والأنواع المستقرة المثبتة على الذاكرة.** هذه المهارة هي بوابة وعقد وخريطة استرجاع — وليست دليلا كاملا.

هذا السطر هو حزمة npm الافتراضية **المستقرة الحالية**. تصفها [وثائق Sandbox](https://developers.cloudflare.com/sandbox/index.md) الرئيسية. يمكن للتطبيقات الحالية البقاء هنا ومواصلة العمل.

نوصي **بالمشاريع الجديدة** على `@cloudflare/sandbox@next` مع **`sandbox-next`**. عندما تتمكن، خطط للانتقال باستخدام **`sandbox-migrate-to-next`** لتكون جاهزا عندما يصبح الإصدار 1.0 هو الإصدار المستقر. لا تفرض هذا النقل إلا إذا طلب المستخدم ذلك.

## 1. البوابة — تأكيد خط الحزمة

قبل كتابة الكود، افحص التطبيق:

| التحقق | يجب أن يتطابق | | ----- | ---------- | | تبعية npm | الافتراضي `@cloudflare/sandbox` (**ليس** `@next` / علامات المعاينة) | | صورة الحاوية | صورة **مستقرة** مطابقة (ليست `cloudflare/sandbox:next`) |

| إذا وجدت… | الإجراء | | ------------ | ------ | | `@cloudflare/sandbox@next` أو صورة `next` | **توقف.** قم بتحميل **`sandbox-next`**. | | المستخدم يريد النقل إلى 1.0 / `@next` | **توقف.** قم بتحميل **`sandbox-migrate-to-next`**. لا تطبق واجهات برمجة التطبيقات التجريبية جزئيا على حزمة مستقرة. | | تنظيف واجهات برمجة التطبيقات المستقرة المهملة فقط | ابق هنا؛ استخدم [دليل الإهمال لعام 2026](https://developers.cloudflare.com/sandbox/sdk/migrate/index.md). هذا **ليس** انتقالا إلى `@next`. |

لا تخلط أبدا حزمة Worker مستقرة مع صورة حاوية `@next` (أو العكس).

تثبيت المهارات: [إعداد Agent](https://developers.cloudflare.com/agent-setup/index.md) · [cloudflare/skills](https://github.com/cloudflare/skills)

## 2. العقد — غير قابل للتفاوض

- `await sandbox.exec(command)` يأخذ **سلسلة أمر** ويحل عندما **ينتهي** الأمر، مع `stdout` / `stderr` / `exitCode` المخزنة مؤقتا (والحقول ذات الصلة). - تستخدم المهام طويلة الأمد والتدفقية واجهات برمجة تطبيقات الأوامر **المستقرة** (`startProcess`, `execStream`, والمساعدات ذات الصلة) — وليس نموذج التعامل الفردي `@next`. افتح وثائق الأوامر؛ لا تخترع معالجات `output()` ل `@next` على الإصدار المستقر. - يمكن **للجلسات** الحفاظ على دليل العمل والبيئة عبر الأوامر (الجلسة الافتراضية / `enableDefaultSession`, `createSession`). راجع وثائق الجلسات عندما يجب أن تنتقل الحالة عبر الاستدعاءات. - غالبا ما تستخدم محطات المتصفح التفاعلية **`sandbox.terminal(request)`** ومساعدات الجلسة/xterm على الإصدار المستقر — وليس معاينة `createTerminal` ما لم تكن الحزمة `@next`. - فضل نقل **RPC** عند استخدام الأنفاق أو التدفقات الكبيرة/الثنائية. تم إهمال نقل HTTP/WebSocket (دليل التنظيف أدناه). - الملفات، نقاط التحميل، المنافذ، الأنفاق، النسخ الاحتياطية، دورة الحياة، والمترجم: استخدم الوثائق الرئيسية للتوقيعات؛ ثق بالأنواع **المستقرة** المثبتة. - التكوين غير السري في بيئة Sandbox؛ بيانات الاعتماد الحية في Worker. استخدم معالجات الصادر عندما تستدعي العمليات واجهات برمجة تطبيقات خارجية. - تتطلب أسماء مضيفات معاينة الإنتاج DNS من نوع wildcard على نطاق مخصص عند استخدام أنماط URL هذه. - **لا** تطبق واجهات برمجة تطبيقات `@next` argv/`process.output()` بينما لا تزال التبعية مستقرة. - يبقى **الجسر** المنشور ذاتيا على الحزمة والصورة المستقرة. [الجسر](https://developers.cloudflare.com/sandbox/sdk/bridge/index.md)

الشكل الأدنى:

```ts import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123"); const result = await sandbox.exec('python3 -c "print(2 + 2)"'); // result.stdout, result.exitCode, result.success ```

## 3. الاسترجاع — افتح الوثيقة للمهمة

احضر الصفحة قبل التنفيذ. الأنواع المستقرة المثبتة تتفوق على التخمينات.

| تحتاج إلى… | افتح | | ------------ | ---- | | التوجيه | [نظرة عامة على Sandbox](https://developers.cloudflare.com/sandbox/index.md) | | أول Worker، قالب، Docker | [البدء](https://developers.cloudflare.com/sandbox/get-started/index.md) | | `exec`، التدفق، العمليات الخلفية | [واجهة برمجة تطبيقات الأوامر](https://developers.cloudflare.com/sandbox/sdk/api/commands/index.md) · [تنفيذ الأوامر](https://developers.cloudflare.com/sandbox/sdk/guides/execute-commands/index.md) · [العمليات الخلفية](https://developers.cloudflare.com/sandbox/sdk/guides/background-processes/index.md) · [تدفق الإخراج](https://developers.cloudflare.com/sandbox/sdk/guides/streaming-output/index.md) | | الجلسات / حالة shell عبر الأوامر | [مفهوم الجلسات](https://developers.cloudflare.com/sandbox/sdk/concepts/sessions/index.md) · [واجهة برمجة تطبيقات الجلسات](https://developers.cloudflare.com/sandbox/sdk/api/sessions/index.md) | | خيارات `getSandbox`، النوم، التدمير | [واجهة برمجة تطبيقات دورة الحياة](https://developers.cloudflare.com/sandbox/sdk/api/lifecycle/index.md) · [خيارات Sandbox](https://developers.cloudflare.com/sandbox/sdk/configuration/sandbox-options/index.md) | | متغيرات البيئة | [متغيرات البيئة](https://developers.cloudflare.com/sandbox/sdk/configuration/environment-variables/index.md) | | الملفات | [واجهة برمجة تطبيقات الملفات](https://d