Как добавить экспорт в 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 коротких урока на телефоне.





