Переменные окружения в Cursor распределены по поверхностям: командная строка и программные интерфейсы, аутентификация, песочница, рабочие деревья, серверный исполнитель, облако и обработчики событий. Справочник показывает имена и назначение, но не значения - секретный материал не должен попадать ни в книгу, ни в отчёт, ни в репозиторий конфигурации. Разделение на поверхности здесь не формальность: оно сразу говорит, какой процесс переменную читает и в какой момент она должна существовать.
Правило про имена и значения не формальная оговорка, а рабочая практика. Имя безопасно: оно объясняет, что настраивается, и его можно свободно обсуждать в задаче или переписке. Значение - нет: оно даёт доступ, причём ровно тот, ради которого его выдавали. Разница особенно важна при отладке, когда хочется приложить к обращению весь вывод окружения. Правильный ход - приложить список имён и указать, какие из них заданы, не раскрывая содержимого; этого достаточно для диагностики почти любой проблемы с конфигурацией.
Полезно один раз свести переменные по поверхностям в таблицу. Ниже такая карта: ключ и токен для программного доступа, поведение входа в среде без графики, выбор хранилища учётных данных, настройка прокси и корневого сертификата, метки серверного исполнителя, каталог конфигурации. Группировка помогает понять, к какому механизму относится переменная, и не искать её не там.
| Поверхность | Переменная | Назначение |
|---|---|---|
| Командная строка и API | CURSOR_API_KEY | Ключ для процесса командной строки, набора или интерфейса |
| Командная строка и протокол | CURSOR_AUTH_TOKEN | Альтернативный предварительно выданный токен |
| Вход | NO_OPEN_BROWSER | Не открывать браузер в среде без графики |
| Вход | AGENT_CLI_CREDENTIAL_STORE | Файловое хранилище вместо системного; применять осознанно |
| Сеть | HTTP_PROXY, HTTPS_PROXY | Корпоративный прокси для исходящих соединений |
| Сеть | NODE_EXTRA_CA_CERTS | Корневой сертификат организации вместо отключения проверки |
| Исполнитель | CURSOR_WORKER_LABELS_FILE |
| Метки серверного исполнителя из файла |
| Конфигурация | CURSOR_CONFIG_DIR, XDG_CONFIG_HOME | Каталог состояния и конфигурации для контейнеров и стендов |
|---|
У переменных разный статус, и это стоит различать. Одни - гарантированный вход: обработчик события получает корень рабочей области и версию инструмента, и на них можно строить логику. Другие - соглашение из примера в документации: имя, под которым в образце принято передавать ключ служебной учётной записи. Первое можно считать частью контракта, второе - нет, и переносить такое имя в свои сценарии как обязательное не следует. Использовать переменную стоит в той области, в которой она описана, и не приписывать ей смысла, которого у неё нет.
Отдельно стоит отметить переменные, меняющие безопасность. Хранилище учётных данных в файле вместо системного, дополнительный корневой сертификат, признаки ослабленной изоляции - всё это существует ради сред, где иначе никак: сборочные машины без графической сессии, контейнеры без связки ключей, корпоративные сети с перехватом трафика. Такие значения не задают в общем профиле оболочки: они живут в конкретном запуске, где их необходимость доказана, и исчезают вместе с ним.
Корпоративная сеть даёт самый частый случай. Загрузки перестают работать, потому что трафик проходит через посредника, подставляющего собственный сертификат, и проверка подлинности честно её отклоняет. Соблазн - отключить проверку целиком; цена - каждое исходящее соединение перестаёт быть защищённым от подмены, включая те, о которых вы не думали. Правильный ход - задать адрес прокси и подключить корневой сертификат организации: доверие расширяется ровно на один известный центр, а не отменяется.
Есть и практический приём для автоматизации: задавать переменную перед конкретной командой, а не экспортировать её в окружение целиком. Это сужает область видимости до одного процесса и не даёт значению утечь в соседние шаги, которые вы не писали, - а в непрерывной интеграции соседние шаги нередко чужие. Дополнительная выгода в том, что запуск становится самодостаточным: по одной строке видно, что именно ему требовалось.
Переменные каталогов конфигурации полезны в контейнерах и на общих машинах: они позволяют развести состояние разных запусков, не мешая друг другу. Это редкая, но очень выручающая возможность - особенно когда на одной машине живут несколько окружений с разными учётными данными и нужно гарантировать, что вход в одном не подменит вход в другом.
Инженерный вывод простой: относитесь к переменным окружения как к части конфигурации, а не как к временным флагам. У каждой есть область видимости, срок жизни и последствия. Записанные и осознанно выданные, они делают среду воспроизводимой; розданные по привычке - создают каналы доступа, о которых через полгода никто не помнит.
Типичные провалы предсказуемы. Приложить к обращению вывод окружения вместе со значениями. Экспортировать ключ в общее окружение вместо конкретной команды. Отключить проверку сертификатов навсегда вместо того, чтобы добавить корневой сертификат организации. Принять соглашение из примера за гарантированный вход. И задать переменные безопасности в общем профиле оболочки.