محیط توسعه‌ی لوکال وردپرس در ۱۴۰۵: wp-env، Docker، Playground، Studio و LocalWP

محیط توسعه‌ی لوکال یعنی یک وردپرس کامل روی سیستم خودتان که در آن کد می‌نویسید، افزونه تست می‌کنید و قالب می‌سازید بدون اینکه سایت واقعی یا اینترنت درگیر شود. تا چند سال پیش جواب این کار XAMPP بود؛ امروز پنج ابزار بهتر وجود دارد که هر کدام برای یک نوع کار ساخته شده‌اند: wp-env ابزار رسمی توسعه‌دهنده‌های بلاک، Docker Compose برای پروژه‌های تیمی، Playground برای اجرا بدون نصب داخل مرورگر، و Studio و LocalWP برای کسانی که رابط گرافیکی می‌خواهند. این راهنما هر پنج را با تنظیمات واقعی راه می‌اندازد و برای مشکل همیشگی توسعه‌دهنده‌های ایرانی، یعنی دانلودهای قطع‌شونده، راه‌حل می‌دهد.

آنچه در این آموزش یاد می‌گیرید

• مقایسه‌ی پنج ابزار لوکال و انتخاب درست بر اساس نوع کار

• راه‌اندازی wp-env با فایل پیکربندی کامل، وردپرس فارسی، Xdebug و سایت تست جداگانه

• یک docker-compose.yml آماده با وردپرس، MariaDB، WP-CLI و phpMyAdmin

• اجرای وردپرس داخل مرورگر با Playground و ساخت دمو با Blueprint

• نکته‌های اینترنت ایران: میرر داکر و npm، و اینکه کدام ابزار اصلاً دانلود ندارد

• دسترسی از موبایل، دیباگ و خطاهای رایج

چرا دیگر XAMPP را توصیه نمی‌کنیم

XAMPP و WAMP یک آپاچی و MySQL مشترک برای همه‌ی پروژه‌ها نصب می‌کنند. نتیجه: یک نسخه‌ی PHP برای همه، تداخل بین سایت‌ها، تنظیماتی که با سرور واقعی فرق دارد و «روی سیستم من کار می‌کرد» در روز تحویل. ابزارهای امروزی هر پروژه را ایزوله می‌کنند، نسخه‌ی PHP و وردپرس را برای هر پروژه جداگانه تعیین می‌کنند و همان تنظیمات را به تیم و CI می‌برند. اگر هنوز با XAMPP راحت‌اید مشکلی نیست، اما حداقل Playground را امتحان کنید؛ پنج ثانیه طول می‌کشد.

همه‌ی این ابزارها رایگان‌اند. ستون «اینترنت ایران» برای انتخاب اولیه مهم‌تر از چیزی است که فکر می‌کنید.

wp-env: ابزار رسمی توسعه‌دهنده‌های وردپرس

wp-env بسته‌ای از تیم گوتنبرگ است که با یک دستور دو سایت وردپرس در داکر بالا می‌آورد: یکی برای توسعه و یکی برای تست‌های خودکار. پوشه‌ای که در آن هستید (افزونه یا قالب شما) مستقیم داخل وردپرس مونت می‌شود، پس هر تغییر بدون کپی و بیلد در مرورگر دیده می‌شود. اگر بلاک یا افزونه می‌سازید، این ابزار پیش‌فرض شماست و create-block هم با گزینه‌ی --wp-env همین را کنار پروژه می‌گذارد.

چهار قدم تا وردپرس آماده. پیش‌نیاز فقط Node و Docker است.

# پیش‌نیازها: Node 22 و Docker در حال اجرا
node -v
docker --version

# نصب سراسری
npm install -g @wordpress/env

# در پوشه‌ی افزونه یا قالب خودتان
wp-env start
# ✔ http://localhost:8888  (admin / password)
# ✔ http://localhost:8889  (سایت تست)

