← Cloudflare Workers / workers / wrangler

Системные переменные окружения

Системные переменные окружения представляют собой локальные переменные окружения, которые могут изменять поведение Wrangler. Задать их можно тремя способами:

1. Создайте .env файл в каталоге вашего проекта. Задайте значения переменных окружения в вашем .env файле. Это рекомендуемый способ задания этих переменных, поскольку он сохраняет значения между сеансами Wrangler.

2. Укажите значения непосредственно в команде Wrangler. Например, WRANGLER_LOG="debug" npx wrangler deploy установит значение WRANGLER_LOG к "debug" для этого выполнения команды.

3. Задайте значения в окружении вашей оболочки. Например, если вы используете Z shell, добавление export CLOUDFLARE_API_TOKEN=... в ваш ~/.zshrc файл установит этот токен как часть конфигурации вашей оболочки.

Wrangler поддерживает следующие переменные окружения:

• CLOUDFLARE_ACCOUNT_ID string необязательно

  • ID аккаунта для аккаунта, связанного с Workers.

• CLOUDFLARE_API_TOKEN string необязательно

  • API-токен для вашего аккаунта Cloudflare, может использоваться для аутентификации в таких сценариях, как CI/CD и другая автоматизация.

• CLOUDFLARE_API_KEY string необязательно

  • API-ключ для вашего аккаунта Cloudflare, обычно используемый для более старого метода аутентификации с CLOUDFLARE_EMAIL=.

• CLOUDFLARE_EMAIL string необязательно

  • Адрес электронной почты, связанный с вашей учётной записью Cloudflare, обычно используется для более старого способа аутентификации с CLOUDFLARE_API_KEY=.

• CLOUDFLARE_ACCESS_CLIENT_ID string необязательно

  • Client ID для Токен службы Cloudflare Access, используется для аутентификации в доменах, защищённых Access, в неинтерактивных средах, например в конвейерах CI/CD. Должен задаваться вместе с CLOUDFLARE_ACCESS_CLIENT_SECRET. Если заданы обе переменные, Wrangler выполняет аутентификацию с помощью service token, вместо того чтобы запускать cloudflared access login. Полную настройку политики Access и токена службы см. в Подключение к Workers, защищённым Access.

• CLOUDFLARE_ACCESS_CLIENT_SECRET string необязательно

  • Client Secret для Токен службы Cloudflare Access, используется вместе с CLOUDFLARE_ACCESS_CLIENT_ID для аутентификации на доменах, защищённых Access, в неинтерактивных средах. Полное описание настройки политики Access и токена сервиса см. Подключение к Workers, защищённым Access.

• CLOUDFLARE_AUTH_USE_KEYRING boolean необязательно

  • Возможные варианты: true и false. По умолчанию не задано. Переопределяет постоянную настройку, заданную wrangler login --use-keyring / --no-use-keyring для одного вызова. Когда true, Wrangler хранит учетные данные OAuth в зашифрованном файле, при этом ключ шифрования хранится в связке ключей ОС, и завершает работу с ошибкой, если хранилище связки ключей недоступно. Когда false, Wrangler использует устаревший текстовый файл TOML, даже если постоянная настройка включена. См. Хранение учётных данных OAuth в связке ключей ОС для получения подробностей.

• CLOUDFLARE_ENV string необязательно

  • окружение для команд Wrangler. Это позволяет выбрать среду, не используя --env флаг. Например, CLOUDFLARE_ENV=production wrangler deploy развернёт в production окружение. --env аргумент командной строки имеет приоритет над этой переменной окружения.

• NODE_ENV string необязательно

  • Задаёт значение process.env.NODE_ENV в коде вашего Worker. По умолчанию: "development" для wrangler dev и "production" для wrangler deploy и wrangler versions upload. См. Bundling, где это описано подробнее.

• WRANGLER_SEND_METRICS boolean необязательно

  • Возможные варианты: true и false. По умолчанию используется true. Определяет, может ли Wrangler отправлять анонимные данные об использовании в Cloudflare для этого проекта. Подробнее об этом можно узнать в политика данных ↗.

