Гайды

Как добавить экспорт в CSV — и почему Excel показывает кракозябры

Иллюстрация: таблица данных вытекает из приложения одним файлом

Кнопка «Скачать CSV» — одна из тех штук, которые ИИ пишет за десять секунд, а потом ты полдня разбираешься, почему бухгалтер прислал скриншот с иероглифами.

Файл вроде правильный. Открывается в блокноте нормально. А в Excel вместо «Заказ №12» — «Ð—аказ». Виноват один невидимый символ, которого в файле нет.

Разберём по шагам — и сразу с ловушками.

Шаг 1. Реши, где собирать файл

Два варианта, и выбор простой.

  • На клиенте (в браузере). Данные уже загружены на страницу, экспорт — это просто «сохрани то, что видишь». Ничего не нужно на сервере, работает мгновенно.
  • На сервере. Строк много (десятки тысяч), или в выгрузку должны попасть данные, которых нет на экране. Тогда браузер просто скачивает ответ эндпоинта.

Начни с клиента. Если строк меньше пары десятков тысяч — этого хватит с запасом.

Шаг 2. Собери строки в массив массивов

Никаких «склеим через запятую в цикле». Сначала — плоская структура: первый массив — заголовки, дальше по массиву на строку. Если данные приходят из базы как объекты, преврати их в массивы явно — так ты сам решаешь порядок колонок, а не полагаешься на порядок ключей.

const rows = [
  ["Дата", "Клиент", "Комментарий", "Сумма"],
  ["2026-08-12", "Аня", 'Сказала: "беру два"', 4990],
];

Обрати внимание на комментарий во второй строке. В нём кавычки — и именно на таких значениях ломается наивный экспорт.

Шаг 3. Экранируй значения по правилам CSV

Это главный шаг. У CSV есть стандарт (RFC 4180), и правил в нём всего три:

  • если в значении есть запятая, кавычка или перенос строки — всё значение оборачивается в двойные кавычки;
  • кавычка внутри значения удваивается: " превращается в "";
  • строки разделяются переносом \r\n.

Функция на шесть строк, которая делает всё это:

function toCsv(rows) {
  const esc = (v) => {
    const s = v === null || v === undefined ? "" : String(v);
    return /[",\r\n]/.test(s) ? `"${s.replaceAll('"', '""')}"` : s;
  };
  return rows.map((r) => r.map(esc).join(",")).join("\r\n");
}

Проверь на своём приложении: если в данных есть текстовые поля, которые пишут пользователи, там обязательно окажутся запятые и переносы строк. Без экранирования один отзыв разъедет на пять колонок и сдвинет всю таблицу.

Шаг 4. Добавь BOM — тот самый невидимый символ

А вот и разгадка кракозябр. Excel при двойном клике по .csv не спрашивает кодировку, а угадывает её — и по умолчанию угадывает системную однобайтовую, а не UTF-8. Кириллица превращается в мусор.

Лечится добавлением в самое начало файла символа \uFEFF — метки порядка байтов (BOM). Он невидимый, размером в пару байт, и Excel по нему сразу понимает: тут UTF-8.

const csv = "\uFEFF" + toCsv(rows);

Одна строка — и проблема, на которую уходят часы, исчезает.

Шаг 5. Отдай файл на скачивание

На клиенте — через Blob и обычную ссылку:

const blob = new Blob([csv], { type: "text/csv;charset=utf-8" });
const a = document.createElement("a");
a.href = URL.createObjectURL(blob);
a.download = `orders-${new Date().toISOString().slice(0, 10)}.csv`;
a.click();
URL.revokeObjectURL(a.href);

Дата в имени файла — мелочь, за которую тебе скажут спасибо: в папке «Загрузки» не будет десяти файлов export (3).csv.

Если собираешь на сервере — отдай два заголовка, остальное сделает браузер:

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="orders-2026-08-12.csv"

Шаг 6. Проверь в трёх местах

CSV — формат-обманка: он «работает» ровно до тех пор, пока ты не открыл его чем-то другим. Проверь выгрузку в Excel, в Google Sheets и в Numbers, если под рукой мак. Гоняй файл с реальными данными, а не с test test — тебе нужны как раз кавычки, запятые и длинные тексты.

Что получится: пользователь жмёт кнопку, получает файл, открывает двойным кликом — и видит нормальную таблицу с русскими буквами, где ни одна строка не разъехалась.

Две ловушки, о которых ИИ не предупредит

Ведущие нули и длинные числа. Excel считает содержимое ячеек числами, если может. 007 станет 7, номер телефона +79991234567 — числом в экспоненциальной записи, а артикул 1-2 может превратиться в дату. Если поле по смыслу текстовое — это надо признать явно: либо не экспортировать такие поля числами, либо предупредить пользователей, что файл нужно импортировать, а не открывать двойным кликом.

CSV-инъекция. Куда серьёзнее. Если значение начинается с =, +, - или @, табличный редактор может воспринять его как формулу — и вычислить у того, кто откроет файл. Значит, пользователь может вписать формулу в поле «Имя» и получить её выполнение на чужом компьютере. Лечится просто: перед выгрузкой добавь апостроф перед такими значениями или оберни их в кавычки принудительно.

Обе ловушки — хороший пример того, почему код от ИИ выглядит рабочим и всё-таки ломается: модель пишет счастливый путь, а грязные данные в него не входят.

Чем CSV отличается от JSON?

CSV — плоская таблица для людей и Excel, JSON — вложенная структура для программ. Если данные с вложенностью, CSV придётся «расплющивать», и часть смысла потеряется.

Почему Excel разбивает мой CSV на одну колонку?

Скорее всего, у системы русская локаль: там Excel ждёт разделителем точку с запятой, а не запятую. Либо используй ; как разделитель, либо импортируй файл через «Данные → Из текста», где кодировку и разделитель указывают руками.

Нужна ли библиотека для экспорта CSV?

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

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →