Файл .htaccess в Apache: настройка и поиск ошибок

.htaccess — файл с настройками Apache HTTP Server, которые действуют для одного каталога сайта и его подкаталогов. Он нужен прежде всего на виртуальном хостинге, где владелец сайта не может редактировать общую конфигурацию сервера.

Если вы управляете VPS и имеете доступ к конфигурации виртуального хоста Apache, правила лучше хранить там. Apache читает основную конфигурацию при запуске, а поиск .htaccess в каталогах выполняется во время обработки запросов. Nginx этот файл вообще не читает.

Убедитесь, что сайт действительно обслуживает Apache

Наличие .htaccess в архиве WordPress не доказывает, что активный веб-сервер его применяет. На хостинге название сервера обычно указано в панели или документации. На собственном Linux-сервере проверьте запущенные службы:

systemctl --type=service --state=running |
  grep -E 'apache2|httpd|nginx'

Команда только читает список служб. В Debian и Ubuntu Apache обычно называется apache2, в Fedora и совместимых системах — httpd. Nginx может стоять перед Apache как reverse proxy, поэтому одного имени процесса недостаточно: посмотрите конфигурацию панели или маршрутизацию запроса.

Если сайт обслуживает Nginx без Apache, переносите нужную логику в блоки server и location. Попытка «включить поддержку .htaccess» в Nginx ведёт не туда: такого механизма у него нет.

Найдите корень именно этого сайта

Файл действует от каталога, в котором находится. Для основного домена это обычно document root — папка, где лежит входной index.php или index.html. Точный путь смотрите в панели хостинга или директиве DocumentRoot виртуального хоста.

Имя начинается с точки, поэтому файловый менеджер может скрывать файл. В терминале покажите скрытые объекты так:

ls -la /var/www/example/public/

Замените путь настоящим document root. Команда ничего не меняет. Если .htaccess нет, не копируйте случайный файл из интернета: сначала сформулируйте одно нужное правило и уточните, разрешено ли оно хостингом.

Перед редактированием сохраните копию с понятным временем:

cp -a .htaccess .htaccess.before-change

Запускайте команду из корня сайта. -a сохраняет основные атрибуты. Проверьте появление копии через ls -la .htaccess*. Файл резервной копии тоже находится в web-каталоге, поэтому после успешной проверки перенесите его за пределы document root или удалите: веб-сервер не должен раздавать конфигурационные копии.

От чего зависит набор разрешённых правил

Администратор Apache управляет .htaccess директивами AllowOverride и AllowOverrideList. Значение AllowOverride None полностью отключает обработку файла. Другие значения разрешают группы настроек, например FileInfo для перенаправлений и rewrite-правил.

На виртуальном хостинге эти параметры меняет провайдер. Если директива запрещена, посетитель обычно получает HTTP 500, а в журнале появляется сообщение вроде not allowed here. Не пытайтесь обойти ограничение: выберите поддерживаемую директиву или обратитесь в поддержку.

На собственном сервере разрешайте только необходимые группы для конкретного каталога. AllowOverride All удобно, но передаёт приложению больше контроля над веб-сервером, чем обычно требуется.

Сделайте простой постоянный редирект

Для переноса одной старой страницы на новую достаточно директивы модуля mod_alias. Добавьте в корневой .htaccess:

Redirect permanent /old-page/ /new-page/

Первый путь — старый URL относительно домена, второй — новый. permanent формирует постоянный ответ 301. Не используйте 301 для временного эксперимента: браузеры и поисковые системы могут запомнить его. Для временного переноса укажите temp, что соответствует коду 302.

Проверьте заголовки без загрузки тела страницы:

curl -I https://example.com/old-page/

Запускайте команду со своего компьютера и замените домен. Ожидайте статус 301 и заголовок Location с новым адресом. Затем откройте новый URL и убедитесь, что он отвечает успешно. Если запрос циклически возвращается на исходную страницу, сразу восстановите прежний файл.

Для множества условий применяют mod_rewrite, но простое перенаправление не стоит усложнять регулярным выражением. Чем короче правило, тем легче проверить его область действия.

Настройте собственную страницу 404

