@wordpress/env چیست و چرا محیط توسعه لوکال وردپرس را متحول کرد؟

@wordpress/env یا همان wp-env یک ابزار خط فرمان مبتنی بر Node.js است که محیط توسعه محلی وردپرس را با Docker و بدون نیاز به پیکربندی دستی راه‌اندازی می‌کند. این ابزار که توسط تیم هسته گوتنبرگ توسعه یافته، دو محیط جداگانه برای توسعه و تست ایجاد کرده و با فایل پیکربندی .wp-env.json امکان تعریف نسخه PHP، نسخه وردپرس، افزونه‌ها و قالب‌ها را فراهم می‌آورد. wp-env مشکل دیرینه ناسازگاری محیط‌های محلی با محیط تولید را با جداسازی سرویس‌ها در کانتینرهای Docker حل کرده و یک محیط قابل تکرار ایجاد می‌کند. این معماری، از توسعه افزونه و قالب تا ادغام در خط لوله CI/CD را پوشش می‌دهد. در این راهنما، معماری، پیکربندی، کاربردهای عملی و نکات پیشرفته wp-env بررسی می‌شود.

نخستین بار که wp-env را راه‌اندازی کردم، انتظار داشتم با یک ابزار ساده و محدود طرف باشم. اما وقتی دیدم دو محیط توسعه و تست به‌طور همزمان بالا آمدند، با یک دستور WP-CLI توانستم با کانتینر تعامل کنم و بدون هیچ پیکربندی دستی، همه‌چیز از پیش آماده بود، متوجه شدم این ابزار رویکرد متفاوتی به محیط محلی دارد. این راهنما حاصل استفاده روزمره از wp-env در پروژه‌های واقعی است. 🐳

wp-env چیست؟

@wordpress/env که به اختصار wp-env نامیده می‌شود، یک بسته npm است که محیط توسعه محلی وردپرس را با استفاده از Docker ایجاد می‌کند[reference:0]. این ابزار توسط تیم هسته گوتنبرگ توسعه یافته و هدف اصلی آن، فراهم کردن یک محیط قابل تکرار و بدون پیکربندی برای ساخت و تست افزونه‌ها و قالب‌های وردپرس است[reference:1].

wp-env در اصل برای رفع مشکلی طراحی شد که سال‌ها توسعه‌دهندگان وردپرس با آن دست‌وپنجه نرم می‌کردند: ایجاد محیطی که سریع راه‌اندازی شود، قابل تکرار باشد، و رفتار آن با محیط تولید همخوانی داشته باشد[reference:2]. برخلاف ابزارهایی مانند XAMPP و MAMP که نیازمند نصب و پیکربندی دستی سرور وب، PHP و MySQL هستند، wp-env تمام این لایه‌ها را در کانتینرهای Docker بسته‌بندی کرده و با یک دستور ساده راه‌اندازی می‌کند.

نکته کلیدی درباره wp-env این است که این ابزار فقط برای توسعه‌دهندگان هسته وردپرس طراحی نشده. هر توسعه‌دهنده‌ای که افزونه یا قالب می‌سازد، یا حتی هر کسی که می‌خواهد یک نمونه وردپرس برای آزمایش داشته باشد، می‌تواند از آن بهره ببرد[reference:3]. برای آشنایی با مبانی وردپرس، مقاله وردپرس چیست و چگونه شروع به کار با آن کنیم؟ را ببینید.

wp-env یک محیط توسعه نیست؛ یک قرارداد است. قراردادی که تضمین می‌کند هر توسعه‌دهنده در تیم، دقیقاً همان محیط را دارد.

چرا wp-env محیط توسعه لوکال را متحول کرد؟

برای درک اهمیت wp-env، باید به مشکل اصلی که این ابزار حل می‌کند نگاه کرد. در توسعه وردپرس، سه عامل همواره باعث اتلاف وقت می‌شدند: پیچیدگی پیکربندی محیط، ناسازگاری نسخه‌ها بین اعضای تیم، و دشواری انتقال محیط بین سیستم‌های مختلف. wp-env هر سه این مشکلات را به‌طور بنیادین حل کرده است.

۱. حذف پیکربندی دستی

