Переменные окружения позволяют переключаться между локальной разработкой, подготовительной средой, пользовательским приемочным тестированием (UAT), производственной средой и любыми другими средами, которые являются частью рабочего процесса вашего проекта.
Вместо того чтобы по отдельности передавать переменные в скрипты, с помощью env-cmd вы можете группировать их в файлах окружения (.env) и передавать эти группы в скрипт.
В этом мануале вы узнаете, как установить env-cmd и использовать его (на примере простого тестового проекта).
Требования
- Локальная установка Node.js. Инструкции по установке зависят от дистрибутива: Mac OS, Ubuntu, CentOS, Debian.
- Если вы хотите добавить файлы в .gitignore (это опциональный раздел), для этого нужно установить и настроить git. За инструкциями обратитесь к мануалу Разработка проектов с открытым исходным кодом: начало работы с Git.
- Желательно иметь базовые навыки работы с терминалом и редактором кода.
Примечание: Это руководство использует команды для env-cmd версии 9.0.0+.
Руководство проверено на версиях Node v15.14.0, npm v7.10.0 и env-cmd v10.0.1.
1: Настройка проекта
В этом руководстве предполагается, что у вас уже есть простой тестовый проект. Давайте подготовим его к работе с переменными.
Сначала создайте новый каталог:
mkdir env-cmd-example
Перейдите в него:
cd env-cmd-example
Передавать файлы среды в систему управления версиями, как правило, не рекомендуется. Если доступ к репозиторию могут получить посторонние, они найдут там ваши учетные данные (поскольку они будут навсегда записаны в историю проекта системой контроля версий).
Потому файлы окружения рекомендуется поместить в .gitignore.
Примечание: Мы не требуем добавлять файлы в gitignore в рамках этого мануала, но в образовательных целях коротко расскажем, как это делается.
Инициализируйте новый проект git:
git init
Создайте файл .gitignore и добавьте в него следующие шаблоны, чтобы исключить файлы окружения:
.env .env.js .env.json .env-cmdrc
В этом руководстве можно исключить .env, .env.js, .env.json и .env-cmdrc.
Затем создайте для проекта файл .env.
Откройте его в редакторе кода и добавьте следующую строку:
creature=shark green=#008f68 yellow=#fae042
Это определяет три переменные: creature со значением shark, green со значением #008f68 и yellow со значением #fae042.
Затем создайте новый файл log.js и поместите в него такие строки:
console.log('NODE_ENV:', process.env.NODE_ENV);
console.log('Creature:', process.env.creature);
console.log('Green:', process.env.green);
console.log('Yellow:', process.env.yellow);
Этот файл будет записывать ранее определенные переменные в консоль. Также он выведет значение NODE_ENV.
Теперь наше тестовое приложение подготовлено к использованию файлов окружения и env-cmd.
2: Использование env-cmd
Современные утилиты npm и yarn могут запускать env-cmd, не внося его в зависимости.
Используйте либо npx:
npx env-cmd node log.js
Или yarn run:
yarn run env-cmd node log.js
Также вы можете установить пакет как зависимость или devDependency:
npm install env-cmd@10.0.1
Пакет env-cmd устанавливает исполняемый сценарий env-cmd, который можно вызывать перед другими сценариями, чтобы легко загрузить переменные среды из внешнего файла.
В зависимости от ваших настроек вы можете ссылаться на env-cmd несколькими способами.
Возможно, наиболее совместимым с пакетными менеджерами вариантом является добавление пользовательского скрипта в файл package.json:
{
"scripts": {
"print-log": "env-cmd node log.js"
}
}
Например, вы сможете запустить этот сценарий с помощью npm:
npm run print-log
Если вы предпочитаете использовать env-cmd непосредственно через командную строку, вы можете вызвать его из node_modules:
./node_modules/.bin/env-cmd node log.js
В дальнейшем в этом руководстве будет использоваться npx, но все описанные выше подходы одинаково хороши.
Теперь запустите сценарий в своем терминале.
Независимо от того, как вы запустите его, env-cmd загрузит файл .env, а сценарий логирования сообщит о переменных.
NODE_ENV: undefined Creature: shark Green: #008f68 Yellow: #fae042
Как вы могли заметить, значение NODE_ENV не определено, undefined. Это потому, что переменная NODE_ENV не была определена в файле .env.
Передать NODE_ENV можно перед вызовом env-cmd. К примеру, вот команда для npx, которая сделает это:
NODE_ENV=development npx env-cmd node log.js
Снова запустите команду с определенной NODE_ENV, и вы получите такой результат:
NODE_ENV: development Creature: shark Green: #008f68 Yellow: #fae042
Теперь вы знаете, как использовать env-cmd с файлом .env.
3: Форматы файлов
env-cmd по умолчанию ожидает встретить файл .env в корневом каталоге проекта. Однако вы можете изменить тип файла и путь с помощью параметра –file (-f).
Есть множество форматов файлов, доступных для хранения переменных окружения.
Файл JSON
Вот пример файла .env.json:
{
"creature": "shark",
"green": "#008f68",
"yellow": "#fae042"
}
А вот пример использования этого формата для файла env-cmd:
NODE_ENV=development npx env-cmd --file .env.json node log.js
Файлы окружения в формате JavaScript
Вот пример файла .env.js:
module.exports = {
creature: 'shark',
green: '#008f68',
yellow: '#fae042'
};
А вот пример файла env-cmd в этом формате:
NODE_ENV=development npx env-cmd --file .env.js node log.js
RC-файлы
Формат файла rc (или runcom) особенный: он позволяет определять несколько сред в одном файле JSON и ссылаться на среду по имени, а не по файлу.
Еще одна особенность файла rc заключается в том, что он должен называться .env-cmdrc и находиться в корневом каталоге проекта.
Вот пример файла .env-cmdrc с определенными средами разработки и производства и промежуточной средой:
{
"development": {
"NODE_ENV": "development",
"creature": "shark",
"green": "#008f68",
"yellow": "#fae042",
"otherVar1": 1
},
"staging": {
"NODE_ENV": "staging",
"creature": "whale",
"green": "#6db65b",
"yellow": "#efbb35",
"otherVar2": 2
},
"production": {
"NODE_ENV": "production",
"creature": "octopus",
"green": "#4aae9b",
"yellow": "#dfa612",
"otherVar3": 3
}
}
Для использования значений из файла .env-cmdrc потребуется параметр –environments (-e).
Затем вы можете сослаться на одну из сред в файле с помощью команды:
npx env-cmd --environments development node log.js
Вы даже можете ссылаться на несколько сред, что объединит все переменные среды (причем последняя среда будет иметь приоритет, если одни и те же переменные встречаются в нескольких средах, но имеют разные значения):
npx env-cmd --environments development,staging,production node log.js
Указав все три среды, мы установим три разные переменные otherVar, а остальные переменные будут извлечены из последней указанной среды, production.
4: Флаг –fallback
В ситуациях, когда пользовательский файл окружения отсутствует:
npx env-cmd -f .env.missing node log.js
env-cmd выдаст ошибку:
Error: Failed to find .env file at path: .env.missing
Если возникает непредвиденная проблема с пользовательским путем к файлу env, env-cmd может попытаться загрузить файл .env из корневого каталога проекта. Для этого передайте флаг –fallback:
npx env-cmd --file .env.missing --fallback node log.js
Если теперь у вас есть валидный файл .env, эта команда не будет отображать никаких ошибок.
5: Флаг –no-override
В некоторых ситуациях возникает необходимость сохранить все или некоторые из переменных, уже установленных в среде.
Чтобы оставить существующие переменные среды (но не писать значения в файле .env), передайте env-cmd флаг –no-override:
NODE_ENV=development creature=squid npx env-cmd --no-override node log.js
Эта команда вернет такой результат:
NODE_ENV: development Creature: squid Green: #008f68 Yellow: #fae042
Обратите внимание, значение creature имеет значение squid вместо shark, которое было определено в файле .env.
Заключение
В этой статье вы изучили основы использования env-cmd на примере простого проекта.
Файлы окружения помогут вам легко переключаться между средами разработки и производства.