• WRANGLER_SEND_ERROR_REPORTS boolean необязательно

  • Возможные варианты: true и false. По умолчанию используется undefined. Определяет, может ли Wrangler отправлять в Cloudflare отчёты об ошибках, не связанных с пользователем, для этого проекта. Если undefined, Wrangler будет спрашивать пользователя, отправлять ли отчет об ошибке, каждый раз при возникновении ошибки, не связанной с действиями пользователя.

• CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>string необязательно

  • локальная строка подключения для вашей базы данных, чтобы использовать её при локальной разработке с Hyperdrive. Например, если привязка для вашего Hyperdrive называется PROD_DB, это будет CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_PROD_DB="postgres://user:[email protected]:5432/testdb". Каждый Hyperdrive однозначно определяется именем привязки.

• CLOUDFLARE_API_BASE_URL string необязательно

  • Значение по умолчанию: "https://api.cloudflare.com/client/v4".

• WRANGLER_LOG string необязательно

  • Варианты для уровней логирования: "none", "error", "warn", "info", "log" и "debug". Уровни нечувствительны к регистру, значение по умолчанию: "log". Если указан недопустимый уровень, Wrangler вернётся к значению по умолчанию. Журналы могут включать запросы к API Cloudflare, собираемые данные об использовании и подробные журналы ошибок.

• WRANGLER_LOG_PATH string необязательно

  • Путь к файлу или каталогу, куда Wrangler будет записывать отладочные журналы. Если путь заканчивается на .log, Wrangler будет считать это путем к файлу, в который будут записываться все журналы. В противном случае Wrangler будет считать этот путь каталогом, в который будет записывать один или несколько файлов журнала с именами на основе временной метки.

• WRANGLER_LOG_SANITIZE boolean необязательно

  • Возможные варианты: true и false. По умолчанию используется true. Определяет, будет ли Wrangler удалять конфиденциальную информацию из логов, записываемых в консоль или в файл логов. К конфиденциальной информации относятся API токены, адреса электронной почты, ID аккаунтов и так далее.

• FORCE_COLOR string необязательно

  • Задав этому параметру значение 0, вы можете отключить цветной вывод Wrangler, что облегчает чтение при некоторых настройках терминала. Например, FORCE_COLOR=0.

• WRANGLER_HTTPS_KEY_PATH string необязательно

  • Путь к пользовательскому ключу HTTPS-сертификата при запуске wrangler dev, для использования с WRANGLER_HTTPS_CERT_PATH.

• WRANGLER_HTTPS_CERT_PATH string необязательно

  • Путь к пользовательскому HTTPS-сертификату при запуске wrangler dev, для использования с WRANGLER_HTTPS_KEY_PATH.

• DOCKER_HOST string необязательно

  • Используется для локальной разработки Containers. Wrangler попытается автоматически найти нужный сокет для взаимодействия с вашим движком контейнеров. Если это не сработает (обычно это проявляется как ошибка internal error при попытке подключения к вашему Container), можно попробовать задать путь к сокету с помощью этой переменной окружения.

• WRANGLER_R2_SQL_AUTH_TOKEN string необязательно

  • Токен API, используемый для выполнения запросов с R2 SQL.

• WRANGLER_OUTPUT_FILE_PATH string необязательно

  • Задаёт путь к файлу, в который Wrangler запишет выходные данные в формате ND-JSON ↗ (формат JSON, где каждая запись располагается на отдельной строке). Каждая строка файла представляет собой отдельный JSON-объект с информацией об операциях Wrangler, таких как развёртывания, загрузки версий и ошибки. Это удобно для конвейеров CI/CD и инструментов автоматизации, которым нужен программный доступ к данным о развёртывании. Если указаны оба WRANGLER_OUTPUT_FILE_PATH и WRANGLER_OUTPUT_FILE_DIRECTORY заданы, WRANGLER_OUTPUT_FILE_PATH имеет приоритет.

• WRANGLER_OUTPUT_FILE_DIRECTORY string необязательно

  • Задаёт каталог, в котором Wrangler создаст файл со случайным именем (формат: wrangler-output-<timestamp>-<random>.json) для записи выходных данных в ND-JSON ↗ формат. Это полезно, если вы хотите, чтобы выходные файлы были организованы в определённой директории, но при этом точное имя файла вас не волнует. Если оба WRANGLER_OUTPUT_FILE_PATH и WRANGLER_OUTPUT_FILE_DIRECTORY заданы, WRANGLER_OUTPUT_FILE_PATH имеет приоритет.