پیش از wp-env، راه‌اندازی یک محیط محلی وردپرس نیازمند نصب سرور وب، PHP، MySQL و پیکربندی آن‌ها بود. ابزارهایی مانند XAMPP این فرآیند را ساده‌تر کرده بودند، اما همچنان نیازمند نصب نرم‌افزار، تخصیص پورت‌ها و مدیریت سرویس‌های پس‌زمینه بودند. wp-env این چرخه را با یک دستور جایگزین کرده است: npx wp-env start[reference:4].

۲. تضمین یکسان بودن محیط تیم

در تیم‌های توسعه، یکی از بزرگ‌ترین چالش‌ها این است که هر توسعه‌دهنده ممکن است نسخه متفاوتی از PHP یا MySQL داشته باشد. این اختلاف نسخه می‌تواند به خطاهایی منجر شود که فقط در سیستم یک نفر تکرار می‌شوند. با wp-env، محیط در یک فایل .wp-env.json تعریف می‌شود و هر عضو تیم دقیقاً همان محیط را راه‌اندازی می‌کند. این رویکرد مشابه مفهوم Infrastructure as Code است که در DevOps رایج است.

۳. جداسازی محیط توسعه و تست

wp-env به‌طور پیش‌فرض دو محیط جداگانه ایجاد می‌کند: یک محیط توسعه در پورت 8888 و یک محیط تست در پورت 8889[reference:5]. محیط تست به‌صورت خودکار برای اجرای تست‌های واحد PHPUnit پیکربندی شده است. این جداسازی از آلودگی داده‌های تست به محیط توسعه جلوگیری می‌کند.

جدول ۱: مقایسه رویکرد سنتی و wp-env در راه‌اندازی محیط محلی
معیار	روش سنتی (XAMPP/MAMP)	wp-env
زمان راه‌اندازی اولیه	۳۰ دقیقه تا چند ساعت	۲-۵ دقیقه
نیاز به نصب نرم‌افزار	بله (سرور، PHP، MySQL)	فقط Docker و Node.js
یکسان بودن محیط تیم	دشوار	تضمین‌شده
محیط تست جداگانه	نیاز به پیکربندی دستی	پیش‌فرض
قابلیت تعریف در فایل	خیر	بله (.wp-env.json)
ادغام با CI/CD	دشوار	پشتیبانی رسمی

پیش از wp-env: دردسرهای محیط محلی سنتی

برای درک بهتر تحولی که wp-env ایجاد کرده، باید به چالش‌های محیط‌های سنتی نگاه کرد. در سال‌های پیش از معرفی wp-env، توسعه‌دهندگان وردپرس با مشکلات متعددی مواجه بودند که هر یک می‌توانست ساعت‌ها وقت گرانبها را تلف کند.

مشکل نسخه PHP

افزونه‌ای که با PHP 8.2 نوشته شده بود، در محیطی با PHP 7.4 خطای Fatal می‌داد. توسعه‌دهنده مجبور بود یا نسخه PHP سیستم خود را ارتقا دهد (که ممکن است پروژه‌های دیگر را مختل کند) یا از ابزارهایی مانند phpbrew استفاده کند که خود فرآیند پیچیده‌ای داشت.

مشکل پورت‌ها و سرویس‌ها

در محیط‌های سنتی، اگر Apache روی پورت ۸۰ در حال اجرا بود، MySQL روی پورت ۳۳۰۶ و phpMyAdmin روی پورت ۸۰۸۰، هر پروژه جدید نیازمند پیکربندی مجدد این پورت‌ها بود. تصادم پورت‌ها یکی از رایج‌ترین دلایل خطا در راه‌اندازی محیط محلی بود.

مشکل انتقال پروژه

وقتی یک توسعه‌دهنده جدید به تیم اضافه می‌شد، باید مرحله‌به‌مرحله تمام پیکربندی محیط را تکرار می‌کرد. یک اشتباه کوچک در تنظیمات می‌توانست به تفاوت‌های پنهانی منجر شود که ماه‌ها بعد خود را نشان می‌داد.

wp-env این چرخه را با یک رویکرد اعلانی (Declarative) شکست. به جای تعریف گام‌های نصب، تمام پیکربندی در یک فایل JSON تعریف می‌شود و wp-env مسئولیت اجرای آن را بر عهده می‌گیرد. برای مطالعه درباره معماری وب، مقاله معماری وب چیست؟ را ببینید.

