Белый экран при установке OpenCart: причины и полное решение проблемы

Вы устанавливаете OpenCart, доходите до 3-го шага - и вместо интернет-магазина видите белую страницу. Или после завершения установки главная страница пустая, а ошибки нигде не отображаются. Это одна из самых частых проблем при первом запуске OpenCart, и она решается - нужно только знать, где искать.

В статье разберём: почему возникает белый экран смерти (WSoD) в OpenCart, как включить отображение ошибок, что чаще всего ломается на 3-м шаге установки, и как устранить каждую проблему пошагово.

Что такое белый экран OpenCart

«Белый экран смерти» (White Screen of Death) - это когда PHP-приложение падает с фатальной ошибкой, но вместо сообщения об ошибке браузер показывает пустую страницу. Так происходит потому, что на большинстве хостингов вывод ошибок отключён по умолчанию из соображений безопасности.

В случае OpenCart это означает: движок запустился, PHP обработал запрос, но где-то в коде или конфигурации произошёл сбой. Сервер ответил пустым телом - отсюда и белая страница.

Почему возникает белый экран при установке OpenCart

Причин несколько, и они встречаются в порядке убывания частоты:

Версия PHP не совпадает с требованиями OpenCart. OpenCart 3.x требует PHP 7.2–7.4. На PHP 8.0 и выше он работает нестабильно или не работает вовсе. OpenCart 4.x требует PHP 8.0+. Несовпадение версии - причина №1.

Не хватает PHP-расширений. OpenCart требует: mysqli, curl, zip, gd, mbstring, xml, openssl. Если хотя бы одного нет - установщик падает на 3-м шаге без объяснений.

Ошибка в файлах конфигурации. После установки OpenCart создаёт два файла: config.php в корне и admin/config.php. Если в них неправильно указан путь или URL - фронтенд и админка не запустятся.

Недостаточно прав на папки и файлы. Папки system/storage, image, cache, upload должны быть доступны для записи (CHMOD 755 или 777).

Остался папка install/ после установки. Если не удалить директорию install/, некоторые версии OpenCart не запустят главную страницу.

Проблема с .htaccess. Неправильный mod_rewrite или отсутствие .htaccess ломает маршрутизацию.

Частые ошибки при установке OpenCart

Белый экран на шаге 3

Шаг 3 установщика - это запись в базу данных и создание конфигурационных файлов. Он чаще всего ломается по одной из причин:

• Неверные данные для подключения к MySQL (логин, пароль, имя БД, хост).

• MySQL-пользователь не имеет прав CREATE, INSERT, UPDATE на базу.

• PHP не может записать config.php - нет прав на корневую папку.

• Версия MySQL ниже минимально необходимой (OpenCart 3.x требует MySQL 5.7+).

Ошибка 500 при установке

HTTP 500 - это серверная ошибка. Значит, PHP упал с исключением. Причины: синтаксическая ошибка в конфиге, несовместимая версия PHP, отсутствующее расширение, или превышен лимит памяти (memory_limit слишком мал).

После установки главная страница пустая

Это значит, что config.php создан, но в нём ошибка. Чаще всего - неправильный HTTP_SERVER или DIR_SYSTEM. Либо папка install/ не удалена, либо тема не применена.

Ошибки не показываются

PHP в production-режиме скрывает ошибки. Нужно включить их вручную - об этом ниже.

Как исправить белый экран OpenCart: пошаговая инструкция

Шаг 1. Включите отображение ошибок

Прежде чем что-то чинить, нужно увидеть, что сломано.

Способ 1 - через PHP-конфиг сайта:

Создайте файл .user.ini в корне сайта или отредактируйте php.ini:

display_errors = On
error_reporting = E_ALL
log_errors = On
error_log = /путь/к/сайту/php_errors.log

Способ 2 - добавить в начало index.php OpenCart:

<?php
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

Добавьте эти строки сразу после открывающего <?php. После диагностики уберите их обратно.

Способ 3 - посмотреть логи OpenCart:

system/storage/logs/error.log

Там обычно написано всё, что нужно.

Шаг 2. Проверьте версию PHP

Зайдите в панель управления хостингом и убедитесь, что версия PHP совпадает с требованиями вашей версии OpenCart:

Если нужно, переключите версию PHP в cPanel, ISPmanager или DirectAdmin.

Шаг 3. Проверьте наличие PHP-расширений

Создайте файл phpinfo.php в корне сайта:

<?php phpinfo();

Откройте его в браузере и найдите разделы: mysqli, curl, gd, mbstring, zip, xml. Если какого-то нет - включите его через панель хостинга или попросите поддержку.

После проверки удалите phpinfo.php - он раскрывает конфигурацию сервера.

Шаг 4. Проверьте и исправьте config.php

Откройте /config.php в корне сайта. Вот как должен выглядеть корректный файл:

<?php
// HTTP
define('HTTP_SERVER', 'https://example.com/');

// HTTPS
define('HTTPS_SERVER', 'https://example.com/');

// DIR
define('DIR_OPENCART', '/var/www/example.com/');
define('DIR_APPLICATION', DIR_OPENCART . 'catalog/');
define('DIR_SYSTEM', DIR_OPENCART . 'system/');
define('DIR_IMAGE', DIR_OPENCART . 'image/');
define('DIR_STORAGE', DIR_OPENCART . 'system/storage/');
define('DIR_LANGUAGE', DIR_APPLICATION . 'language/');
define('DIR_TEMPLATE', DIR_APPLICATION . 'view/theme/');
define('DIR_CONFIG', DIR_SYSTEM . 'config/');
define('DIR_CACHE', DIR_STORAGE . 'cache/');
define('DIR_DOWNLOAD', DIR_STORAGE . 'download/');
define('DIR_LOGS', DIR_STORAGE . 'logs/');
define('DIR_MODIFICATION', DIR_STORAGE . 'modification/');
define('DIR_UPLOAD', DIR_STORAGE . 'upload/');
define('DIR_DB', DIR_SYSTEM . 'database/');

