Исправление неработающих ссылок навигации после развертывания на Vercel/GitHub Pages

Ссылки навигации не работают после развертывания, потому что относительные пути ведут себя по-разному в статических хостинговых средах, таких как GitHub Pages и Vercel, по сравнению с локальной разработкой. Когда вы используете ../ в HTML, он разрешается относительно расположения текущего файла во время разработки, но после развертывания структура файлов и базовый URL полностью меняются, из-за чего эти относительные ссылки указывают на неправильные местоположения.

Содержание

• Понимание основной причины
• Проблемы, специфичные для GitHub Pages
• Особенности развертывания на Vercel
• Эффективные решения
• Лучшие практики для развертывания статических сайтов

Понимание основной причины

Основная проблема заключается в том, как относительные пути разрешаются по-разному между локальной разработкой и платформами статического развертывания. Когда вы используете ../Welcome/index.html в навигации, браузер интерпретирует это как “перейти на один каталог вверх от текущего файла, затем в каталог Welcome”.

Однако при развертывании на GitHub Pages или Vercel:

• Ваш сайт находится на другом базовом URL (например, xyz.github.io/your-repo/)
• Структура файлов может обслуживаться из другого пути
• Разрешение относительных путей больше не соответствует ожидаемой структуре каталогов

Как отмечено в исследованиях, GitHub Pages использует определенную структуру URL https://{org}.github.io/{repo}/, что влияет на работу относительных путей [источник]. Это означает, что относительный путь, который работал локально, может разрешиться до xyz.github.io/Welcome/index.html вместо правильного xyz.github.io/your-repo/Welcome/index.html.

Проблемы, специфичные для GitHub Pages

GitHub Pages имеет несколько характеристик, которые часто нарушают относительные ссылки:

Несоответствие структуры URL

GitHub Pages обслуживает ваш сайт с адреса https://username.github.io/repository-name/, а не с корня домена. Это создает несоответствие при использовании относительных путей, которые не учитывают имя репозитория в URL.

Рассмотрения базового пути

При развертывании на GitHub Pages базовый URL вашего сайта имеет следующую структуру: https://{org}.github.io/{repo} [источник]. Относительная ссылка вроде ../Welcome/index.html со страницы в вашем репозитории может разрешиться до xyz.github.io/Welcome/index.html вместо правильного xyz.github.io/your-repo/Welcome/index.html.

Обслуживание статических ресурсов

GitHub Pages обслуживает статические файлы напрямую, и из-за относительных путей вы можете либо разместить ресурсы на вашем username.github.io/project-name, либо на вашем кастомном домене [источник]. Это создает конфликты, когда ваши относительные пути не учитывают структуру каталога проекта.

Особенности развертывания на Vercel

Vercel представляет схожие, но немного разные проблемы:

Переписывание путей

Согласно документации Next.js, экземпляр NGINX добавляет базовый элемент в head страницы, так что каждый URL предваряется нашим базовым путем [источник]. Это означает, что ваши относительные пути могут быть перезаписаны неожиданным образом.

Проблемы с кастомными доменами

Некоторые пользователи сообщают, что проблемы с относительными путями возникают при доступе через кастомное доменное имя в Vercel, но проблем нет при доступе через GitHub URL [источник]. Это указывает на то, что конфигурация базового пути может отличаться между предоставленным GitHub URL и вашим кастомным доменом.

Особенности поведения Next.js

Если вы используете Next.js, могут возникнуть дополнительные сложности маршрутизации. В исследованиях упоминаются проблемы с относительными ссылками с перезаписанными путями с использованием next/link, где навигация идет по неправильному пути [источник].

Эффективные решения

Вот несколько подходов для исправления ссылок навигации:

1. Использование путей, относительных к корню

Измените ваши относительные пути на пути, относительные к корню, начав их с /:

<div class="nav-links">
    <span class="material-symbols-outlined" id="closeMenu">close</span>
    <a href="/Welcome/index.html" class="navurl navpart">Welcome</a>
    <a href="/Overview/overview.html" class="navurl navpart">Overview of Experiment</a>
    <a href="/Simulation/simulation.html" class="navurl navpart">Simulation</a>
    <a href="/Photos/photos.html" class="navurl navpart">Photos</a>
</div>

Пути, относительные к корню, начинаются с корня вашего сайта и работают последовательно в разных средах развертывания.