معماری فنی wp-env

wp-env بر پایه Docker بنا شده است. Docker یک پلتفرم کانتینرسازی است که امکان جداسازی اپلیکیشن‌ها را در محیط‌های ایزوله فراهم می‌کند. wp-env از این قابلیت برای ایجاد یک محیط وردپرس کامل شامل سرور وب، PHP، MySQL و WP-CLI استفاده می‌کند.

اجزای معماری

wp-env از چند سرویس اصلی تشکیل شده است که در کانتینرهای جداگانه اجرا می‌شوند:

کانتینر WordPress: شامل سرور وب (Apache)، PHP و هسته وردپرس. کد افزونه یا قالبی که در حال توسعه آن هستید، از طریق Volume به این کانتینر متصل می‌شود.
کانتینر MySQL: پایگاه داده اختصاصی برای هر محیط. داده‌ها در Volume ذخیره می‌شوند تا با ری‌استارت کانتینر از بین نروند.
کانتینر WP-CLI: ابزار خط فرمان وردپرس که امکان اجرای دستورات مدیریتی را از خارج کانتینر فراهم می‌کند.

در سطح پیاده‌سازی، wp-env از کتابخانه docker-compose برای تعریف و مدیریت این سرویس‌ها استفاده می‌کند[reference:6]. هر بار که wp-env start را اجرا می‌کنید، wp-env یک فایل docker-compose.yml به صورت پویا تولید کرده و کانتینرها را راه‌اندازی می‌نماید.

Volume Mapping و توسعه زنده

یکی از هوشمندانه‌ترین جنبه‌های معماری wp-env، نحوه اتصال کد در حال توسعه به کانتینر است. wp-env پوشه افزونه یا قالب شما را از سیستم میزبان به مسیر /wp-content/plugins/ یا /wp-content/themes/ در کانتینر Map می‌کند. این بدان معناست که هر تغییری که در ویرایشگر کد خود ایجاد می‌کنید، بلافاصله در کانتینر منعکس می‌شود، بدون نیاز به Build یا Rebuild. برای مطالعه درباره ساختار افزونه‌ها، مقاله ساختار فایل‌های یک افزونه استاندارد وردپرس را ببینید.

معماری wp-env بر پایه جداسازی سرویس‌ها بنا شده: هر سرویس در کانتینر خود، اما همه در یک شبکه Docker به هم متصل.

نصب و راه‌اندازی

نصب wp-env ساده است اما نیازمند دو پیش‌نیاز است: Node.js (نسخه ۱۴ یا بالاتر) و Docker Desktop. Docker باید روی سیستم شما نصب و در حال اجرا باشد[reference:7].

نصب سراسری

npm -g i @wordpress/env

پس از نصب، با اجرای دستور wp-env start در پوشه پروژه، محیط راه‌اندازی می‌شود. محیط توسعه در آدرس http://localhost:8888 و محیط تست در http://localhost:8889 در دسترس خواهد بود[reference:8].

نصب محلی (توصیه‌شده)

به‌جای نصب سراسری، توصیه می‌شود wp-env را به عنوان وابستگی توسعه در پروژه خود تعریف کنید. این رویکرد تضمین می‌کند که هر عضو تیم از همان نسخه استفاده می‌کند:

npm install --save-dev @wordpress/env

سپس در فایل package.json، اسکریپت‌های لازم را تعریف کنید:

"scripts": {
    "wp-env": "wp-env",
    "start": "wp-env start",
    "stop": "wp-env stop",
    "destroy": "wp-env destroy"
}

با این پیکربندی، اعضای تیم می‌توانند با npm run start محیط را راه‌اندازی کنند. برای مطالعه درباره مدیریت وابستگی‌ها، مقاله npm یا Yarn؛ کدام برای مدیریت پکیج سریع‌تر است؟ را ببینید.

فایل پیکربندی wp-env.json

فایل .wp-env.json قلب پیکربندی wp-env است. این فایل در ریشه پروژه قرار می‌گیرد و به wp-env می‌گوید که چه محیطی بسازد. ساختار این فایل JSON است و شامل کلیدهای متعددی برای تعریف نسخه PHP، نسخه وردپرس، افزونه‌ها، قالب‌ها، و تنظیمات دیگر می‌شود[reference:9].

