Почему сайт не опубликовался: 6 причин и как починить

Почти все отказы публикации сводятся к шести причинам, и Tuqo в каждом случае пишет, что именно не так с вашим набором файлов, а не общее «нужен index.html». Ниже — эти шесть случаев с настоящими текстами ошибок и с тем, что делать. Если сайт опубликовался, но работает неправильно, это другая история — смотрите гайд что нейросети ломают в сайтах.

1. Вложенная папка: index.html не в корне

Самый частый случай на бою. Человек упаковал папку целиком, и всё лежит уровнем глубже: my-site/index.html вместо index.html.

В архиве один лишний уровень — не ошибка. Если в tar.gz или zip ровно один верхний каталог, Tuqo сам в него спускается и публикует содержимое. Проверено: архив, собранный командой tar czf site.tar.gz my-site, публикуется как есть.

Ошибка появляется, когда уровней два — my-site/dist/index.html, а в промежуточной папке больше ничего нет:

файлы сайта лежат во вложенной папке «dist», а нужны в корне. Упакуйте СОДЕРЖИМОЕ папки, а не саму папку: tar -czf site.tar.gz -C ./dist . — или просто перетащите папку в панель, там это учитывается автоматически.

А вот при отправке файлами вложенность не выпрямляется. Так работают агенты через MCP, REST и CLI: пути уходят как есть, и my-site/index.html в корне главной не даёт:

все файлы лежат во вложенной папке «my-site», а index.html нужен в корне. Перетащите саму папку «my-site» (её содержимое станет корнем) или уберите лишний уровень вложенности.

Если верхних папок несколько и в корне нет ни index.html, ни package.json, Tuqo перечислит, что именно приехало, — по списку сразу видно, что упаковали не то.

2. index.htm вместо index.html

Сайт открывается с /, а на этот адрес отдаётся ровно index.html. Файл с другим именем или другим регистром главной не станет:

главная страница должна называться ровно index.html, а в корне лежит «index.htm». Переименуйте файл и загрузите снова.

Если в корне есть другие HTML-страницы, но нет главной, текст скажет и это: «в корне есть html-страницы (about.html, contact.html), но нет index.html — с неё открывается сайт». Переименуйте главную.

3. Сжат один файл вместо архива папки

gzip index.html даёт файл index.html.gz — по магическим байтам это gzip, проверка на входе его пропускает, а внутри нет структуры tar:

не удалось распаковать архив: внутри нет структуры tar. Похоже, сжат один файл, а не папка. Соберите архив из СОДЕРЖИМОГО папки сайта: tar -czf site.tar.gz -C ./папка . — или просто перетащите папку в панель. Подойдёт и .zip.

Принимаются два формата: tar.gz и zip. Всё остальное отсекается сразу: «архив не распознан — принимаются tar.gz и zip». Zip, кстати, надёжнее: его по умолчанию делают Windows и большинство нейросетей.

4. Сборка не дала результата

Если в корне архива есть package.json, Tuqo считает набор сборочным проектом и запускает сборку на Node 20: npm ci при наличии lock-файла (иначе npm install), затем npm run build. Два типичных отказа:

• В package.json нет скрипта build. Сборка падает на команде npm run build — в логе будет ошибка npm про отсутствующий скрипт. Добавьте скрипт или укажите свою команду сборки в настройках.

• Результат лежит не там, где его ищут.

  сборка прошла, но каталог с готовым сайтом не найден. Ищем dist, build, out, _site, public, site, .vitepress/dist, .output/public, storybook-static. Если ваш стек кладёт результат в другое место — укажите каталог вывода в настройках Git CD или загрузите готовую папку.

Обратная ситуация — вы публикуете готовый сайт файлами, а в наборе случайно остался package.json. Тогда придёт: «обнаружен package.json в корне — это сборочный проект. Для статики уберите его, для сборки используйте deploy_site (архив с исходниками)».

5. Упёрлись в лимит

Потолки разные у разных путей публикации:

• папкой в панели — до 2000 файлов и примерно 36 МБ. Панель прямо подскажет: «Суммарно 48.2 МБ — для загрузки папкой лимит ~36 МБ. Соберите tar.gz/zip (до 50 МБ) или используйте CLI: npx @tuqo/cli deploy»;
• архивом в панели, через REST и MCP deploy_site — 50 МБ, иначе «архив исходников превышает 50 MB»;
• CLI — до 2000 файлов, до 50 МБ на файл, суммарно в пределах памяти тарифа. Лимита на размер тела запроса нет: файлы уходят поштучно.

Отдельная частая история — «слишком много файлов»: в архив уехал node_modules или папка с исходниками. Публикуйте готовую сборку, а не проект целиком. Тяжёлые сайты с фото — через CLI, см. гайд про обновление без перезаливки.

6. Служебные файлы и __tuqo/

Часть путей не публикуется никогда, и это не ошибка — их просто выбрасывают из набора: .git, .hg, .svn, .bzr, .env (и .env.local, .env.production), .ssh, .aws, .gnupg, .docker, .kube, .config, .netrc, .npmrc, .pypirc, .htpasswd, .htaccess, .DS_Store. Проверяется каждый сегмент пути, регистр не важен: frontend/.env.local тоже отсеется.

Отдельно — префикс __tuqo/: он зарезервирован платформой, там живут служебные страницы (вход по паролю, выдача файлов). Файл сайта по такому пути не раздастся, поэтому он не публикуется вовсе.

Если в наборе не осталось ничего, кроме служебного, вы увидите отказ про отсутствующий index.html. Агентам список выброшенного возвращается полем skipped_paths — присылать эти файлы снова не нужно.

Частые вопросы

Как правильно собрать архив?

tar -czf site.tar.gz -C ./dist . — точка в конце означает «содержимое каталога». Или zip -r site.zip . изнутри папки сайта. Проверить можно так: tar -tzf site.tar.gz | head — в списке должно быть ./index.html, а не dist/index.html.

Деплой прошёл, но сайт отдаёт 404

Значит, index.html не оказался в корне артефакта либо сайт выключен в настройках. На SPA с клиентским роутингом 404 при обновлении страницы лечится иначе — есть отдельный гайд.

Где посмотреть, почему упала сборка?

Вкладка «Деплои» → неудачный деплой: там статус и текст ошибки (последние строки лога). Через MCP то же самое отдаёт get_logs(deploy_id).

Можно ли откатиться, если новая версия сломалась?

Да, если тариф хранит больше одной версии: вкладка «Деплои» → «Откатить сюда». Подробно — в гайде как откатить сайт.

Документация → · Проверки при публикации →