2. Реализация тега Base Href

Добавьте тег <base> в head вашего HTML, чтобы указать базовый URL для всех относительных ссылок:

<head>
    <base href="/your-repo-name/">
</head>

Это гарантирует, что все относительные пути будут разрешаться относительно корня вашего репозитория. Решение <base href="/[repo]/"> применяется только к относительным URL, а не к тем, которые являются абсолютными по пути [источник].

3. Использование абсолютных URL с переменными окружения

Для максимальной надежности используйте абсолютные URL, которые адаптируются к среде развертывания:

<head>
    <script>
        const baseUrl = window.location.origin + '/your-repo-name/';
    </script>
</head>

<div class="nav-links">
    <span class="material-symbols-outlined" id="closeMenu">close</span>
    <a href="${baseUrl}Welcome/index.html" class="navurl navpart">Welcome</a>
    <a href="${baseUrl}Overview/overview.html" class="navurl navpart">Overview of Experiment</a>
    <a href="${baseUrl}Simulation/simulation.html" class="navurl navpart">Simulation</a>
    <a href="${baseUrl}Photos/photos.html" class="navurl navpart">Photos</a>
</div>

4. Создание файла 404.html

Для GitHub Pages добавьте новую страницу с именем 404.html в ваш репозиторий [источник]. Это может помочь с проблемами маршрутизации и обеспечить лучшее поведение отката.

Лучшие практики для развертывания статических сайтов

Согласованность структуры каталогов

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

Тестирование путей

Перед развертыванием протестируйте ваши пути, выполнив:

1. Открытие HTML-файлов напрямую в браузере (протокол file://)
2. Обслуживание локально с помощью простого веб-сервера
3. Проверку того, как пути разрешаются в каждой среде

Разрешение путей на этапе сборки

Рассмотрите возможность использования инструмента сборки или генератора статических сайтов, который может автоматически исправлять пути в процессе сборки. Многие инструменты, такие как Hugo, Jekyll или Eleventy, имеют встроенную обработку проблем с путями развертывания.

Осведомленность о среде развертывания

Помните, что разные платформы развертывания имеют разное поведение:

• GitHub Pages: Всегда обслуживает с username.github.io/repo-name/
• Vercel: Может обслуживать с кастомных доменов или проектных URL
• Netlify, Cloudflare Pages и т.д.: У каждой есть свои собственные поведения маршрутизации

Ключевое замечание: Иногда вы можете видеть пути, относительные к корню, неправильно называемые абсолютными ссылками. Технически это неверно, потому что абсолютная ссылка всегда начинается со схемы/протокола (https://). Путаница возникает из-за того, что пути, относительные к корню, являются абсолютными в отношении части пути URL [источник].

Заключение

Проблемы со ссылками навигации, с которыми вы столкнулись, являются распространенными при развертывании статических сайтов на платформах, таких как GitHub Pages и Vercel. Основная проблема заключается в том, что относительные пути ведут себя по-разному в производственных средах по сравнению с локальной разработкой.

Ключевые выводы:

1. Пути, относительные к корню (начинающиеся с /) более надежны, чем ссылки на родительские каталоги (../)
2. Теги base href могут помочь стандартизировать разрешение путей в разных средах
3. Абсолютные URL обеспечивают наиболее последовательное поведение, но требуют больше обслуживания
4. Структура каталогов должна быть согласована между локальной разработкой и развертыванием

Рекомендуемое действие: Начните с преобразования ваших путей ../ в пути, относительные к корню (начиная с /), что должно решить большинство ваших проблем. Если проблемы сохраняются, рассмотрите возможность реализации тега base href или использования инструментов разрешения путей на этапе сборки.

Для постоянного обслуживания установите процесс тестирования, который включает локальное обслуживание и среды предварительного просмотра развертывания, чтобы выявлять проблемы с путями на ранних этапах вашего рабочего процесса разработки.

Источники

1. GitHub Pages and relative paths - Stack Overflow
2. Fixing Broken Relative Links on GitHub Pages | Pluralsight
3. Deploying to Github Pages? Don’t Forget to Fix Your Links - Maxim Orlov
4. Use relative URLs instead of absolute · vercel/next.js
5. Relative path problem · vercel/vercel · Discussion
6. Dealing with Relative Paths on gh-pages