پیکربندی پایه

{
    "core": "WordPress/WordPress#6.7",
    "phpVersion": "8.3",
    "plugins": [
        "https://downloads.wordpress.org/plugin/woocommerce.zip",
        "."
    ],
    "themes": [
        "https://downloads.wordpress.org/theme/twentytwentyfour.zip"
    ],
    "config": {
        "WP_DEBUG": true,
        "SCRIPT_DEBUG": true
    }
}

در این پیکربندی، core نسخه وردپرس را تعیین می‌کند. می‌توانید از برچسب‌های Git مانند WordPress/WordPress#6.7 یا WordPress/WordPress#trunk استفاده کنید. علامت . در آرایه plugins به wp-env می‌گوید که پوشه فعلی را به عنوان افزونه نصب کند. config نیز مقادیر ثابت‌های PHP را در فایل wp-config.php تعریف می‌کند[reference:10].

پیکربندی محیط تست

wp-env امکان تعریف تنظیمات جداگانه برای محیط تست را نیز فراهم می‌کند. از کلید testsEnvironment می‌توان برای فعال یا غیرفعال کردن محیط تست، تعریف افزونه‌های خاص، یا تغییر نسخه PHP استفاده کرد:

{
    "testsEnvironment": false
}

غیرفعال کردن محیط تست می‌تواند زمان راه‌اندازی و مصرف منابع را کاهش دهد، به‌ویژه در پروژه‌هایی که نیازی به اجرای تست‌های واحد ندارند.

پیکربندی Multisite

wp-env از راه‌اندازی وردپرس مولتی‌سایت نیز پشتیبانی می‌کند. با تنظیم WP_ALLOW_MULTISITE و MULTISITE در بخش config، محیط به صورت شبکه‌ای راه‌اندازی می‌شود. برای مطالعه درباره مولتی‌سایت، مقاله آموزش کار با وردپرس مولتی‌سایت را ببینید.

اسکریپت‌های چرخه حیات (Lifecycle Scripts)

یکی از قدرتمندترین قابلیت‌های wp-env، پشتیبانی از اسکریپت‌های چرخه حیات است. این اسکریپت‌ها در نقاط مشخصی از چرخه حیات محیط اجرا می‌شوند و به شما امکان می‌دهند فرآیندهای خودکارسازی را تعریف کنید.

انواع اسکریپت‌های چرخه حیات

wp-env از چهار نقطه چرخه حیات پشتیبانی می‌کند[reference:11]:

afterStart: بلافاصله پس از راه‌اندازی کانتینرها اجرا می‌شود.
afterStop: بلافاصله پس از توقف کانتینرها اجرا می‌شود.
beforeStart: قبل از راه‌اندازی کانتینرها اجرا می‌شود.
afterDestroy: پس از حذف کانتینرها و داده‌ها اجرا می‌شود.

مثال عملی: نصب خودکار محتوا

فرض کنید می‌خواهید هر بار که محیط راه‌اندازی می‌شود، یک افزونه خاص نصب شود و یک برگه پیش‌فرض ایجاد شود. می‌توانید از afterStart استفاده کنید:

{
    "lifecycleScripts": {
        "afterStart": "wp-env run cli wp plugin install contact-form-7 --activate && wp-env run cli wp post create --post_type=page --post_title='About Us' --post_status=publish"
    }
}

این اسکریپت پس از هر بار راه‌اندازی، افزونه Contact Form 7 را نصب و فعال کرده و یک برگه «درباره ما» ایجاد می‌کند. این قابلیت برای محیط‌های آموزشی، دموها، و تست‌های خودکار بسیار مفید است.

اسکریپت‌های چرخه حیات، wp-env را از یک ابزار ساده راه‌اندازی به یک سیستم خودکارسازی کامل تبدیل می‌کنند.

تعامل با WP-CLI

wp-env به‌طور پیش‌فرض یک کانتینر WP-CLI در اختیار شما قرار می‌دهد که از طریق دستور wp-env run cli قابل دسترسی است[reference:12]. این کانتینر به همان دیتابیس و فایل‌سیستم محیط توسعه متصل است و امکان اجرای هر دستور WP-CLI را فراهم می‌کند.

