فحص الثيم
كل قاعدة يطبّقها theme check بنص خطئها الحرفي، والحدود، والفحص البعيد، وملاحظة تأخّر المدقّق، ووصفة CI.
في هذه الصفحة
هذه الصفحة مرجع لمن قابل رسالة ✗ من theme check أو من الدفع. المدقّق الذي يشغّله theme check محلياً هو الملف نفسه الذي يشغّله الخادم عند الدفع، فالقواعد هنا تنطبق في المكانين حرفياً.
كيف يُبلَّغ#
✗ templates/home.liquid: <script> is not allowed (themes ship no JavaScript; JSON-LD data blocks are the only exception)
✗ disallowed file extension: assets/app.js
2 error(s) block pushing. Fix them, then run `dukkan theme check` again. https://developer.dukkan.one/docs/themes/checkعند النجاح:
✓ Bundle valid — 14 files, hash 3f9a1c2b7d4e…يعيد الأمر رمز الخروج 1 عند أي خطأ و0 عند النجاح. الملفات والمجلدات التي تبدأ بنقطة وnode_modules تُتجاوز بصمت؛ الروابط الرمزية تُتجاوز مع تحذير ! skipped PATH (symlink).
قواعد المسارات#
| الخطأ | السبب |
|---|---|
bundle is empty |
لا ملفات |
bundle has too many files (N) |
أكثر من 400 ملف |
path length out of range: "…" |
مسار فارغ أو أطول من 200 حرف |
absolute path not allowed: PATH |
يبدأ بـ / |
backslash not allowed: PATH |
يحوي \ |
NUL byte in path |
يحوي بايت صفري |
path traversal / empty segment not allowed: PATH |
يحوي .. أو . أو مقطعاً فارغاً |
dotfiles not allowed: PATH |
مقطع يبدأ بنقطة |
disallowed file extension: PATH |
امتداد خارج القائمة: .liquid .json .css .svg .png .jpg .jpeg .webp .woff2 |
قواعد الحجم#
| الخطأ | الحد |
|---|---|
file too large: PATH |
ملف أكبر من 1 MB |
bundle too large (N bytes) |
مجموع أكبر من 5 MB |
theme exceeds 400 files / theme exceeds the total bundle size limit |
يوقف قارئ المجلد في الأداة مبكراً قبل التحقق |
قواعد المحتوى#
تُفحص ملفات .liquid و.css نصياً:
| الخطأ | ما يلتقطه |
|---|---|
PATH: <script> is not allowed (themes ship no JavaScript; JSON-LD data blocks are the only exception) |
أي <script> عدا <script type="application/ld+json"> بالضبط |
PATH: inline event handlers (onclick=...) are not allowed |
أي سمة on*= |
PATH: javascript: URLs are not allowed |
javascript: |
PATH: data:text/html URLs are not allowed |
data:text/html |
PATH: <iframe> is not allowed |
<iframe> |
PATH: the \raw` filter is not allowed (breaks output escaping)` |
` |
PATH: "<" is not allowed in CSS (prevents </style> breakout) |
أي < داخل ملف CSS |
PATH: section wrapper markers are platform-emitted and not allowed in theme code |
data-dukkan-section أو data-section-id= في Liquid |
قواعد البنية#
| الخطأ | السبب |
|---|---|
missing required template layout/theme.liquid |
لا هيكل |
missing required config/settings_schema.json |
لا مخطط |
config/settings_schema.json is not valid JSON |
JSON غير صالح |
config/settings_schema.json: … |
خطأ مخطط؛ راجع أخطاء المخطط |
snippets/sections.liquid is a reserved platform path |
ملف محجوز للمنصّة موجود في حزمتك |
theme declares sections but ships no snippets/section-body.liquid |
مخطط بأقسام دون موزّع أجسام |
أخطاء المخطط#
تظهر مسبوقة بـ config/settings_schema.json::
| الخطأ | السبب |
|---|---|
path.to.key: message |
مخالفة بنيوية (مفتاح إضافي، نوع غير مسموح، نص أطول من حدّه، schema_version ليس 1) |
duplicate group id "x" |
معرّف مجموعة مكرّر |
duplicate setting id "x" in group "g" |
معرّف إعداد مكرّر |
setting id "x" in group "g" is reserved |
pages أو translations أو مفتاح كائن محجوز كمعرّف عام |
duplicate section type "x" |
نوع قسم مكرّر |
duplicate block type "b" in section "s" |
نوع كتلة مكرّر |
select "x" in … must declare options |
select بلا خيارات |
setting "x" in … declares options but is not a select |
options على غير select |
setting "x" in … declares source but is not a picker |
source على غير product/category |
setting "x" in … declares localized but is not text |
localized على غير text/textarea/richtext |
setting "x" in … has min greater than max |
min > max |
default … (where) |
قيمة default لا تطابق نوعها |
المواصفة الكاملة في مخطط الإعدادات.
الفحص البعيد#
npx @dukkan.one/theme-cli theme check --remoteيرسل الحزمة إلى POST /theme-api/v1/theme/check فتُعاد القواعد أعلاه على الخادم ثم يُجرى تصيير تجريبي لـ templates/home.liquid في بيئة العمل المعزولة نفسها التي تحرس النشر، بمتجر وهمي ومنتج واحد ومثيل من كل نوع قسم تعلنه. الفشل يعود كسطر render failed: <code> حيث <code> أحد:
| الرمز | المعنى |
|---|---|
timeout |
تجاوز التصيير 1.5 ثانية من عمل المحرّك أو 3 ثوانٍ كلياً |
render_error |
خطأ Liquid (وسم مجهول، مرشّح غير معروف، تضمين لملف غائب) |
output_cap |
المخرجات أكبر من 1 MB |
template_missing |
templates/home.liquid غائب |
worker_unavailable / busy |
ضغط على الخادم؛ أعد المحاولة |
عند الدفع تُفحص مخرجات التصيير أيضاً: غلاف قسم بلا معرّف، أو معرّف مجهول، أو معرّف مكرّر يرفض الدفع حتى لو اجتاز الفحص النصي.
تأخّر المدقّق في الإصدار المنشور#
تحذير
يحزم الإصدار المنشور @dukkan.one/theme-cli@0.1.0 نسخة من المدقّق أقدم من المخطط الحالي: يرفض محلياً band وإضافات أحدث يقبلها الخادم. إن رأيت خطأ مخطط على مفتاح موثّق هنا، فالفحص البعيد هو الحكم. حتى صدور نسخة أحدث، إمّا أن تترك band أو تشغّل نسخة الأداة من مستودع المنصّة.
في مستودع dukkan-themes يوجّه المتغير DUKKAN_CLI=/path/to/app/cli/dist/index.js أدوات المستودع إلى نسخة غير منشورة من الأداة؛ راجع مرجع الأداة.
وصفة CI#
name: theme-check
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx @dukkan.one/theme-cli@0.1.0 theme check .الفحص المحلي لا يحتاج إلى تسجيل دخول؛ --remote يحتاج إلى رمز أداة، فأبقه لتشغيل يدوي أو لخطوة تقرأ اعتماداتها من سرّ.