• WRANGLER_CACHE_DIR string необязательно

  • Пользовательский каталог для файлов кеша Wrangler. Если задан, он переопределяет расположение кеша по умолчанию (node_modules/.cache/wrangler). Полезно для сред, не использующих традиционный node_modules каталог, например Yarn PnP.

• MINIFLARE_CACHE_DIR string необязательно

  • Пользовательский каталог для Miniflare cf.json файл кеша, используемый при локальной разработке с wrangler dev. Если этот параметр задан, он переопределяет расположение кеша по умолчанию (node_modules/.mf). Полезно для сред, не использующих традиционный node_modules каталог, например Yarn PnP.

• CLOUDFLARE_CF_FETCH_ENABLED string необязательно

  • Управляет тем, будет ли Miniflare получает cf.json файл, содержащий Request.cf свойства от Cloudflare при локальной разработке. Установите значение "false" или "0" чтобы полностью отключить получение данных и использовать резервные данные. Никаких node_modules/.mf/cf.json файл будет создан, если отключено. По умолчанию "true". Это особенно полезно для проектов не на JavaScript (например, Workers на Rust или Go), в которых не нужен node_modules каталог создается автоматически. Явное cf параметр в API Miniflare имеет приоритет над этой переменной окружения.

• CLOUDFLARE_CF_FETCH_PATH string необязательно

  • Задаёт пользовательский путь для кеширования cf.json файл, переопределяя значение по умолчанию node_modules/.mf/cf.json расположение. Это полезно для конфигураций с несколькими проектами, где нужно общее расположение кеша, или для проектов, которым нужно хранить кеш вне node_modules. Явный cf параметр в API Miniflare имеет приоритет над этой переменной окружения, а CLOUDFLARE_CF_FETCH_ENABLED=false имеет приоритет над этой переменной.

Когда эти переменные окружения заданы, Wrangler построчно записывает в выходной файл по одному объекту JSON. Каждая запись включает timestamp поле и type поле, указывающее тип операции. Вот пример того, что может содержать файл после выполнения wrangler deploy:

{"type":"wrangler-session","version":1,"wrangler_version":"3.78.0","command_line_args":["deploy"],"log_file_path":"/path/to/logs/wrangler-2024-11-03_12-00-00_abc.log","timestamp":"2024-11-03T12:00:00.000Z"}
{"type":"deploy","version":1,"worker_name":"my-worker","worker_tag":"abc123def456","version_id":"v1-abc123","targets":["https://my-worker.example.workers.dev"],"worker_name_overridden":false,"wrangler_environment":"production","timestamp":"2024-11-03T12:00:05.000Z"}

wrangler-session запись создаётся при запуске Wrangler и содержит информацию о выполняемой команде. deploy запись создаётся при успешном завершении деплоя и включает имя Worker, ID версии и URL-адреса деплоя.

К другим типам точек входа относятся:

• version-upload - Написано wrangler versions upload с идентификатором версии и URL для предпросмотра
• version-deploy - Написано wrangler versions deploy с информацией о развертывании
• pages-deploy - Написано wrangler pages deploy с данными о развертывании Pages
• command-failed - Записывается при сбое команды, включая код ошибки и сообщение

Ниже приведён пример .env файле:

CLOUDFLARE_ACCOUNT_ID=<YOUR_ACCOUNT_ID_VALUE>
CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN_VALUE>
CLOUDFLARE_EMAIL=<YOUR_EMAIL>
WRANGLER_SEND_METRICS=true
CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
WRANGLER_LOG=debug
WRANGLER_LOG_PATH=../Desktop/my-logs/my-log-file.log
WRANGLER_R2_SQL_AUTH_TOKEN=<YOUR_R2_API_TOKEN_VALUE>
CLOUDFLARE_CF_FETCH_ENABLED=false

Следующие переменные считаются устаревшими. Используйте новые переменные, перечисленные выше, чтобы избежать проблем и нежелательных сообщений.

• CF_ACCOUNT_ID
• CF_API_TOKEN
• CF_API_KEY
• CF_EMAIL
• CF_API_BASE_URL