دستورات پرکاربرد

# اجرای دستور WP-CLI در محیط توسعه
wp-env run cli wp plugin list

# اجرای دستور در محیط تست
wp-env run tests-cli wp plugin list

# باز کردن Shell در کانتینر
wp-env run cli bash

# اجرای اسکریپت PHP در زمینه وردپرس
wp-env run cli wp eval 'var_dump( get_option( \"blogname\" ) );'

این قابلیت به‌ویژه در خودکارسازی فرآیندهای توسعه مفید است. برای مثال، می‌توانید یک اسکریپت Shell بنویسید که پس از راه‌اندازی محیط، داده‌های تست را وارد کند. برای مطالعه بیشتر درباره WP-CLI، مقاله آموزش مدیریت دیتابیس وردپرس را ببینید.

محیط تست و PHPUnit

wp-env به‌طور خودکار یک محیط تست جداگانه ایجاد می‌کند که برای اجرای تست‌های واحد PHPUnit پیکربندی شده است. این محیط در پورت 8889 در دسترس است و از دیتابیس جداگانه‌ای استفاده می‌کند.

نصب پیش‌نیازهای PHPUnit

برای اجرای تست‌ها، ابتدا باید اسکریپت‌های نصب را اجرا کنید:

wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin bash -c \"composer install\"
wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin bash -c \"composer run test\"

پیکربندی phpunit.xml

فایل phpunit.xml.dist در ریشه افزونه باید به مسیر نصب وردپرس در کانتینر اشاره کند:

<?xml version=\"1.0\"?>
<phpunit>
    <testsuites>
        <testsuite name=\"default\">
            <directory suffix=\"Test.php\">./tests/</directory>
        </testsuite>
    </testsuites>
</phpunit>

با این پیکربندی، می‌توانید تست‌های واحد خود را در محیطی ایزوله اجرا کنید که به داده‌های محیط توسعه آسیب نمی‌زند. برای مطالعه درباره استانداردهای کدنویسی، مقاله استانداردهای کدنویسی وردپرس چیست را ببینید.

ادغام با CI/CD و GitHub Actions

یکی از کاربردهای حیاتی wp-env، ادغام با خط لوله CI/CD است. از آنجا که wp-env محیطی قابل تکرار ایجاد می‌کند، می‌توان از آن در GitHub Actions برای اجرای تست‌های خودکار استفاده کرد.

پیکربندی GitHub Actions

نمونه‌ای از یک Workflow که با wp-env تست‌های E2E را اجرا می‌کند:

name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Start wp-env
        run: npm run wp-env start

      - name: Run tests
        run: npm run test:e2e

این رویکرد در پروژه‌های واقعی مانند مخزن وردپرس و WooCommerce استفاده می‌شود. پروژه WooCommerce از wp-env به عنوان محیط پایه برای تست‌های خودکار استفاده می‌کند و اسکریپت‌هایی برای به‌روزرسانی پیکربندی wp-env با آخرین نسخه‌های PHP، وردپرس و Docker دارد[reference:13]. برای مطالعه درباره CI/CD در وردپرس، مقاله CI/CD برای پروژه‌های وردپرسی چگونه پیاده‌سازی می‌شود؟ را ببینید.

wp-env در برابر ابزارهای جایگزین

wp-env تنها ابزار محیط توسعه محلی وردپرس نیست. ابزارهای دیگری مانند wp-now و WordPress Playground CLI نیز وجود دارند که رویکردهای متفاوتی ارائه می‌دهند. درک تفاوت این ابزارها برای انتخاب درست ضروری است.

wp-now

wp-now یک ابزار سبک‌تر است که بر پایه WordPress Playground ساخته شده و از WebAssembly و SQLite به جای Docker استفاده می‌کند. این ابزار در حدود ۵ ثانیه راه‌اندازی می‌شود و نیازی به Docker ندارد[reference:14]. اما محدودیت‌های آن شامل عدم پشتیبانی از MySQL واقعی و ناسازگاری با برخی افزونه‌هاست.

Local by Flywheel

Local یک اپلیکیشن گرافیکی است که محیط محلی وردپرس را فراهم می‌کند. این ابزار برای کاربران غیرفنی مناسب‌تر است اما انعطاف‌پذیری wp-env را ندارد و ادغام آن با CI/CD دشوارتر است.

