brepo/ngx_http_apache_rewrite_module
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
ceb3e2eff6bcc7b834080bafde0ee30f0302ba19
ngx_http_apache_rewrite_module/README.ru.md
alexey ceb3e2eff6 Documentaion fixes
2026-03-23 15:11:12 +03:00

19 KiB
Raw Blame History

Модуль совместимости Apache mod_rewrite для Nginx

Этот модуль обеспечивает совместимость Apache mod_rewrite для Nginx, позволяя использовать файлы .htaccess и стандартные правила переписывания.

Директивы конфигурации

Ниже перечислены доступные директивы в этом модуле:

1. RewriteEngine

Назначение: Включить или отключить механизм переписывания.

Контекст Доступные уровни
main, server, location ✓ Поддерживаются все три уровня

Синтаксис:

RewriteEngine on|off

Возможные значения:

  • on - Включить механизм переписывания
  • off - Отключить механизм переписывания (по умолчанию)

Пример в nginx.conf:

http {
    server {
        RewriteEngine on;

        location /blog/ {
            # Правила применяются здесь
        }

        location /static/ {
            RewriteEngine off;  # Отключить для этой локации
        }
    }
}

2. RewriteRule

Назначение: Определить правило переписывания, которое сопоставляет шаблон URL и заменяет его новым значением.

Контекст Доступные уровни
server, location ✓ Уровни сервера и локации
.htaccess ✓ Поддерживается в файлах .htaccess

Синтаксис:

RewriteRule pattern substitution [flags]