فایل .wp-env.json

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

{
	"$schema": "https://schemas.wp.org/trunk/wp-env.json",
	"core": null,
	"phpVersion": "8.3",
	"plugins": [ ".", "https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip" ],
	"themes": [ "https://downloads.wordpress.org/theme/twentytwentyfive.latest-stable.zip" ],
	"mappings": {
		"wp-content/mu-plugins": "./dev/mu-plugins",
		"wp-content/uploads": "./dev/uploads"
	},
	"port": 8888,
	"testsPort": 8889,
	"config": {
		"WP_DEBUG": true,
		"WP_DEBUG_LOG": true,
		"SCRIPT_DEBUG": true,
		"WPLANG": "fa_IR"
	},
	"lifecycleScripts": {
		"afterStart": "wp-env run cli wp language core install fa_IR --activate"
	}
}

• "core": null یعنی آخرین نسخه‌ی پایدار وردپرس. برای تست با نسخه‌ی خاص می‌توانید "WordPress/WordPress#7.0.3" بدهید.

• در plugins و themes هم مسیر محلی قبول می‌شود و هم آدرس زیپ از مخزن وردپرس.

• mappings هر پوشه‌ی محلی را به هر مسیری داخل وردپرس وصل می‌کند؛ برای mu-plugins و آپلودهای ثابت عالی است.

• lifecycleScripts بعد از هر start اجرا می‌شود؛ این‌جا زبان فارسی را نصب و فعال می‌کند تا هر بار دستی انجام ندهید.

دستورهای روزمره

wp-env start --update          # بعد از تغییر .wp-env.json
wp-env run cli wp plugin list  # هر دستور WP-CLI داخل سایت توسعه
wp-env run tests-cli wp user list
wp-env logs --watch            # لاگ PHP و وب‌سرور
wp-env start --xdebug          # دیباگ با Xdebug روی پورت 9003
wp-env reset tests             # دیتابیس سایت تست را خالی کن
wp-env stop
wp-env destroy                 # حذف کامل کانتینرها و داده

پرچم --xdebug دیباگر PHP را روی پورت ۹۰۰۳ فعال می‌کند؛ در VS Code افزونه‌ی PHP Debug را نصب کنید و با یک پیکربندی launch.json روی خط‌های کد توقف بگذارید. سایت دوم روی پورت ۸۸۸۹ برای تست‌های PHPUnit و Playwright است و با wp-env reset tests همیشه تمیز می‌شود.

Docker Compose: کنترل کامل برای پروژه‌های تیمی

وقتی به nginx، Redis، نسخه‌ی خاص MariaDB یا همان ساختاری نیاز دارید که روی سرور است، مستقیم Docker Compose بنویسید. همان فایل در CI و حتی سرور قابل استفاده است و همه‌ی اعضای تیم دقیقاً یک محیط دارند.

چهار سرویس. پوشه‌ی افزونه یا قالب شما با volume داخل کانتینر وردپرس می‌نشیند.

# docker-compose.yml
services:
  db:
    image: mariadb:11
    environment:
      MARIADB_ROOT_PASSWORD: root
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: wordpress
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      retries: 10

  wordpress:
    image: wordpress:php8.3-apache
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DEBUG: 1
      WORDPRESS_CONFIG_EXTRA: |
        define( 'WP_DEBUG_LOG', true );
        define( 'WPLANG', 'fa_IR' );
    volumes:
      - wp_data:/var/www/html
      - ./wpkala-blocks:/var/www/html/wp-content/plugins/wpkala-blocks
      - ./wpkala-theme:/var/www/html/wp-content/themes/wpkala-theme
      - ./php.ini:/usr/local/etc/php/conf.d/custom.ini

  wpcli:
    image: wordpress:cli
    depends_on:
      - wordpress
    user: "33:33"
    volumes_from:
      - wordpress
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress
    entrypoint: ["wp"]
    command: ["--info"]

  phpmyadmin:
    image: phpmyadmin:latest
    depends_on:
      - db
    ports:
      - "8081:80"
    environment:
      PMA_HOST: db