جدول ۲: مقایسه wp-env با wp-now و Local
معیار	wp-env	wp-now	Local by Flywheel
زمان راه‌اندازی	۲-۵ دقیقه	~۵ ثانیه	۱-۳ دقیقه
وابستگی	Docker + Node.js	فقط Node.js	اپلیکیشن اختصاصی
دیتابیس	MySQL واقعی	SQLite	MySQL واقعی
پیکربندی اعلانی	بله (.wp-env.json)	محدود	رابط گرافیکی
ادغام با CI/CD	عالی	خوب	ضعیف
مناسب برای	توسعه جدی، تیم‌ها	تست سریع	کاربران غیرفنی

به‌طور کلی، wp-env برای پروژه‌های جدی و تیم‌های توسعه انتخاب بهتری است، در حالی که wp-now برای تست سریع و بررسی افزونه‌ها مناسب‌تر است. برای مطالعه درباره WordPress Playground، مقاله WordPress Playground چطور وردپرس را بدون نصب در مرورگر اجرا می‌کند؟ را ببینید.

پشتیبانی از Multisite و Xdebug

wp-env از چندین سناریوی پیشرفته پشتیبانی می‌کند که آن را از ابزارهای ساده‌تر متمایز می‌کند.

راه‌اندازی Multisite

برای راه‌اندازی وردپرس مولتی‌سایت، کافی است تنظیمات زیر را در .wp-env.json اضافه کنید:

{
    "config": {
        "WP_ALLOW_MULTISITE": true,
        "MULTISITE": true,
        "SUBDOMAIN_INSTALL": false,
        "DOMAIN_CURRENT_SITE": "localhost",
        "PATH_CURRENT_SITE": "/",
        "SITE_ID_CURRENT_SITE": 1,
        "BLOG_ID_CURRENT_SITE": 1
    }
}

فعال‌سازی Xdebug

wp-env از Xdebug برای اشکال‌زدایی پشتیبانی می‌کند. برای فعال‌سازی، باید متغیر محیطی XDEBUG_MODE را تنظیم کنید:

XDEBUG_MODE=debug wp-env start

سپس می‌توانید از VS Code یا PHPStorm برای اتصال به Xdebug استفاده کنید. این قابلیت برای رفع خطاهای پیچیده در کد PHP ضروری است. برای مطالعه درباره رفع خطاها، مقاله خطاهای رایج وردپرس و رفع مرحله‌به‌مرحله آن‌ها را ببینید.

رویکرد آینده: افزودن WordPress Playground به عنوان Runtime

یکی از تحولات مهم در اکوسیستم wp-env، افزودن پشتیبانی از WordPress Playground به عنوان یک Runtime جایگزین است. در ژانویه ۲۰۲۶، یک Pull Request در مخزن گوتنبرگ معرفی شد که یک معماری چند Runtime برای wp-env پیشنهاد می‌دهد[reference:15].

در این معماری، کاربران می‌توانند بین دو Runtime انتخاب کنند:

Docker Runtime: Runtime پیش‌فرض که از کانتینرهای Docker و MySQL واقعی استفاده می‌کند.
Playground Runtime: Runtime آزمایشی که از WebAssembly و SQLite استفاده می‌کند و نیازی به Docker ندارد[reference:16].

این معماری مزایای قابل توجهی دارد: راه‌اندازی سریع‌تر، عدم نیاز به Docker، و کاهش مصرف منابع. با این حال، محدودیت‌هایی مانند عدم پشتیبانی از MySQL واقعی و ناسازگاری با برخی افزونه‌ها همچنان وجود دارد. این تغییر نشان‌دهنده روند گسترده‌تر در اکوسیستم وردپرس به سمت سبک‌سازی محیط‌های توسعه است.

خطاهای رایج و عیب‌یابی

در استفاده از wp-env، برخی خطاهای رایج می‌توانند تجربه را تحت تأثیر قرار دهند. در ادامه، مهم‌ترین این خطاها و راه‌حل‌های آن‌ها بررسی می‌شود.

خطای «Could not find the current WordPress version»

