Работа с файлами .env при помощи env-cmd

Development, Java | Amber | Комментировать запись

Переменные окружения позволяют переключаться между локальной разработкой, подготовительной средой, пользовательским приемочным тестированием (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 на примере простого проекта.

Файлы окружения помогут вам легко переключаться между средами разработки и производства.