volumes:
  db_data:
  wp_data:

; php.ini : محدودیت‌های لوکال را بالا ببرید
upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 512M
max_execution_time = 300

docker compose up -d
docker compose run --rm wpcli core install --url=http://localhost:8080 --title="تست" --admin_user=admin --admin_password=admin --admin_email=admin@example.ir --locale=fa_IR
docker compose run --rm wpcli plugin install woocommerce --activate
docker compose logs -f wordpress
docker compose down          # نگه داشتن داده
docker compose down -v       # حذف داده

• healthcheck روی دیتابیس باعث می‌شود وردپرس قبل از آماده شدن MariaDB بالا نیاید و خطای اتصال نگیرید.

• WORDPRESS_CONFIG_EXTRA هر ثابت دلخواهی را به wp-config اضافه می‌کند؛ این‌جا لاگ دیباگ و زبان فارسی.

• سرویس wpcli با همان volume وردپرس اجرا می‌شود و با user: "33:33" (کاربر www-data) فایل‌هایی با مالک اشتباه نمی‌سازد. دستورهای کامل WP-CLI را در مقاله‌ی جداگانه‌ی وردپرس کالا ببینید.

• برای nginx به جای آپاچی از ایمیج wordpress:php8.3-fpm و یک کانتینر nginx با فایل پیکربندی خودتان استفاده کنید.

Playground: وردپرس بدون نصب، حتی بدون اینترنت پایدار

WordPress Playground کل وردپرس را با PHP کامپایل‌شده به WebAssembly و دیتابیس SQLite داخل تب مرورگر اجرا می‌کند. هیچ سروری درگیر نیست، هیچ‌چیز نصب نمی‌شود و فقط یک بار فایل‌های اولیه دانلود می‌شود. برای تست سریع یک افزونه، نشان دادن دمو به مشتری یا آموزش، سریع‌ترین راه ممکن است و وردپرس ۷ هم از همین فناوری برای دکمه‌ی «پیش‌نمایش زنده» در مخزن افزونه‌ها استفاده می‌کند.

سه شکل استفاده: نسخه‌ی مرورگری برای تست سریع، CLI برای توسعه‌ی محلی بدون Docker و Blueprint برای ساخت دموی قابل اشتراک.

# در پوشه‌ی افزونه یا قالب: بالا می‌آید و همین پوشه را نصب می‌کند
npx @wp-playground/cli@latest start

# کنترل کامل: نسخه‌ی وردپرس و PHP، پورت، مونت دستی
npx @wp-playground/cli@latest server --wp=7.1 --php=8.3 --port=9400 \
  --mount=./wpkala-blocks:/wordpress/wp-content/plugins/wpkala-blocks

Blueprint: دمو با یک لینک

Blueprint یک فایل JSON است که می‌گوید سایت با چه نسخه، چه افزونه‌ها، چه قالب و چه تنظیماتی ساخته شود. آن را روی GitHub یا سایت خودتان بگذارید و لینک Playground را به مشتری بفرستید؛ او بدون نصب چیزی یک سایت کامل با افزونه‌ی شما می‌بیند:

{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"landingPage": "/wp-admin/",
	"preferredVersions": { "php": "8.3", "wp": "latest" },
	"login": true,
	"steps": [
		{ "step": "setSiteLanguage", "language": "fa_IR" },
		{ "step": "installPlugin", "pluginData": { "resource": "wordpress.org/plugins", "slug": "woocommerce" } },
		{ "step": "installTheme", "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfive" } },
		{ "step": "setSiteOptions", "options": { "blogname": "دموی وردپرس کالا" } }
	]
}