این خطا زمانی رخ می‌دهد که wp-env نتواند نسخه وردپرس را از مخزن GitHub دریافت کند. علت معمولاً مشکلات شبکه یا محدودیت‌های جغرافیایی است[reference:17]. راه‌حل‌ها شامل استفاده از VPN، تنظیم پروکسی، و پاک کردن کش wp-env است:

wp-env destroy
wp-env start

خطای Docker Daemon

اگر Docker Desktop در حال اجرا نباشد، wp-env با خطا مواجه می‌شود. بررسی کنید که Docker Desktop باز و سرویس آن فعال باشد. در ویندوز، اطمینان حاصل کنید که WSL2 Backend فعال است[reference:18].

خطای Timeout در راه‌اندازی

در شبکه‌های کند، wp-env ممکن است با خطای ETIMEDOUT مواجه شود[reference:19]. راه‌حل شامل افزایش Timeout، استفاده از پروکسی، یا دانلود دستی بسته‌هاست.

تصادم پورت

اگر پورت‌های ۸۸۸۸ یا ۸۸۸۹ توسط سرویس دیگری اشغال شده باشند، wp-env نمی‌تواند راه‌اندازی شود. با دستور lsof -i :8888 می‌توانید سرویس اشغال‌کننده را پیدا کنید.

خطای مجوز فایل

در لینوکس و مک، ممکن است wp-env با خطای مجوز در Volume Mapping مواجه شود. راه‌حل شامل تنظیم مجوزهای پوشه پروژه است:

chmod -R 755 /path/to/project

خطاهای wp-env تقریباً همیشه به یکی از سه علت برمی‌گردند: Docker، شبکه، یا مجوزها. با بررسی این سه، بیشتر مشکلات حل می‌شوند.

دیدگاه مهندسی پیشرفته

از منظر مهندسی نرم‌افزار، wp-env یک پیاده‌سازی از مفهوم Containerization بدون پیچیدگی Docker است. در حالی که Docker به‌طور خام نیازمند درک عمیق از شبکه، Volume و Image است، wp-env این پیچیدگی‌ها را انتزاع کرده و یک API ساده مبتنی بر CLI ارائه می‌دهد. این رویکرد مشابه کاری است که Terraform برای مدیریت زیرساخت ابری انجام می‌دهد.

در سطح معماری، wp-env از الگوی Declaration Management استفاده می‌کند. به جای اجرای دستورات Imperative برای راه‌اندازی هر سرویس، وضعیت نهایی در فایل .wp-env.json تعریف می‌شود و wp-env مسئولیت رسیدن به آن وضعیت را بر عهده می‌گیرد. این رویکرد مشابه Kubernetes است که در آن وضعیت مطلوب در YAML تعریف شده و سیستم مسئول همگرایی است.

یکی از جنبه‌های پیشرفته، معماری چند Runtime آینده wp-env است. در این معماری، wp-env به یک لایه انتزاعی تبدیل می‌شود که می‌تواند با Runtimeهای مختلف (Docker، Playground) کار کند. این طراحی مشابه الگوی Strategy در برنامه‌نویسی شی‌گرا است، جایی که الگوریتم اجرایی می‌تواند در زمان اجرا تغییر کند بدون تغییر کد فراخوان.

برای مهندسان ارشد، درک تعامل wp-env با سیستم فایل میزبان اهمیت دارد. Volume Mapping در wp-env به‌طور پیش‌فرض از Bind Mount استفاده می‌کند، به این معنی که فایل‌های پروژه مستقیماً از سیستم میزبان خوانده و نوشته می‌شوند. این رویکرد عملکرد خوبی در مک و لینوکس دارد اما در ویندوز می‌تواند کند باشد. برای بهبود عملکرد در ویندوز، می‌توان از WSL2 و ذخیره پروژه در فایل‌سیستم لینوکس استفاده کرد.

در آینده، انتظار می‌رود که wp-env با قابلیت‌هایی مانند پشتیبانی از محیط‌های چندسرویسی سفارشی (مانند Redis و Elasticsearch)، ادغام عمیق‌تر با WordPress Playground، و بهبود عملکرد در ویندوز گسترش یابد. توسعه‌دهندگانی که امروز بر wp-env مسلط شوند، در آینده مزیت رقابتی خواهند داشت. برای مطالعه درباره آینده وردپرس، مقاله گوتنبرگ و آینده ویرایش محتوا در وردپرس را ببینید.