Создайте обычную страницу /404.html, доступную по прямому адресу, а затем укажите её в .htaccess:

ErrorDocument 404 /404.html

Путь начинается с / и относится к текущему сайту. Не указывайте здесь несуществующую страницу, иначе обработка ошибки сама вызовет ещё одну ошибку.

Проверяйте адресом, которого заведомо нет:

curl -I https://example.com/definitely-missing-page-48271

Тело должно быть вашим, но статус обязан остаться 404 Not Found. Если сервер отвечает 200 OK, поисковые системы увидят мягкую 404: пользователь читает сообщение об отсутствии страницы, а протокол утверждает, что документ найден.

Поймите, почему правила RewriteRule выглядят иначе

В .htaccess Apache уже убирает путь текущего каталога перед сопоставлением RewriteRule. Поэтому правило в корне сайта обычно не начинается с /.

Например, это временно перенаправит только /docs/start на /guide/:

RewriteEngine On
RewriteRule ^docs/start$ /guide/ [R=302,L]

RewriteEngine On включает механизм переписывания. Выражение ^docs/start$ совпадает со всем относительным путём, а флаги означают временный редирект (R=302) и прекращение обработки следующих правил после совпадения (L).

Сначала используйте 302 и проверьте разные адреса: старый, новый, соседнюю страницу и файл изображения. Меняйте код на 301 только когда уверены, что условие не захватывает лишние URL.

Не вставляйте готовую схему перенаправления HTTP на HTTPS без понимания инфраструктуры. За CDN или балансировщиком Apache может видеть внутреннее HTTP-соединение, даже когда посетитель пришёл по HTTPS; неверное условие создаст бесконечный цикл. Для настройки HTTPS учитывайте, на каком узле завершается TLS и каким заголовкам можно доверять.

Не ломайте автоматически созданный блок WordPress

WordPress записывает rewrite-правила между комментариями # BEGIN WordPress и # END WordPress. Плагины или сохранение структуры постоянных ссылок могут пересоздать этот участок.

Собственные редиректы размещайте вне автоматически управляемого блока и храните копию. Если нужна логика приложения, сначала проверьте, не решается ли задача настройкой WordPress или плагина: два конкурирующих набора правил трудно диагностировать.

Найдите причину ошибки 500

Если после сохранения сайт отвечает 500 Internal Server Error, первым делом верните прежнюю версию:

cp -a .htaccess.before-change .htaccess

Команда перезаписывает текущий файл сохранённой копией, поэтому выполняйте её только в том каталоге, где сделали резервную копию. После возврата снова откройте сайт.

Затем прочитайте журнал ошибок. На собственном сервере путь зависит от дистрибутива и виртуального хоста; часто удобнее журнал службы:

journalctl -u apache2 --since '10 minutes ago' --no-pager

В системах с сервисом httpd замените имя. На виртуальном хостинге журнал ошибок обычно доступен в панели. Ищите точное имя файла, номер строки и текст вроде Invalid command, not allowed here или ошибку регулярного выражения.

Если есть доступ к основной конфигурации, проверяйте её перед reload:

sudo apachectl configtest

Ожидаемый результат — Syntax OK. Эта проверка не гарантирует правильную бизнес-логику редиректа, но обнаруживает синтаксические ошибки доступной Apache конфигурации. При ошибке не перезапускайте службу; исправьте указанную строку и повторите тест.

Проверяйте одно изменение за раз

Надёжный цикл работы выглядит так:

1. Записать ожидаемый URL и HTTP-статус.
2. Сохранить прежний файл вне web-каталога.
3. Добавить одно правило.
4. Проверить старый, новый и соседний URL через curl -I.
5. Прочитать error log, даже если страница визуально открылась.
6. Только после этого переходить к следующему правилу.

Так проще понять, какая строка вызвала ошибку. Большой набор из генератора .htaccess может содержать несовместимые директивы, дублировать настройки приложения и создавать редиректы, которые проявятся только на части страниц.

Источники

• Apache HTTP Server: руководство по .htaccess
• Apache HTTP Server: директива AllowOverride
• Apache HTTP Server: URL Rewriting Guide
• Apache HTTP Server: директива Redirect