# اشتراک دمو با یک لینک: فایل blueprint.json را روی GitHub یا سایت بگذارید
https://playground.wordpress.net/?blueprint-url=https://example.ir/blueprint.json

محدودیت‌های Playground را بشناسید: دیتابیس SQLite است نه MySQL، کرون و ایمیل واقعی ندارد و بعضی افزونه‌های سنگین (مثل ووکامرس با داده‌ی زیاد) کند می‌شوند. تست نهایی را همیشه در wp-env یا Docker انجام دهید.

Studio و LocalWP: برای کسانی که ترمینال نمی‌خواهند

Studio ابزار رایگان WordPress.com برای مک و ویندوز است که با یک کلیک سایت می‌سازد، چند سایت را کنار هم مدیریت می‌کند و از نسخه‌ی ۱.۷ خط فرمان و از نسخه‌های بعدی Xdebug و نمایش لاگ دارد. قابلیت Sync آن سایت لوکال را با میزبانی WordPress.com و Pressable همگام می‌کند که برای کاربر ایرانی کاربرد چندانی ندارد، اما خود ابزار برای کار لوکال عالی است. LocalWP (محصول WP Engine) قدیمی‌تر و پخته‌تر است، نسخه‌ی PHP و وب‌سرور را از منو عوض می‌کند و لینک موقت برای نمایش به مشتری می‌دهد. هر دو موقع نصب و ساخت سایت از سرورهای خارجی دانلود می‌کنند؛ یک بار با اتصال پایدار نصب کنید و بعد آفلاین کار می‌کنند.

نکته‌های اینترنت ایران

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

Docker Hub

ایمیج‌های داکر از Docker Hub می‌آیند که برای IP ایران یا محدود است یا بسیار کند. چند شرکت زیرساخت ایرانی میرر رایگان Docker Hub دارند؛ آدرس را از آن‌ها بگیرید و در تنظیمات داکر ثبت کنید:

// /etc/docker/daemon.json  (ویندوز و مک: Docker Desktop › Settings › Docker Engine)
{
  "registry-mirrors": [ "https://آدرس-میرر-ایرانی" ]
}
// بعد: systemctl restart docker  یا  ری‌استارت Docker Desktop

npm

مخزن npm معمولاً باز است اما بسته‌های بزرگ (مثل Playwright یا Puppeteer) قطع می‌شوند. اگر مشکل داشتید میرر داخلی یا پروکسی موقت تنظیم کنید و بعد از نصب به حالت عادی برگردید تا بسته‌ها همیشه از منبع رسمی بیایند:

# اگر npm install کند یا قطع می‌شود، یک میرر یا پروکسی موقت تنظیم کنید
npm config set registry https://آدرس-میرر-npm
# بازگشت به حالت عادی
npm config set registry https://registry.npmjs.org/

بدون دانلود: Playground

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

دسترسی از موبایل و اشتراک با همکار

سایت لوکال روی localhost فقط از همان سیستم باز می‌شود. برای تست روی موبایل در همان شبکه‌ی وای‌فای، آدرس سایت را به IP سیستم تغییر دهید:

# دسترسی به سایت لوکال از موبایل در همان شبکه‌ی وای‌فای
# IP سیستم خودتان را پیدا کنید (مثلاً 192.168.1.20) و در لوکال:
wp-env run cli wp option update home http://192.168.1.20:8888
wp-env run cli wp option update siteurl http://192.168.1.20:8888

برای نشان دادن به کسی بیرون از شبکه، LocalWP لینک موقت دارد و برای بقیه‌ی ابزارها می‌توانید از تونل‌هایی مثل Cloudflare Tunnel استفاده کنید. ساده‌تر از همه: یک Blueprint بسازید و لینک Playground بفرستید.

کدام را انتخاب کنم؟

چهار سؤال کافی است. بیشتر توسعه‌دهنده‌ها در عمل دو ابزار را کنار هم استفاده می‌کنند.

خطاهای رایج و راه‌حل