پرسش‌های پرتکرار درباره wp-env

wp-env چیست و چه تفاوتی با XAMPP دارد؟

wp-env یک ابزار خط فرمان مبتنی بر Docker است که محیط توسعه وردپرس را بدون پیکربندی دستی راه‌اندازی می‌کند. برخلاف XAMPP که نیازمند نصب و پیکربندی سرور، PHP و MySQL است، wp-env همه این لایه‌ها را در کانتینرهای Docker بسته‌بندی کرده و با یک دستور راه‌اندازی می‌کند.

آیا wp-env به Docker نیاز دارد؟

بله، در حالت پیش‌فرض wp-env بر پایه Docker کار می‌کند. با این حال، یک Runtime آزمایشی مبتنی بر WordPress Playground نیز در حال توسعه است که نیازی به Docker ندارد[reference:20].

چگونه محیط تست را در wp-env غیرفعال کنم؟

با اضافه کردن "testsEnvironment": false به فایل .wp-env.json، محیط تست غیرفعال می‌شود. این کار زمان راه‌اندازی و مصرف منابع را کاهش می‌دهد.

آیا wp-env از Multisite پشتیبانی می‌کند؟

بله، با تنظیم WP_ALLOW_MULTISITE و MULTISITE در بخش config فایل .wp-env.json می‌توانید وردپرس مولتی‌سایت را راه‌اندازی کنید.

چگونه داده‌های محیط wp-env را پاک کنم؟

با دستور wp-env destroy تمام کانتینرها و Volumeها حذف می‌شوند. برای پاک کردن فقط دیتابیس، از wp-env reset استفاده کنید.

آیا wp-env در CI/CD قابل استفاده است؟

بله، wp-env برای ادغام با CI/CD طراحی شده است. پروژه‌هایی مانند WooCommerce و وردپرس هسته از wp-env در GitHub Actions برای اجرای تست‌های خودکار استفاده می‌کنند[reference:21].

آیا wp-env از Xdebug پشتیبانی می‌کند؟

بله، با تنظیم XDEBUG_MODE=debug می‌توانید Xdebug را فعال کنید و از VS Code یا PHPStorm به آن متصل شوید.

تفاوت wp-env و wp-now چیست؟

wp-env بر پایه Docker و MySQL واقعی کار می‌کند و برای توسعه جدی مناسب است. wp-now بر پایه WebAssembly و SQLite کار می‌کند، سریع‌تر راه‌اندازی می‌شود اما محدودیت‌های بیشتری دارد[reference:22].

آنچه در عمل اهمیت دارد

@wordpress/env یک تغییر پارادایمی در نحوه راه‌اندازی محیط توسعه محلی وردپرس است. این ابزار با حذف پیکربندی دستی، تضمین یکسان بودن محیط تیم، و ارائه دو محیط جداگانه توسعه و تست، بهره‌وری توسعه‌دهندگان را به‌طور قابل توجهی افزایش می‌دهد. از منظر معماری، wp-env یک لایه انتزاعی تمیز روی Docker ایجاد می‌کند که پیچیدگی‌های کانتینرسازی را پنهان کرده و یک API ساده مبتنی بر CLI ارائه می‌دهد.

برای توسعه‌دهندگان، تسلط بر wp-env به یک مهارت ضروری تبدیل شده است. این ابزار نه تنها در توسعه افزونه و قالب کاربرد دارد، بلکه در ادغام با CI/CD و تست‌های خودکار نیز نقش کلیدی ایفا می‌کند. با گسترش معماری چند Runtime در آینده، wp-env احتمالاً به یک لایه انتزاعی جامع‌تر تبدیل خواهد شد که می‌تواند با Runtimeهای مختلف کار کند. 🚀

اگر این ابزار را در گردش کار خود ادغام کرده‌اید، برای ما جالب است بدانید کدام جنبه آن بیشترین ارزش را برایتان ایجاد کرده است. تجربه خودتان را در دیدگاه‌ها بنویسید؛ به‌خصوص اگر پیکربندی خلاقانه‌ای در فایل .wp-env.json ساخته‌اید که می‌تواند برای خواننده بعدی مفید باشد.