Частые вопросы и устранение неполадок

Последнее обновление: 22 сент. 2026 г. / Официальная архитектурная спецификация EpoCanvas

Если при использовании, написании или развёртывании EpoCanvas Docs возникла неполадка, сначала найдите её здесь. Вопросы упорядочены по цепочке «локальный запуск → написание документации → поиск → развёртывание»; для каждого указаны причина и проверенное решение.

1. Локальный запуск и установка

Q1: команда `pnpm run dev` сообщает, что порт 4321 занят

Причина: ранее запущенный сервер разработки завершился не полностью, либо порт 4321 занят другой программой.
Решение: запустите на другом порту:
Окно терминала
```
pnpm run dev -- --port 4322
```

Q2: при установке зависимостей возникает ошибка компиляции модуля Sharp

Причина: Sharp — низкоуровневый C++-модуль сжатия изображений на этапе сборки; после смены версии Node.js старый кэш может оказаться с ним несовместим.
Решение: очистите зависимости и установите заново:
Окно терминала
```
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

Q3: при выполнении `pnpm install` возникает ошибка `packages field missing or empty`

Причина: файл pnpm-workspace.yaml пуст или имеет неполный формат; pnpm интерпретирует его как конфигурацию workspace и выдаёт ошибку.
Решение: убедитесь, что файл содержит поле packages:
```
packages:
  - .
```

2. Написание документации и рендеринг

Q4: создан новый Markdown-файл, но в боковой панели слева его не видно

Причина: каталог боковой панели объявляется вручную; новый файл обязательно нужно зарегистрировать в конфигурации.
Решение: откройте astro.config.mjs и добавьте запись в подходящую группу массива sidebar:
```
{ label: 'Описание новой функции', link: '/canvas/new-feature/' }
```

Q5: в терминале возникает ошибка `"title" is required`

Причина: в заголовке Markdown пропущено поле title, либо открывающие три дефиса --- оформлены не по стандарту.

Решение: проверьте Frontmatter в самом начале файла:

---
title: Это заголовок статьи
description: Это описание статьи
---

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

Причина: в тексте документа написан ещё и заголовок первого уровня #. title из Frontmatter уже отрисовывается как крупный заголовок, поэтому # в тексте неизбежно даёт повтор.
Решение: удалите заголовок # из текста документа; разделы начинайте с ##. Полные правила — в разделе Подробно о правилах рендеринга.

Q7: написан `> [!TIP]`, но выноска не окрашивается, текст отображается как есть

Причина: синтаксис цитаты в стиле GitHub > [!TIP] не поддерживается — компилятор Markdown его не распознаёт.
Решение: используйте синтаксис с тройным двоеточием:
```
:::tip
Так писать правильно.
:::
```

Q8: вставленное изображение отображается как «битое»

Причина: путь к изображению указан неверно, либо изображение не помещено в статический каталог public/.
Решение:
1. Убедитесь, что изображение сохранено в public/images/canvas/ui-docs-reading.png;
2. Подключайте его абсолютным путём, начинающимся с /: ![описание](/images/canvas/ui-docs-reading.png); не пишите относительные пути вида ../public/....

3. Поиск

Q9: при локальной отладке через `pnpm dev` глобальный поиск не находит только что написанную статью

Причина: глобальный поиск зависит от индекса Pagefind, который создаётся только при pnpm run build; в режиме разработки диалог Ctrl+K не загружает индекс (открывается без поля ввода), поэтому глобальный поиск недоступен. Это ожидаемое поведение фреймворка, а не неисправность сайта.
Решение: выполните полную сборку и проверьте через сервер предпросмотра:
Окно терминала
```
pnpm run build
pnpm run preview
```
Поиск по странице в верхней панели от этого ограничения не зависит: при разработке им можно пользоваться для поиска по содержимому текущей страницы.

Q10: поиск по `Ctrl+K` не открывает всплывающее окно

Причина: горячую клавишу Ctrl+K / Cmd+K занимают некоторые средства ввода, утилиты буфера обмена или программы для скриншотов.
Решение: нажмите на маленький значок Ctrl K справа в поле поиска — он тоже открывает всплывающее окно поиска по всему сайту.

4. Развёртывание на Cloudflare Pages

Q11: только что привязанный собственный домен сообщает об ошибке SSL handshake (Error 525)

Причина: выдача Cloudflare сертификата Universal SSL для нового домена требует 2–5 минут на распространение по всему миру.
Решение: подождите несколько минут и обновите страницу жёстким обновлением (Ctrl+F5 / Cmd+Shift+R); в это время можно пользоваться доменом по умолчанию <имя проекта>.pages.dev — он доступен всегда.

Q12: команда `pnpm run deploy` выдаёт ошибку `Project not found`

Причина: параметр --project-name в команде развёртывания не совпадает с именем проекта в консоли Cloudflare; либо на этом компьютере не выполнен вход.
Решение:
1. Сначала выполните npx wrangler whoami, чтобы убедиться, что вы вошли;
2. Сверьте имя проекта в консоли Cloudflare и при необходимости исправьте параметр --project-name в скрипте deploy в package.json.

5. Самопроверка перед коммитом

Перед отправкой на GitHub выполните следующую команду для полной самопроверки (проверка типов + полная сборка):

pnpm exec astro check && pnpm run build

Если astro check выдаёт 0 errors, а сборка завершается сообщением Complete!, синтаксических ошибок в документации нет, и можно спокойно отправлять изменения. CI репозитория (build.yml) после отправки выполняет ту же сборку; локальная проверка помогает избежать падения CI.