Vue.js: 環境変数の設定ができてない時にビルドを失敗させる

まとめ

• vue.config.js に環境変数が設定されていなかったら例外を throw する処理を書く
• yarn lint の時は環境変数が来ないので NODE_ENV が undefined の時は環境変数のチェックをスキップする
• vue.config.js 内で例外を発生させることで、ビルドと開発サーバーの起動のどちらも失敗させられる

vue.config.js

// yarn lint の時など、環境変数が来てない場合(NODE_ENV===undefined)はスキップ
if (process.env.NODE_ENV !== undefined) {
  // 環境変数 VUE_APP_API_URL が必須の場合 (もっと細かくURLをチェックしてもOK)
  if (!process.env.VUE_APP_API_URL) {
    // throw で例外を発生させることでビルドが失敗する
    // なるべく自分で解決できるようなエラーメッセージにする(ドキュメントに誘導してもいい)
    throw 'VUE_APP_API_URL に API の URL を指定してください(.env.sample 参照)'
  }
  // 環境変数の検証に限らず設定が増えるごとにここにルールを追加していく
}

module.exports = {
  // もともと設定があればここに書く、ない場合はカラのオブジェクトを export する
}

背景

• フロントエンドのアプリケーションを開発している時、ビルド時・開発サーバーの起動時に必要な情報を環境変数で渡すことがよくあります
• ローカル環境、ステージング環境、本番環境と複数の環境がある場合、新しく追加した環境変数を他の環境に設定し忘れてアプリケーションに不可解なバグが発生することがあります
• 設定に不備があるならビルド時に検出して、デプロイを失敗させて早めに気付けるとうれしい

こんなことを避けたい

• 新しく入った開発メンバーがローカル環境をセットアップ後、はじめてアプリを起動したらなんか動きがおかしい(設定の不備のせいで)
• 他の環境で動作確認したアプリが本番環境にデプロイしたら一部の機能が動かない(本番用の設定の不備のせいで)
• 誰かが新しい環境変数を追加して、他の開発メンバーが最新のソースに更新したらローカルで動きがおかしい(設定の追加ができてない)

やること

• 設定値をチェックする処理を vue.config.js に書く
• yarn serve 時に設定値をチェックして、設定に不備があったら起動に失敗させる
• yarn build 時に設定値をチェックして、設定に不備があったらビルドに失敗させる

やってみる

※ Node.js と yarn はインストール済みの前提です

VUE_APP_API_URL という環境変数が必須なアプリケーションを作って試してみます

まず Vue のプロジェクトを作ります(Vue 2, Vue 3 のどちらでも可)

npm install -g @vue/cli
vue create vue-env-validator

カラの vue.config.js を作ります

cd vue-env-validator/
touch vue.config.js

vue.config.js に以下の内容を書き込みます(環境変数 VUE_APP_API_URL を必須にする)

vue.config.js

// yarn lint 実行時など、環境変数が渡って来ないときは NODE_ENV が undefined なのでスキップ
if (process.env.NODE_ENV !== undefined) {
  if (!process.env.VUE_APP_API_URL) {
    throw 'VUE_APP_API_URL に API の URL を指定してください(.env.sample 参照)'
  }
}

module.exports = {
  // もともと設定がないのでカラのオブジェクトを export する
}

実際に環境変数のチェックができているかを確認してみます

• yarn serve
  • 環境変数未設定の時、開発サーバーの起動に失敗することを確認
  • 
• yarn build
  • 環境変数未設定の時、ビルドが失敗することを確認
  • 
• yarn lint
  • 環境変数未設定の時、lint は影響を受けないことを確認
• VUE_APP_API_URL=https://example.com yarn serve
  • 環境変数設定時、開発サーバーの起動が成功することを確認
• VUE_APP_API_URL=https://example.com yarn build
  • 環境変数設定時、ビルドが成功することを確認
• VUE_APP_API_URL=https://example.com yarn lint
  • 環境変数設定時、lint は影響を受けないことを確認

環境変数が設定されていない時は、無事にビルド・開発サーバーの起動に失敗することが確認できました。

最後に

自動で検出できる不備は早めに検知できると楽ですね。

.env.development などを介して環境変数を設定している場合でも、今回の手順で設定の不備を検出できます。

参考

• Configuration Reference | Vue CLI