できない.dev

Vite「process is not defined」の原因と直し方

Vite の process is not defined は、ブラウザで Node の process を参照すると出る。
自分のコードは import.meta.env に書き換え、ライブラリ由来なら define で補えば直る。

公開: 更新:

症状できない · exit 1
node run-in-browserlike.mjs
…
ReferenceError: process is not defined
    at evalmachine.<anonymous>:3:15
    at evalmachine.<anonymous>:5:3
    at Script.runInContext (node:vm:149:12)
解決後できた · exit 0
node run-in-browserlike.mjs
API_URL = https://api.example.com

2026-09-18 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細

要約

Uncaught ReferenceError: process is not defined は、Node.js のグローバル変数 process をブラウザで参照したときに出る。
process は Node のランタイムが提供するもので、ブラウザには存在しない。
開発サーバーは process.env.NODE_ENV 以外の process.env.FOO をそのまま残すので、ブラウザでこのエラーになる。
vite build は process.env を {} に置き換えるのでエラーにならず、値が undefined になる。
ただし、ライブラリモード(新しいタブで開く)の build は置き換えない。
process.platform のような process.env 以外の参照は、どのモードでも残る(Vite 6.4.5 と 8.3.5 で確認)。
環境変数は Vite の流儀である import.meta.env から読む。
自分のコードは import.meta.env に直し、ライブラリ都合でどうしても process が必要なときは define で補う。

Uncaught ReferenceError: process is not defined

実行例

ライブラリモード(build.lib)でビルドすると process.env.VITE_API_URL はバンドル後もそのまま残り、ブラウザに近い実行環境では ReferenceError: process is not defined で終了コード 1 になる。
import.meta.env に書き換えても define で置き換えても、バンドルには文字列 "https://api.example.com" が埋め込まれて終了コード 0 になる。

$ npx vite build
vite v6.4.3 building for production...
transforming...
✓ 1 modules transformed.
rendering chunks...
computing gzip size...
dist/app.iife.js  0.11 kB │ gzip: 0.12 kB
✓ built in 27ms
$ grep -n 'process.env' dist/app.iife.js
3:  const url = process.env.VITE_API_URL;
$ node run-in-browserlike.mjs
evalmachine.<anonymous>:3
  const url = process.env.VITE_API_URL;
              ^
 
ReferenceError: process is not defined
    at evalmachine.<anonymous>:3:15
    at evalmachine.<anonymous>:5:3
    at Script.runInContext (node:vm:149:12)
    at Object.runInContext (node:vm:301:6)
    at file:///tmp/tmp.GUn486Btwy/run-in-browserlike.mjs:8:4
    at ModuleJob.run (node:internal/modules/esm/module_job:325:25)
    at async ModuleLoader.import (node:internal/modules/esm/loader:606:24)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:117:5)
 
Node.js v20.20.2
$ echo $?
1
$ npx vite build
vite v6.4.3 building for production...
transforming...
✓ 1 modules transformed.
rendering chunks...
computing gzip size...
dist/app.iife.js  0.11 kB │ gzip: 0.12 kB
✓ built in 24ms
$ node run-in-browserlike.mjs
API_URL = https://api.example.com
$ echo $?
0
$ npx vite build
vite v6.4.3 building for production...
transforming...
✓ 1 modules transformed.
rendering chunks...
computing gzip size...
dist/app.iife.js  0.11 kB │ gzip: 0.12 kB
✓ built in 25ms
$ grep -n 'api.example.com' dist/app.iife.js
3:  const url = "https://api.example.com";
$ node run-in-browserlike.mjs
API_URL = https://api.example.com
$ echo $?
0

— 2026-09-18 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-09-18 検証(ほか 1 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. import.meta.env に書き換える

自分のコードでは process.env をやめ、import.meta.env を使う。
クライアントへ露出させる変数名は VITE_ で始める必要がある。

// const url = process.env.API_URL  →
const url = import.meta.env.VITE_API_URL;

.env ファイル側も合わせる。

VITE_API_URL=https://api.example.com

なお VITE_ を付けた変数はバンドルに含まれてブラウザから見えるため、API キーなどの秘匿情報は入れてはならない。

2. ライブラリ都合の process.env を define で補う

自分では直せないライブラリが process.env を読む場合は、vite.config の define でビルド時に値を埋め込む。
define は文字列を「そのままコードに置換」するので、値は JSON.stringify で囲む。

// vite.config.ts
export default defineConfig({
  define: {
    "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV),
    // 参照だけ通したい最低限のフォールバック
    "process.env": {},
  },
});

よくある原因

  1. 自前のコードが process.env を参照している。
    Node の感覚で、process.env.FOO と書いてしまっている。
  2. 依存ライブラリが参照している。
    ライブラリが内部で process.env.FOO や process.platform を読んでおり、それがブラウザに混ざっている。
    process.env.NODE_ENV は開発サーバーでも build でも値に置き換わるので、ライブラリモード以外ではこのエラーの原因にならない。
  3. CRA から移行した。
    process.env.REACT_APP_* の参照が、移行後も残っている。
  4. プレフィックスが違う。
    Vite は VITE_ で始まる変数だけをクライアントに露出するため、それ以外は import.meta.env に現れない。