Ключи (env)
env.NAME — ключ проекта: токен, клиентский секрет, ключ карт, — который хранится вне кода: на этой
машине — в файле проекта .env (NAME=value, рядом с app.json, никогда не уходит на платформу), на
le.codes — в Project Settings → Keys. Серверный код (*.server.ts,
Серверные функции) читает любой ключ. Приложение читает только
ключи с именем PUBLIC_…: бандл приложения публичен, так что ключ, который несёт приложение,
публичен уже по имени, а компиляция отвергает любое другое имя в коде приложения. Языковой модели
проекта ключ не нужен: ai.
- вызывать платный API с сервера с токеном, которого нет в коде (
env.OPENAI_KEY) - использовать в приложении ключ карт или аналитики, не зашивая его в код (
env.PUBLIC_MAPS_KEY) - держать токен бота или платёжный ключ вне репозитория и вне поля зрения ИИ
- узнать, какого ключа не хватает, до того как упадёт первый вызов
- быть уверенным, что секрет никогда не попадёт в бандл приложения
Обзор
# .env — next to app.json; the CLI never pushes it. Capital names, one per line.
OPENAI_KEY=sk-… # server only
PUBLIC_MAPS_KEY=AIza… # may be in the app: its name says so// ask.server.ts — выполняется на бэкенде: здесь доступен любой ключ
export async function ask(question: string) {
const r = await fetch("https://api.openai.com/v1/responses", {
method: "POST",
headers: { authorization: `Bearer ${env.OPENAI_KEY}`, "content-type": "application/json" },
body: JSON.stringify({ model: "gpt-5", input: question }),
})
return (await r.json()).output_text as string
}// main.ts — приложение: только ключи PUBLIC_
const places = await fetch(`https://maps.example/places?near=${lat},${lng}&key=${env.PUBLIC_MAPS_KEY}`)Ключ — это string, никогда не string | undefined. Чтение незаданного ключа бросает EnvError,
чьё сообщение называет ключ и место, куда его добавить: здесь — .env, на le.codes — Settings →
Keys. На сервере это упавший вызов (500, причина — в консоли сервера); в приложении — исключение там,
где стоит чтение. "OPENAI_KEY" in env спрашивает без исключения; Object.keys(env) перечисляет
заданные ключи.
Где живёт ключ и когда он приходит
| где работает приложение | серверные ключи (env.NAME) |
ключи приложения (env.PUBLIC_NAME) |
|---|---|---|
lecodes dev, lecodes test, lecodes render, desktop run |
.env проекта, читается при каждой перезагрузке — сохранение .env передеплоивает бэкенд |
.env проекта, вшивается в бандл при компиляции |
| превью le.codes и опубликованное приложение | Project Settings → Keys, уходят на бэкенд с каждой сборкой | Project Settings → Keys, вшиваются в бандл сборкой |
Имена — заглавные латинские буквы, цифры и подчёркивания ([A-Z][A-Z0-9_]*, не длиннее 64). В
.env лежат и собственные настройки CLI LECODES_* / CREATOR_*; это не ключи приложения.
Что проверяется при компиляции и деплое
- Код приложения читает ключ не
PUBLIC_…— ошибка компиляции с именем файла:main.ts: env.OPENAI_KEY. Читай его в файле*.server.tsи вызывай эндпоинт — или назови егоPUBLIC_…, если приложению можно его нести. - Код приложения читает незаданный ключ
PUBLIC_…— предупреждение компиляции; чтение бросает исключение, пока ключ не добавят. - Серверный код читает незаданный ключ — предупреждение при старте бэкенда
(
env: OPENAI_KEY not set), в терминале dev или в консоли сервера; падают только вызовы, которые его читают. - Значение секрета оказалось в бандле приложения — вставлено в код приложения или в ассет:
компиляция отвергается (
EnvLeakError). Значения короче 8 символов не ищутся.
Имена, которые читает серверный код, находит компиляция (env.NAME, env["NAME"]); динамическое
чтение, env[name], проверяется только во время выполнения.
Чего нет
- Разных значений для разных сборок (черновик / опубликованная): у проекта один набор ключей.
- Ключа в общем модуле, который импортируют обе стороны: файл не
*.server.ts— это код приложения, так что там разрешены только чтенияPUBLIC_….