Параметры:

  • pattern - Регулярное выражение для сопоставления URL (поддерживаются обратные ссылки $1, $2 и т.д.)

    • Паттерн может быть префиксирован ! для отрицания
    • - в качестве замены означает "нет замены" (только проверка условий)

  • substitution - Целевой URL или путь файла для переписывания

    • Может быть относительным путем (/new/path) или абсолютным перенаправлением (http://example.com/new)

Флаги: [flag1,flag2,...] (необязательно):

Флаг Короткая запись Описание
B - Экранировать обратные ссылки в выводе (предотвратить проблемы с кодировкой URL)
C Chain Присоединить это правило к следующему (требует предыдущего совпадения)
D DPI Отбросить информацию о пути после замены
E Env=var:val Установить переменную окружения для последующего использования (FastCGI интеграция)
F Forbidden Вернуть статус HTTP 403 Forbidden
G Gone Вернуть статус HTTP 410 Gone
L Last Остановить обработку правил после этого
N Next=limit Цикл (повторить) до N раз для предотвращения бесконечных переписываний
P Proxy Проксировать запрос внутренне (Фаза 2)
Q QSA Прикрепить исходную строку запроса к URL замены
Q QSD Удалить исходную строку запроса
Q QSL Установить маркер "query string last"
R Redirect=code Выполнить внешнее перенаправление со статусом (301, 302, 307) или: Permanent, Temp, SeeOther
S Skip=N Пропустить N последующих правил после этого
T Type=mime Принудительно установить MIME-тип для ответа
NC - Непрерывное сопоставление без учета регистра
NOESCAPE - Не экранировать специальные символы в выводе
END - Остановить все переписывания и перейти к фазе контента

Пример:

# Перенаправление /old-path/ в /new-path/ (постоянное перенаправление)
RewriteRule ^old-path/(.*)$ /new-path/$1 [R=301,L]

# Условное переписывание (цепочка)
RewriteCond %{REQUEST_URI} !^/admin/
RewriteRule ^admin/(.*)$ /login.php?user=$1 [NC,E,END]

# В .htaccess:
RewriteEngine on
RewriteCond %{HTTP_HOST} ^www\.example\.com$ [OR]
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://example.com/$1 [R=301,L]

3. RewriteCond

Назначение: Определить условия, которые должны быть выполнены, прежде чем будет применено правило RewriteRule. Множественные условия объединяются по умолчанию (AND); можно изменить это с помощью флага OR.

Контекст Доступные уровни
server, location ✓ Уровни сервера и локации
.htaccess ✓ Поддерживается в файлах .htaccess

Синтаксис:

RewriteCond input_string pattern [flags]

Параметры:

  • input_string - Переменная или строка для проверки (например, %REQUEST_URI, %HTTP_HOST, %REQUEST_METHOD, %REQUEST_FILENAME)

    • Общие переменные: REQUEST_URI, HTTP_HOST, REQUEST_METHOD, REQUEST_FILENAME

  • pattern - Шаблон проверки:

    • Тесты файлов: -f (файл существует), -d (директория существует), -x (исполняемый), -s (не нулевой размер)
    • Тесты ссылок: -h или -l (жёсткая/мягкая ссылка), -L (цель ссылки существует)
    • Сравнение целых чисел: -lt, -le, -eq, -gt, -ge, -ne
    • Сравнение строк: =, >, <, >=, <=
    • Регулярные выражения: любой шаблон regex

  • flags (необязательно):

    • NC - Не чувствительно к регистру
    • OR / ornext - Логика OR между условиями (вместо AND)

Примеры:

# Условие: файл существует
RewriteCond %{REQUEST_FILENAME} -f

# Условие: не директория
RewriteCond %{REQUEST_FILENAME} !-d

# Сравнение строк
RewriteCond %{HTTP_HOST} ^www\.example\.com$ [NC]

# Множественные условия с OR
RewriteCond %{HTTP_HOST} ^www\.example\.com$ [OR]
RewriteCond %{HTTPS} off

# Регулярный шаблон
RewriteCond %{REQUEST_URI} ^/old/(.*)$

4. RewriteBase

Назначение: Установить базовый URL-путь для относительных замен в правилах переписывания.

Контекст Доступные уровни
location ✓ Только уровень локации
.htaccess ✓ Поддерживается в файлах .htaccess

Синтаксис:

RewriteBase /path/

Параметры:

  • Должен начинаться с / и заканчиваться / (обязательный слеш)

Пример:

# Внутри конкретной локации
location /blog/ {
    RewriteBase /blog/

    # Относительная замена разрешается: /blog/news.html
    RewriteRule ^news\.html$ news.php [L]
}

# В .htaccess:
RewriteEngine on
RewriteBase /subdir/
RewriteRule ^index\.html$ home.php [L]

5. RewriteOptions

Назначение: Настроить параметры поведения переписывания, которые влияют на наследование правил и порядок их обработки.

Контекст Доступные уровни
main, server, location ✓ Все три уровня поддерживаются

Синтаксис:

RewriteOptions option1 [option2 ...]

Возможные опции:

Опция Описание
Inherit Наследовать правила из родительских локаций/серверов (поведение по умолчанию)
InheritBefore Обрабатывать правила родительских локаций до правил дочерних

Пример:

http {
    server {
        RewriteOptions Inherit

        location /parent/ {
            RewriteRule ^parent/(.*)$ /new/$1 [L]
        }

        location /child/ {
            # Наследует правила от родителя по умолчанию с опцией 'Inherit'
            RewriteBase /child/
        }
    }
}

6. RewriteMap

Назначение: Определить имя‑значение карты для поиска таблиц в выражениях переписывания.

Контекст Доступные уровни
server ✓ Только уровень сервера
.htaccess ✗ Не поддерживается в .htaccess

Синтаксис:

RewriteMap name type:source

Параметры:

  • name - Идентификатор карты (используется как переменная, например %MAPNAME:value)
  • type - Тип карты:
    • int - Внутренняя функция (поддерживаемые: tolower, toupper, escape, unescape)
    • txt - Поиск по текстовому файлу (пока не реализовано)
    • rnd - Поиск по случайному (пока не реализовано)
    • prg - Поиск по программе (пока не реализовано)

Пример:

server {
    # Карта к нижнему регистру имени хоста
    RewriteMap lc int:tolower

    server_name example.com;

    location / {
        # Использовать сопоставленное значение в правиле
        RewriteRule ^lc/([^/]+)$ /redirect/$1 [L]
    }
}

# Использование в правилах:
RewriteRule ^(.*)$ /%lc:$1 [L]

7. HtaccessEnable

Назначение: Включить или отключить разбор файлов .htaccess для сервера/локации.

Контекст Доступные уровни
main, server ✓ Только уровни основного и сервера
.htaccess ✗ Не поддерживается в .htaccess

Синтаксис:

HtaccessEnable on|off

Параметры:

  • on - Включить разбор .htaccess
  • off - Отключить разбор .htaccess (по умолчанию)

Пример:

http {
    server {
        HtaccessEnable on

        # Файлы .htaccess будут искаться вверх от пути запроса
        location /subdir/ {
            root /var/www/html;
        }
    }
}

# В nginx.conf, можно включить на уровне http:
http {
    HtaccessEnable on;

    server {
        # Наследует настройку из уровня http
    }
}

8. HtaccessName

Назначение: Указать альтернативное имя файла для файлов .htaccess.

Контекст Доступные уровни
main, server ✓ Только уровни основного и сервера
.htaccess ✗ Не поддерживается в .htaccess

Синтаксис:

HtaccessName filename

Параметры:

  • Любая строка (по умолчанию .htaccess)

Пример:

server {
    HtaccessName .webconfig

    # Будет искать файлы .webconfig вместо .htaccess
    location / {
        root /var/www/html;
    }
}

# В .htaccess:
HtaccessEnable on
HtaccessName .custom_htac

9. RewriteFallBack

Назначение: Указать альтернативный путь отката, если переписанный файл не существует (вместо стандартного /index.php). Эта директива может использоваться только в файлах .htaccess и читается функцией ngx_htaccess_parse_file_from_ha(). Путь отката кэшируется для каждого запроса и извлекается в ngx_http_apache_rewrite_url_register_hook_with_fallback().

Контекст Доступные уровни
.htaccess ✓ Поддерживается только в файлах .htaccess

Синтаксис:

RewriteFallBack /path/to/fallback.php

Параметры:

  • Путь должен начинаться с / (обязательно)
  • По умолчанию путь отката – /index.php, если не указан

Пример в .htaccess:

# Использовать пользовательский откат, если файл не найден
RewriteFallBack /custom/app.php

# Откат перенаправит на /custom/app.php?query_string вместо /index.php
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php [QSA,L]

Пример с параметром строки запроса:

RewriteFallBack /handler.php?lang=ru

# Если файл не существует, запрос будет перенаправлен на путь отката
# с сохранением исходной строки запроса, если она присутствует

Сводка уровней конфигурации

Директива http/main server location .htaccess
RewriteEngine ✓ ✓ ✓ ✓
RewriteRule - ✓ ✓ ✓
RewriteCond - ✓ ✓ ✓
RewriteBase - - ✓ ✓
RewriteOptions ✓ ✓ ✓ -
RewriteMap - ✓ - -
HtaccessEnable ✓ ✓ - -
HtaccessName ✓ ✓ - -
RewriteFallBack ✗ ✗ - ✓

Формат файла .htaccess

Файлы .htaccess следуют формату Apache:

# Комментарии начинаются с #
RewriteEngine on

RewriteCond %{REQUEST_URI} ^/old/(.*)$
RewriteRule ^old/(.*)$ /new/$1 [R=301,L]

# Множественные условия (логика AND по умолчанию)
RewriteCond %{HTTP_HOST} www\.example\.com$
RewriteCond %{HTTPS} off
RewriteRule (.*) https://www.example.com/$1 [R=301,L]

RewriteBase /subdir/
RewriteFallBack /custom/fallback.php
RewriteCond !-f
RewriteCond !-d
RewriteRule ^(.*)$ index.php?route=$1 [QSA,L]

Если после переписывания URL файл не существует, модуль переходит к:

  1. Путь RewriteFallBack, если указан в .htaccess, или
  2. /index.php как стандартный откат

---


## Возможности модуля

### Интеграция с FastCGI
Модуль автоматически передаёт переменные окружения (установленные через флаги `[E=VAR:VAL]`) в приложения FastCGI без дополнительной настройки.

### Переменные окружения
Переменные окружения сохраняются между фазами запроса и доступны downstream-модулям.

### Кэширование .htaccess
Файлы `.htaccess` кэшируются по времени изменения в памяти запроса, чтобы ускорить повторные запросы.

### Директива RewriteFallBack
Директива `RewriteFallBack` позволяет настроить путь отката, который используется, когда переписанный файл не существует:

1. **Кеширование:** Путь отката из `.htaccess` кэшируется на каждый запрос, чтобы избежать повторного разборов.
2. **Логика отката:** Когда `try_files` завершается неудачей, модуль перенаправляет на заданный откат вместо `/index.php`.
3. **Сохранение строки запроса:** Исходная строка запроса сохраняется и добавляется к пути отката.

Заметки

  • Правила переписывания обрабатываются в порядке, определенном в конфигурации или файлах .htaccess
  • Флаг [L] останавливает обработку на текущем правиле
  • Флаг [N] включает цикл для предотвращения бесконечных перенаправлений (максимум 10 000 раундов)
  • Правила уровня локации переопределяют правила уровня сервера, если не задана опция Inherit
Reference in New Issue View Git Blame Copy Permalink