// DB
define('DB_DRIVER', 'mysqli');
define('DB_HOSTNAME', 'localhost');
define('DB_USERNAME', 'db_user');
define('DB_PASSWORD', 'db_password');
define('DB_DATABASE', 'db_name');
define('DB_PORT', '3306');
define('DB_PREFIX', 'oc_');

Типичные ошибки: слэш в конце HTTP_SERVER забыт, неверный DIR_OPENCART (абсолютный путь, а не относительный), несоответствие DB_PREFIX тому, что реально в базе.

Шаг 5. Установите правильные права на папки

Через SSH или файловый менеджер хостинга:

# Папки - 755, файлы - 644
find /var/www/example.com -type d -exec chmod 755 {} \;
find /var/www/example.com -type f -exec chmod 644 {} \;

# Папки, требующие записи
chmod 777 /var/www/example.com/system/storage/cache
chmod 777 /var/www/example.com/system/storage/logs
chmod 777 /var/www/example.com/system/storage/download
chmod 777 /var/www/example.com/system/storage/upload
chmod 777 /var/www/example.com/image

Шаг 6. Удалите папку install/

После завершения установки удалите папку install/ из корня сайта. Пока она существует, некоторые версии OpenCart отказываются запускать магазин.

rm -rf /var/www/example.com/install/

Шаг 7. Проверьте .htaccess

Убедитесь, что в корне сайта есть файл .htaccess. Если он был удалён или не создан - скопируйте из .htaccess.txt (он входит в поставку OpenCart):

cp .htaccess.txt .htaccess

Также убедитесь, что на сервере включён mod_rewrite. В cPanel это делается через «Конфигурация Apache» или через поддержку хостинга.

Шаг 8. Очистите кэш

Если магазин запускался, но после изменений снова показывает белый экран:

rm -rf /var/www/example.com/system/storage/cache/*
rm -rf /var/www/example.com/system/storage/modification/*

В админке: Extensions → Modifications → Refresh (иконка обновления).

Примеры реальных ошибок и их исправление

Пример 1. Ошибка в логе:

PHP Fatal error: Uncaught Error: Call to undefined function mysqli_connect()

Решение: включите расширение php_mysqli в настройках PHP на хостинге.

Пример 2. Ошибка в логе:

Warning: require(/var/www/html/system/startup.php): failed to open stream: No such file or directory

Решение: неверный DIR_SYSTEM в config.php. Проверьте абсолютный путь к папке system/.

Пример 3. HTTP 500, лог Apache:

/var/www/html/.htaccess: Invalid command 'Options', perhaps misspelled or defined by a module not included in the server configuration

Решение: на сервере не включён mod_rewrite или AllowOverride All в виртуальном хосте.

Пример 4. Белый экран без ошибок в логе: Включите логирование через php.ini, проверьте memory_limit. Для OpenCart минимум - 128M, рекомендуется 256M:

memory_limit = 256M

Часто задаваемые вопросы

- Белый экран только в админке, фронтенд работает. Почему? Проверьте admin/config.php - он отдельный. Скорее всего, там неверный путь или URL. Структура файла аналогична корневому config.php.

- После переноса сайта на другой хостинг появился белый экран. При переносе меняются абсолютные пути. Откройте оба config.php и обновите все DIR_* значения под новый сервер.

- Как узнать абсолютный путь на хостинге? Создайте файл path.php с содержимым <?php echo DIR; и откройте его в браузере. Это и есть абсолютный путь к папке.

- OpenCart установился, но тема не отображается, сайт без стилей. Проверьте HTTP_SERVER в config.php - он должен совпадать с реальным URL сайта, включая https:// и слэш в конце.

- Установщик завис на шаге 3, ничего не происходит. Вероятно, PHP превысил max_execution_time. Установите в php.ini: max_execution_time = 300. Также проверьте доступность MySQL с данными из установщика.

- Ошибка 403 вместо белого экрана. Проблема с правами на файлы или директивой Options -Indexes в .htaccess. Убедитесь, что index.php присутствует и имеет права 644.

- Как переустановить OpenCart не удаляя базу данных? Восстановите папку install/, запустите установщик заново с теми же данными БД. Или вручную отредактируйте config.php.

- После обновления OpenCart белый экран. Обновление могло сломать модификации. В админке: Extensions → Modifications → Clear (очистить) → Refresh. Если не помогает - проверьте совместимость установленных расширений с новой версией.

Полезные советы и лучшие практики

Установите OpenCart локально с помощью XAMPP или Laragon, прежде чем загружать на хостинг. Так вы увидите все ошибки сразу и не будете тратить время на FTP.

Всегда делайте резервную копию config.php и базы данных перед любыми изменениями.

Используйте SSH вместо FTP - так проще управлять правами, видеть реальные логи и запускать команды.

Если хостинг не даёт менять версию PHP - смените хостинг. OpenCart требует конкретную версию, и это не то, с чем стоит бороться.

После исправления всех ошибок уберите display_errors = On из php.ini или index.php - открытый вывод ошибок опасен в production.

Логи OpenCart (system/storage/logs/error.log) и логи PHP - ваши главные инструменты диагностики. Проверяйте их первыми при любой проблеме.

Итоги

Белый экран при установке OpenCart почти всегда означает одно из следующего: несовместимая версия PHP, отсутствующее расширение, ошибка в config.php, неверные права на папки или не удалённая директория install/. Включите вывод ошибок, загляните в логи - и вы сразу увидите точную причину. Действуйте по шагам из этой статьи, и магазин запустится.