※本記事はアフィリエイト広告(PR)を含みます。
npm run build を打つと dist/ に見覚えのないファイルができる。あれは何なのか。
前回: node_modulesは消してよい — npmとパッケージ管理 この記事で第3段階(プログラミング)は最後です。
自分が書いたのは main.js と style.css と index.html の3つだけのはずなのに、出てきたのは index-a1b2c3d4.js みたいな、意味の分からない名前のファイルでした。開いてみたら改行がなくて、変数名は t とか n とか1文字になっていて、自分が書いた覚えのないコードまで混ざっている。
「動いたからいいや」で先に進みました。 そして数日後、本番だけ画面が真っ白になったときに、何も出来ませんでした。
エラーは出ています。でもエラーが指している場所は index-a1b2c3d4.js の 1行目 4823文字目。自分のコードのどこなのか、まったく分かりません。
中で何が起きているか分からないまま使うと、壊れたときに何も出来ない。 これはビルドツールに限った話ではないのですが、ビルドツールは特にそうです。普段は完全に透明で、壊れたときだけ突然出てくるからです。
この記事は「Vite の使い方」ではありません。「そもそも、なぜビルドという工程が要るのか」を分解する記事です。動かすのは、分解した話を目で確認するためです。
対象レベル: 初級 / 区分: 必修
この記事でわかること
- ビルドは1つの作業ではなく、4つの別々の作業の総称だということ(トランスパイル・バンドル・minify・tree shaking)
- 「バンドルは必須ではなくなった」こと。ブラウザは今
importを理解できる。それでも本番でまとめるのには別の理由がある - Vite の開発サーバーが速いのは、最適化が上手いからではなく「まとめていないから」だということ
dist/に出るファイル名のハッシュは飾りではなく、キャッシュ対策という明確な仕事をしていること- ビルド成果物はただの静的ファイルなので、nginx が返すだけで公開できること
この記事でやること
- なぜビルドが要るのかを4つに分解して理解する(ここが本題)
- VMの中の Ubuntu で
npm create vite@latestを実行し、Vanilla(フレームワークなし)のプロジェクトを作る npm run dev -- --host 0.0.0.0で開発サーバーを起動し、ホストのブラウザから見る。HMR を体験するnpm run buildしてdist/の中身をls -laで実際に見るdist/を nginx で配って、ビルド成果物がただの静的ファイルであることを確認する
作業する場所を毎回書きます。コマンドは全部 VMの中の Ubuntu(VS Code のリモートターミナルでも、SSH でも同じ)、確認はホストの Windows のブラウザです。
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| ビルド | 自分が書いたコードを、そのままブラウザに配れる形に作り直す工程。中身は下の4つの作業の総称 |
| トランスパイル | ブラウザが理解できない書き方を、理解できる JavaScript に書き直すこと |
| バンドル | 分かれている複数のファイルを1つにまとめること。通信の回数を減らすのが目的 |
| minify(ミニファイ) | 空白・改行・コメントを削り、変数名を短くしてファイルを小さくすること。動きは変わらない |
| tree shaking | どこからも呼ばれていないコードを捨てること。使っていない機能まで配らずに済む |
| Vite | 上の作業をまとめて引き受けるビルドツールのひとつ。開発中と本番で別々のやり方を使い分けるのが特徴 |
そもそも、なぜビルドが要るのか
ここが本題です。ビルドという単語が指しているのは、実は4つの別々の作業です。まとめて「ビルド」と呼ばれているせいで、1個の魔法に見えてしまいます。
分解すると、こうなります。
| # | 作業 | 何をしているか | 無いと何が困るか |
|---|---|---|---|
| 1 | トランスパイル | ブラウザが読めない書き方を、読める形に書き直す | そもそも動かない |
| 2 | バンドル | たくさんのファイルを1つにまとめる | 通信回数が増えて遅い |
| 3 | minify | 空白・改行・変数名を削って小さくする | ファイルが重い |
| 4 | tree shaking | 使っていないコードを捨てる | 使わないコードまで配ってしまう |
この4つは、それぞれ別々の困りごとに対する別々の答えです。 順番に見ます。
1. ブラウザが理解できない書き方を、理解できる形に直す=トランスパイル
一番わかりやすいのがこれです。
人間が書きたい書き方と、ブラウザが読める書き方は、一致していません。
たとえば TypeScript。
function greet(name: string): string {
return `こんにちは、${name}さん`;
}
: string の部分は TypeScript の書き方です。ブラウザにそのまま渡すと構文エラーで止まります。 ブラウザは JavaScript しか知らないからです。
だから、こう書き直してから渡します。
function greet(name) {
return `こんにちは、${name}さん`;
}
型の情報を消しただけです。 この「別の言語・別の書き方から、ブラウザが読める JavaScript に書き直す」作業をトランスパイルと呼びます。
同じことが、React の JSX でも起きます。
const el = <h1>こんにちは</h1>;
JavaScript に <h1> をそのまま書く文法は存在しません。 これも書き直しが要ります。
そしてもう1つ、見落としやすいけれど大事なケースがあります。新しい構文と、古いブラウザです。
const name = user?.profile?.name ?? "名無し";
?.(オプショナルチェーン)と ??(Null 合体演算子)は、比較的新しい書き方です。今の Chrome なら動きます。でも数年前のブラウザや、古い Android の WebView では構文エラーになります。
トランスパイラは、これを古いブラウザでも動く形に書き直します。
var _a, _b;
var name = (_b = user === null || user === void 0
? void 0
: (_a = user.profile) === null || _a === void 0
? void 0
: _a.name) !== null && _b !== void 0
? _b
: "名無し";
読みたくない見た目です。でも、これが「動く形」です。
ここがビルドの本質の1つです。 人間が読みやすい書き方と、機械が確実に動かせる書き方は、違います。ビルドツールはその間を機械的に翻訳しているだけです。 前者を人間が書き、後者をブラウザが読む。両方を人間が書こうとしていたのが、ビルドが無かった時代です。
2. たくさんのファイルを、まとめて減らす=バンドル
コードを整理していくと、ファイルは自然に増えます。
src/
├── main.js
├── utils/
│ ├── format.js
│ ├── validate.js
│ └── api.js
├── components/
│ ├── header.js
│ ├── footer.js
│ └── modal.js
└── style.css
人間にとっては、分かれているほうが圧倒的に読みやすい。 これは間違いなくそうです。
でもブラウザにとっては、分かれているほど不利です。
DNS・HTTP・HTTPS の回 で、1ページを表示するのに何回通信が発生しているかを開発者ツールで数えました。画像1枚、CSS 1枚、JS 1本、それぞれが別々のリクエストでした。
ファイルが8個あれば、リクエストは8回です。1回のリクエストには、
- DNS の名前解決(キャッシュされていなければ)
- TCP の接続確立
- TLS のハンドシェイク(HTTPS なら)
- リクエスト送信 → レスポンス待ち
という往復がぶら下がっています。ファイルの中身が小さくても、往復の時間はほぼ固定でかかります。
これを1つにまとめれば、リクエストは1回で済みます。これがバンドルです。
dist/
└── assets/
└── index-a1b2c3d4.js ← 8個ぜんぶ入っている
HTTP/2 で改善したのでは? という指摘は正しいです。HTTP/2 以降は1本の接続の中で複数のファイルを並行して送れるので、昔ほど「ファイル数=致命傷」ではなくなりました。 ただしゼロにはなりません。 ファイルごとにヘッダーの往復はあるし、そのファイルが必要だと分かるのは、それを参照している別のファイルを読み終えた後です。
main.jsを読んで初めてutils/api.jsが要ると分かる、というのが連鎖すると、待ち時間が積み上がります。
3. 小さくする=minify
自分が書いたコードは、こうなっているはずです。
function calculateTotalPrice(items, taxRate) {
// 合計金額を計算する
let total = 0;
for (const item of items) {
total = total + item.price * item.quantity;
}
return Math.round(total * (1 + taxRate));
}
改行・インデント・コメント・意味のある変数名。 全部、人間が読むためのものです。ブラウザは1つも必要としていません。
minify は、これを削ります。
function c(t,a){let e=0;for(const n of t)e=e+n.price*n.quantity;return Math.round(e*(1+a))}
やっていることは3つです。
| 削るもの | 例 |
|---|---|
| 空白・改行・インデント | 全部詰める |
| コメント | 丸ごと削除 |
| 変数名・関数名 | calculateTotalPrice → c、total → e |
動作は1ミリも変わりません。 変わるのはサイズだけです。これで数十パーセント小さくなります。
そして、これがデバッグを不可能にしている犯人でもあります。冒頭で書いた「エラーの場所が index-a1b2c3d4.js の 1行目 4823文字目」というのは、改行を全部消したから全部が1行目になっているというだけの話です。この解決策が後で出てくるソースマップです。
変数名を短くするのは、なぜ安全なのか。 関数の中でしか使われていない変数は、外から名前で呼ばれることがないからです。だから名前は何でもいい。 逆に、外から名前で呼ばれるもの(
window.myFuncとか、オブジェクトのプロパティ名)は、迂闊にリネームすると壊れます。ここはツールが判別してやってくれますが、「文字列でプロパティ名を組み立てる」ような書き方をすると判別に失敗することがあります。 minify したときだけ壊れるバグは、だいたいこれです。
4. 使っていないコードを落とす=tree shaking
ライブラリを入れると、使っていない機能まで全部ついてきます。
たとえば、日付を扱うライブラリを入れて、使ったのは「今日の日付を YYYY-MM-DD にする」1つだけ。でもライブラリ本体には、タイムゾーン変換も、相対時間表示も、各国語の月名も入っています。
そのまま配ると、使っていない99%も一緒に配ることになります。
tree shaking は、「どこからも呼ばれていないコード」を辿って捨てる作業です。
// utils.js
export function used() { return "使う"; }
export function unused() { return "使わない"; }
// main.js
import { used } from "./utils.js";
console.log(used());
この場合、unused() はどこからも呼ばれていないので、dist/ には入りません。
木を揺すって、枯れた葉(使われていないコード)を落とす。だから tree shaking です。
なぜ「木を揺する」で済むのか。
import { used } from "./utils.js"という書き方が、「何を使うか」をコードを実行する前に静的に読み取れる形だからです。 これは後で出てくる ES モジュールの性質です。昔のrequire()は実行時に決まるので、何が使われるか事前に分からず、tree shaking ができません。 ここは繋がっています。
ビルドが要らなかった時代に、何が困っていたか
「ビルドが要る理由」を4つ見ました。逆側からも見ておきます。ビルドが無かった頃、どう書いていたのか。
こうです。
<script src="jquery.js"></script>
<script src="utils.js"></script>
<script src="validate.js"></script>
<script src="main.js"></script>
<script> タグを、必要な順番に並べる。 それだけです。ビルドツールもコンパイルも要りません。
これは分かりやすいです。分かりやすいのですが、規模が大きくなると3つの問題が出ます。
問題1: グローバル汚染
昔のスクリプトには、「このファイルの中だけ」という仕切りがありませんでした。
// utils.js
var config = { debug: true };
// main.js
var config = { apiUrl: "https://example.com" };
後から読まれたほうが勝ちます。 utils.js の config は、main.js に上書きされて消えます。
エラーは出ません。静かに壊れます。 そして「なぜか debug が効かない」という調査に半日溶けます。
ファイルが4個なら気をつけられます。40個になると無理です。
問題2: 読み込み順
上の例で <script src="main.js"> を utils.js より先に書いたら、main.js が utils.js の関数を呼ぶ瞬間に「そんな関数はない」で落ちます。
つまり、依存関係を人間が手で順番に並べて管理していたわけです。
- A は B に依存している
- B は C に依存している
- C は A の一部の関数を使っている(循環している)
この順番を、ファイルが増えても手で正しく保ち続ける。 現実的ではありません。
問題3: 依存の管理
jquery.js というファイルがリポジトリに置いてあるだけでは、バージョンも入手元も分かりません。 更新は公式サイトから手でダウンロードして置き換える。そのライブラリがさらに別のライブラリに依存していたら、それも手で入れる。
これは npm の回 で見た package.json が解決した問題そのものです。
まとめると、ビルドツールが登場した理由はこうです。 ファイルを分けたい(人間の都合)が、分けると壊れる・遅くなる(機械の都合)。 その両方を成立させるために、「書くときは分ける、配るときはまとめる」という工程を挟んだ。 それがビルドです。
ES モジュール — import と export
グローバル汚染と読み込み順の問題に、言語そのものが出した答えが ES モジュールです。
// utils.js
export function formatDate(d) {
return d.toISOString().slice(0, 10);
}
// main.js
import { formatDate } from "./utils.js";
console.log(formatDate(new Date()));
これで3つが同時に解決します。
| 昔の問題 | ES モジュールでどうなるか |
|---|---|
| グローバル汚染 | export したものだけが外に出る。 それ以外はファイルの中に閉じる |
| 読み込み順 | import に書いてある=依存関係が宣言されている。 順番はツールが解決する |
| 何を使っているか不明 | ファイルの先頭を見れば依存が全部分かる |
「このファイルは何に依存しているか」がコードに書いてある。 これが決定的です。人間が <script> の順番で暗黙に表現していたものが、明示的なデータになりました。
ブラウザも今は理解できる
ここが、この記事で一番ひっくり返るところです。
import / export は、今のブラウザがそのまま理解できます。
<script type="module" src="/main.js"></script>
type="module" を付けるだけです。これだけで、ブラウザは main.js の中の import を読んで、必要なファイルを自分で取りに行きます。
試せます。VMの中の Ubuntu で、適当なディレクトリを作って。
配ります。
ホストの Windows のブラウザで http://<VMのIP>:8000/ を開くと、「こんにちは、obmesさん」と出ます。
ビルドツールは1つも使っていません。 import をブラウザが解釈して、utils.js を自分で取りに行っています。
なぜ
python3 -m http.serverが要るのか。index.htmlをファイルとしてダブルクリックで開く(file://)と、モジュールの読み込みは CORS エラーで失敗します。 ES モジュールはhttp://かhttps://経由でしか読めない決まりです。 「ローカルで開いたら動かない」の大半はこれです。
止めるときは Ctrl+C。片付けは rm -rf ~/esm-test です。
[スクリーンショット: 01_esmodule_network.png] ホストのブラウザで開いた状態で F12 → Network タブを開いて再読み込みし、main.js と utils.js が別々のリクエストとして2本並んでいるところを撮ってください。開発者ツールの回 で見た画面です。バンドルしていないと通信が増える、というのがそのまま見えます。
だから「バンドルは必須ではなくなった」
ブラウザが import を理解するなら、バンドルしなくても動きます。 これは事実です。
それでも本番でまとめる理由は、残っています。
- 通信回数。上のスクリーンショットの通り、ファイルの数だけリクエストが飛びます。 ファイル200個のアプリなら200回です
- 依存の連鎖。ブラウザは
main.jsを読み終えて初めてutils.jsが必要だと知ります。そのutils.jsがさらに import していたら、また往復します。深さの分だけ待ちます import "lodash"は動かない。ブラウザは./utils.jsのようなパスは辿れますが、lodashというパッケージ名だけではnode_modulesを探しに行けません。この解決はツールの仕事です- minify・tree shaking・トランスパイルは、どのみち要る。バンドルしないならしないで、残り3つの作業は消えません
整理すると、 ES モジュールは「なぜバンドルするのか」の理由の一部を消しました。「グローバル汚染を避けるため」「読み込み順を管理するため」はもう理由になりません。 残ったのは「配る効率のため」だけです。だから開発中はバンドルしない、本番だけバンドルするという選択が成り立ちます。それをやっているのが Vite です。
実際にやる — Vite でプロジェクトを作る
ここから VMの中の Ubuntu で作業します。
Node.js と npm は npm の回 で入れた前提です。確認します。
v22.11.0
10.9.0
バージョンが表示されれば OK です。出なければ npm の回に戻ってください。
その前に —— ここまでの ~/web/ はどうなるのか
第2段階から使ってきた ~/web/(index.html / style.css / script.js / data.json)は、消しません。
これから作る Vite のプロジェクトは別のディレクトリ(~/vite-demo/)に作ります。~/web/ はそのまま残しておいてください。
この2つは役割が違います。
~/web/ | ~/vite-demo/ | |
|---|---|---|
| 何か | 素のHTML/CSS/JS。ブラウザにそのまま渡している | ビルドを通すプロジェクト |
| 配り方 | python3 -m http.server でそのまま | npm run build → dist/ を配る |
| 役割 | 仕組みを見るための最小構成 | 道具が何をやっているかを見るための比較対象 |
~/web/ を Vite に載せ替えることもできますが、この回ではやりません。 載せ替えてしまうと「Vite が何を足したのか」の比較対象が消えるからです。素の状態を残したまま、隣に道具ありの状態を作って見比べます。
~/web/を使うのは、第6段階の nginx の回が最後です。そこで「素のHTML」と「ビルド成果物」の両方を nginx に載せます。
npm create vite@latest
作業ディレクトリに移動して、
対話が始まります。 聞かれる順に答えます。
? Project name: › vite-demo
? Select a framework: › Vanilla
? Select a variant: › JavaScript
| 質問 | 答え | 理由 |
|---|---|---|
| Project name | vite-demo | ディレクトリ名になる |
| Select a framework | Vanilla | フレームワークなし。 React などは第4段階で扱う |
| Select a variant | JavaScript | TypeScript はまだ扱わない |
必ず Vanilla を選んでください。 ここで React を選ぶと、ビルドの話とフレームワークの話が混ざって、何がどっちの機能なのか分からなくなります。 今日見たいのは「ビルドツールが何をしているか」だけです。
npm createは何をしているのか。 npm の回 のnpxと同じで、create-viteを一時的にダウンロードして実行し、終わったら捨てています。@latestを付けないと古いキャッシュが使われることがあります。
[スクリーンショット: 02_create_vite_対話.png] npm create vite@latest のフレームワーク選択画面(Vanilla にカーソルがある状態)を撮ってください。
npm install
作られたディレクトリに入って、
drwxr-xr-x .
-rw-r--r-- .gitignore
-rw-r--r-- index.html
-rw-r--r-- package.json
drwxr-xr-x public
drwxr-xr-x src
node_modules/ はまだありません。 package.json に「何が必要か」が書いてあるだけです。
{
"name": "vite-demo",
"private": true,
"version": "0.0.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"devDependencies": {
"vite": "^7.0.0"
}
}
見るところが3つあります。
"type": "module"… このプロジェクトは ES モジュールで書く、という宣言scripts…npm run dev/npm run build/npm run previewの中身。この3行が全部ですdevDependencies… Vite は開発時にだけ必要なのでdependenciesではなくこちら。ビルド成果物には入りません
入れます。
確認: ls node_modules | wc -l で数百のディレクトリが出れば成功です。 戻し方: rm -rf node_modules package-lock.json で消して、npm install をやり直せます。
先に 5173番を開ける
新しいポートを使うので、また ufw に穴を開けます。(HTMLの回からずっと同じ手順です)
5173/tcp の行が出れば準備完了です。開けずに進むと、次の起動は成功するのにブラウザは読み込み中のまま終わります。
npm run dev — --host を付けないと見えない
起動します。ここが一番つまずくところです。
VITE v7.0.0 ready in 312 ms
➜ Local: http://localhost:5173/
➜ Network: http://192.168.226.50:5173/
--host 0.0.0.0 を付けないと、ホストのブラウザから見えません。
理由は Linux のネットワークの回 と nginx の回 で見た話と同じです。Vite の開発サーバーは、デフォルトで 127.0.0.1(自分自身)にだけ待ち受けます。 VM の中からしか繋がりません。
0.0.0.0 にすると全部のネットワークインターフェースで待ち受けるので、ホストの Windows から届きます。
確認します。VMの中で、
LISTEN 0 511 0.0.0.0:5173 0.0.0.0:* users:(("node",pid=4821,fd=21))
0.0.0.0:5173 になっていれば外向きです。ここが 127.0.0.1:5173 なら --host が効いていません。
--は何なのか。npm run dev -- --host 0.0.0.0の真ん中の--は、「ここから先は npm ではなく、実行されるコマンド(vite)への引数だ」という区切りです。 付け忘れると--hostを npm が食べてしまって、Vite に届きません。--hostを書いたのに 127.0.0.1 のまま、という時はこれです。
ホストの Windows のブラウザで、表示された Network の URL(http://192.168.226.50:5173/)を開きます。Vite のロゴとカウンターボタンのページが出れば成功です。
繋がらないときの確認順は nginx の回と同じで、内側から1段ずつです。
- VMの中で
curl -I http://localhost:5173/→ 200 が返るか(サーバー自体が動いているか) - VMの中で
ss -tlnp | grep 5173→0.0.0.0か127.0.0.1か - ホストで
ping <VMのIP>→ ネットワークが繋がっているか - VMの中で
sudo ufw status→ ファイアウォールが塞いでいないか(塞いでいればsudo ufw allow 5173/tcp)
止め方: ターミナルで Ctrl+C。
[スクリーンショット: 03_vite_dev起動.png] 左に VM のターミナル(Local/Network の2行が見えている状態)、右にホストのブラウザで開いた Vite の初期ページを並べて撮ってください。--host を付けた結果 Network 行に VM の IP が出ているのが分かる形で。
開発サーバーが速い理由
npm run dev の起動が 300ミリ秒くらいだったはずです。これは偶然ではありません。
昔のビルドツール(webpack など)の開発サーバーは、こうでした。
起動 → 全ファイルを読む → 依存を解決する → 全部まとめる → 変換する
→ メモリ上に完成品を置く → やっとブラウザに配れる
「配る前に、全部作る」です。ファイルが1000個あれば、1000個分の作業が終わるまで待ちます。大きなプロジェクトで起動に30秒〜数分というのは、これが理由です。
Vite は違います。
起動 → 待ち受けるだけ(何も作らない)
→ ブラウザが index.html を要求 → 返す
→ ブラウザが main.js を要求 → その1本だけ変換して返す
→ ブラウザが style.css を要求 → その1本だけ変換して返す
ブラウザが要求したファイルだけ、その場で変換して返す。
これができるのは、さっき確認した「ブラウザが import を理解できる」という前提があるからです。まとめて渡さなくても、ブラウザが必要なものを自分で順番に取りに来てくれる。 だからサーバー側で先に全部作っておく必要がない。
| 昔のやり方 | Vite の開発サーバー | |
|---|---|---|
| 起動時にやること | 全ファイルをバンドル | ほぼ何もしない |
| ブラウザに返すもの | 完成した1つの塊 | 要求された1ファイルずつ |
| 起動時間 | ファイル数に比例して増える | ほぼ一定 |
| 1ファイル直したとき | 影響範囲を作り直す | そのファイルだけ変換し直す |
これを Network タブで確認できます。
ホストのブラウザで F12 → Network → JS で絞って再読み込みすると、main.js、counter.js、vite/client … といったファイルが個別に並びます。 バンドルされた1本ではありません。
注意: これは開発中だけの姿です。 「本番でもファイルが200個飛ぶのか」と心配になりますが、
npm run buildした本番用はちゃんとまとまります。 Vite は開発と本番で別々の仕組みを使い分けています。 開発は「速さ優先=まとめない」、本番は「配る効率優先=まとめる」。この使い分けが Vite の設計そのものです。
node_modulesはどうしているのか。 ライブラリだけは例外で、初回起動時にまとめて事前変換(依存の事前バンドル)されます。node_modules/.vite/に置かれます。 ライブラリは滅多に変わらないうえにファイル数が異常に多い(1パッケージで数百ファイルということがある)ので、ここだけは先にまとめたほうが速いからです。変わるもの=そのつど、変わらないもの=先にまとめる、という切り分けです。
HMR — 保存すると画面が即座に変わる
開発サーバーを起動したまま、VMの中でファイルを編集します。VS Code のリモート接続で開いてもいいですし、nano でも構いません。
先に CSS で試します。 src/style.css の中の色をどれでもいいので変えて、保存します。たとえば body の background-color を #ff0000 にしてみてください。
ホストのブラウザを見てください。
再読み込みしていないのに、画面が変わっています。 Console にはこう出ます。
[vite] css hot updated: /src/style.css
これが HMR(Hot Module Replacement)です。日本語だと「モジュールの動的差し替え」。
やっていることは、こうです。
- Vite の開発サーバーが、ファイルの変更を監視している
- 変更を検知したら、そのファイルだけ変換し直す
- WebSocket でブラウザに「このモジュールが変わった」と通知する
- ブラウザ側が、そのモジュールだけ差し替える
ページ全体の再読み込みではありません。 ここが重要です。
なぜ再読み込みでは駄目なのか。 再読み込みすると、画面の状態が全部リセットされます。 フォームに10項目入力していた、モーダルを3階層開いていた、スクロールを一番下まで下げていた。保存するたびに全部消えて、また同じ操作をやり直す。 HMR は状態を保ったままコードだけ入れ替えるので、この往復が消えます。開発中の体感が一番変わるのはここです。
JS を変えると、同じにはならない
今度は src/main.js の文字列を変えて保存してください。
[vite] page reload src/main.js
hot updated ではなく page reload です。ページ全体が読み込み直されています。
差し替えではなく、再読み込みに落ちています。 理由は、この Vanilla テンプレートの main.js が「自分が差し替わったとき何をすればいいか」(import.meta.hot.accept)を書いていないからです。Vite はどう差し替えれば安全か分からないので、安全側に倒してページごと読み直します。
| 変えたファイル | Console | 状態 |
|---|---|---|
src/style.css | [vite] css hot updated | 保たれる(本当のHMR) |
src/main.js | [vite] page reload | リセットされる |
「HMR が効かない」の多くは、壊れているのではなくこれです。 React や Vue は「コンポーネント単位で差し替える」というルールが決まっているので、JSでもHMRがよく効きます。HMR の効きはフレームワーク次第、と覚えておいてください。
[スクリーンショット: 04_HMR.png] 左にエディタ(変更した style.css)、右にホストのブラウザ(色が変わった画面)を並べて撮ってください。ブラウザの Console に [vite] css hot updated: /src/style.css のログが出ている形にすると分かりやすいです。
npm run build — dist/ の中身を見る
ここが冒頭の疑問に対する答えです。
一度 Ctrl+C で開発サーバーを止めて、VMの中で、
vite v7.0.0 building for production...
✓ 9 modules transformed.
dist/index.html 0.46 kB │ gzip: 0.30 kB
dist/assets/index-DiwrgTda.css 1.24 kB │ gzip: 0.65 kB
dist/assets/index-C0sCkigK.js 1.86 kB │ gzip: 0.98 kB
✓ built in 284ms
見ます。
dist/
-rw-r--r-- index.html
drwxr-xr-x assets
-rw-r--r-- vite.svg
dist/assets/
-rw-r--r-- index-C0sCkigK.js
-rw-r--r-- index-DiwrgTda.css
-rw-r--r-- javascript-CnrDzTsG.svg
src/ にあったファイルの名前が、1つも残っていません。
中を見ます。
(function(){const t=document.createElement("link").relList;if(t&&t.supports&&t.supports("modulepreload"))return;for(const o of document.querySelectorAll('link[rel="modulepreload"]'))r(o);...
改行がありません。変数名が1文字です。 さっき見た minify そのものです。
index.html も見ます。
<!doctype html><html lang="ja"><head><meta charset="UTF-8"/><link rel="icon" type="image/svg+xml" href="/vite.svg"/><title>Vite App</title><script type="module" crossorigin src="/assets/index-C0sCkigK.js"></script><link rel="stylesheet" crossorigin href="/assets/index-DiwrgTda.css"></head><body><div id="app"></div></body></html>
元の index.html に書いてあった <script type="module" src="/src/main.js"> が、ビルド後のファイル名に書き換わっています。
これが npm run build の全体像です。
| やったこと | 結果 |
|---|---|
| トランスパイル | 新しい構文が、指定した対象ブラウザで動く形に |
| バンドル | src/ の複数ファイルが assets/index-xxx.js 1本に |
| minify | 改行なし・変数名1文字 |
| tree shaking | 使っていない export は入っていない |
| HTML の書き換え | <script> の参照先が新しいファイル名に |
[スクリーンショット: 05_dist_中身.png] ls -la dist/ dist/assets/ の出力と、npm run build のログ(ファイルサイズが並んでいるところ)が入るように撮ってください。ハッシュ付きのファイル名がはっきり読めるようにしてください。
戻し方: rm -rf dist で消せます。npm run build すればまた作られます。dist/ は「毎回作り直せる、捨てていいもの」です。この感覚が後の .gitignore の話に繋がります。
ファイル名のハッシュは何なのか
index-C0sCkigK.js の C0sCkigK の部分です。これは飾りではありません。
中身から計算された値です。中身が1バイトでも変われば、この文字列は変わります。
なぜそんなことをするのか。キャッシュ対策です。
ブラウザは、一度読んだファイルを保存して使い回します(キャッシュ)。速くていいのですが、更新したときに困ります。
ファイル名が main.js で固定だった場合:
1回目 main.js を取得 → キャッシュに保存
(あなたがバグを直して再デプロイ)
2回目 main.js → 「持ってるからそれでいいや」 → 古いコードのまま
これが「自分のブラウザでは直っているのに、ユーザーからは直っていないと言われる」の正体です。
ハッシュ付きの場合:
1回目 index-C0sCkigK.js を取得 → キャッシュに保存
(あなたがバグを直して再ビルド → 名前が index-Xy9pQr2m.js に変わる)
2回目 index.html が新しい名前を指している → 持っていない → 取りに行く
中身が変わればファイル名が変わるので、キャッシュが自動的に無効になります。
そして逆側も重要です。中身が変わらなければ名前も変わらないので、キャッシュがそのまま効き続けます。
だからサーバー側の設定はこうなります。 –
index.html… キャッシュさせない(毎回取りに来させる。ここが新しいファイル名を教える入口だから) –assets/の中身 … 思いっきりキャッシュさせる(名前が変われば別ファイル扱いなので、古いものが誤って使われることがない)ハッシュ付きファイル名は、この設定を安全に成立させるための仕組みです。
確認してみます。VMの中で src/main.js を少しだけ書き換えて、
JS のファイル名が変わっているはずです。CSS を触っていなければ、CSS の名前は変わっていません。 ここが確認できると、ハッシュが「中身から計算されている」ことが腑に落ちます。
npm run preview — 本番ビルドを確認する
dist/ ができたら、本番と同じ形で動くかを確認します。
このポートも開けます。
➜ Local: http://localhost:4173/
➜ Network: http://192.168.226.50:4173/
ポートが 5173 ではなく 4173 です。開発サーバーと混同しないよう分けてあります。ここでも --host 0.0.0.0 は必須です。
ホストのブラウザで開いて、F12 → Network を見てください。
開発サーバーのときと違って、JS が1本しか来ていません。 バンドルされた結果です。
npm run devで動くのにnpm run previewで壊れる、はよくあります。 開発と本番で仕組みが違うからです。開発中は変換していなかったものが本番では変換される、開発中は使われていたimportが tree shaking で落ちる、など。 「動いた」と言う前に、必ずnpm run build→npm run previewまで通してください。 ここを飛ばして本番で気づく、というのが一番痛いパターンです。
止め方は Ctrl+C です。
dist/ は、ただの静的ファイル
ここで一番腑に落ちてほしいことがあります。
ビルド成果物は、ただの静的ファイルです。
HTML と CSS と JS と画像。それだけです。Node.js は要りません。Vite も要りません。Webサーバーが返すだけでいい。
証明します。Vite も npm も一切使わずに dist/ を配ってみます。使うのは、HTMLの回からずっと使っている Python の簡易サーバーです。VMの中で、
ホストのブラウザで http://192.168.226.50:8000/ を開きます(IPは自分の値に)。Vite のページがそのまま出ます。
いま動いているのは Python です。 Node.js のプロセスは1つも起きていません。別のターミナルで確かめられます。
0
これが分かると、公開の話が急に簡単になります。 ビルド成果物は静的ファイルなので、nginx でも、S3 でも、GitHub Pages でも、Netlify でも、置けば動きます。 「フロントエンドのデプロイ」と言われると難しそうですが、やっているのは
dist/をどこかに置くことだけです。
確認できたら Ctrl+C で止めてください。
本物のWebサーバーで配るのは次の段階です。 Python の簡易サーバーは練習用で、本番では使いません(性能や安全性の面で本番向けではない、といった割り切りがあります)。 第6段階の nginx の回で、この
dist/をそのまま nginx に載せ替えます。~/vite-demo/は消さずに残しておいてください。
1つだけ注意があります。 今回のような1ページだけのサイトなら問題ありませんが、ページ内でURLを切り替えるタイプのアプリ(SPA)を配ると、
/aboutに直接アクセスしたときに 404 になります。サーバーは「aboutというファイルを探して、無い」と正しく答えているだけです。JS が中でURLを切り替えているだけで、そのファイルは実在しないからです。 対処は nginx ならtry_files $uri $uri/ /index.html;で見つからなければindex.htmlを返すようにすること。第4段階で扱います。今は「そういう罠がある」とだけ覚えておいてください。
静的ファイルなので、置き場所は Vite の開発サーバーである必要はなく、普通のレンタルサーバーに置いても動きます。練習用に外から見える場所へ置くなら、スターレンタルサーバー
のライトプランが 2026年11月時点で 3 ヶ月 495 円〜36 ヶ月 253 円(税込・月額換算、契約期間分の一括前払い)です。ライトは自動バックアップの対象外なので、dist/ をソースからいつでも作り直せる前提で使うのが向いています。
dist/ と node_modules/ は Git に入れない
Vite が作った .gitignore を見てください。VMの中で、
node_modules
dist
dist-ssr
*.local
.vscode/*
!.vscode/extensions.json
.DS_Store
node_modules と dist が最初から入っています。
理由は同じで、どちらも「作り直せるもの」だからです。
| 作り直す方法 | Git に入れるとどうなるか | |
|---|---|---|
node_modules/ | npm install | 数万ファイル。 クローンが遅くなり、差分が読めなくなる |
dist/ | npm run build | 毎回全部が差分になる。 minify されているので中身が読めない |
Git に入れるのは「人間が書いた、作り直せないもの」だけです。
- 入れる:
src/、index.html、package.json、package-lock.json、設定ファイル - 入れない:
node_modules/、dist/、.env(秘密情報)
package-lock.jsonは入れます。 npm の回 で見た通り、これは「実際に入ったバージョンの記録」です。これが無いと、別の人がnpm installしたときに違うバージョンが入り、「自分の環境では動く」が発生します。 生成物だけど入れる、という唯一の例外だと思ってください。
もし間違えて追加してしまった場合は、
--cached を付けると、Git の管理からだけ外れて、ファイル自体は消えません。 付け忘れると本当に消えます。ここは気をつけてください。
ソースマップ — ビルド後のコードをデバッグする地図
冒頭の話に戻ります。エラーが index-C0sCkigK.js の 1行目 4823文字目。これでは調べようがありません。
これを解決するのがソースマップです。
ソースマップは「ビルド後のこの位置は、元のファイルのこの行に対応する」という対応表です。
index-C0sCkigK.js の 1行目 4823文字目
↓ ソースマップを引くと
src/utils/format.js の 12行目 5文字目
元のコードの位置を教える地図、と考えれば正確です。
開発者ツールがこれを読むと、Sources タブに、ビルド前のファイルがそのまま表示されます。 src/main.js も src/counter.js も、自分が書いた形のまま出てきます。ブレークポイントも元のコードに置けます。
「minify したのに、なぜか開発者ツールで元のコードが見えている」のは、ソースマップが効いているからです。魔法ではありません。
Vite では、本番ビルドのソースマップはデフォルトでは出ません。VMの中で vite.config.js を作って有効にします。
-rw-r--r-- index-C0sCkigK.js
-rw-r--r-- index-C0sCkigK.js.map ← これ
-rw-r--r-- index-DiwrgTda.css
.map が増えています。 .js の末尾には、こう書かれます。
//# sourceMappingURL=index-C0sCkigK.js.map
「地図はここにあります」というメモです。開発者ツールはこれを見て .map を取りに行きます。
npm run preview -- --host 0.0.0.0 で確認して、ホストのブラウザの F12 → Sources タブを見てください。src/ のファイルが見えるようになっています。
戻し方: rm vite.config.js && npm run build でソースマップなしに戻せます。
本番にソースマップを置くべきか。賛否があります。 – 置く: エラー監視ツールが元の行番号を教えてくれる。障害対応が段違いに速い – 置かない: 元のコードが誰でも読める。コメントも変数名も全部
折衷案として、
.mapはビルドするが公開ディレクトリには置かず、エラー監視ツールにだけ渡すやり方が広く使われています。少なくとも「知らないうちに.mapが公開されている」状態は避けてください。
ビルドツールの系譜 — webpack から Vite まで
調べていると名前が大量に出てきて混乱します。整理します。
| ツール | 出た背景 | 一言でいうと | 今の立ち位置 |
|---|---|---|---|
| webpack | 2012〜 | 何でもできる代わりに、設定が長い。 画像もCSSも全部モジュールとして扱う発想を作った | 既存プロジェクトで大量に現役。 新規で選ぶ理由は減った |
| Parcel | 2017〜 | 設定ファイルなしで動く。 webpack の設定地獄への反動 | 手軽。使われてはいるが主流ではない |
| Rollup | 2015〜 | ライブラリを作るための道具。 tree shaking を広めた立役者 | 健在。Vite の本番ビルドが内部で使っている |
| esbuild | 2020〜 | Go で書かれていて、とにかく速い(10〜100倍)。機能は絞ってある | 健在。Vite の依存の事前バンドルが内部で使っている |
| Vite | 2020〜 | 開発は「まとめない」、本番は Rollup でまとめる。 使い分けが設計思想 | 今の事実上の標準 |
| Turbopack | 2022〜 | Rust 製。webpack の作者が作っている次世代版 | Next.js 中心。 単独で選ぶ場面はまだ少ない |
流れとしては、こうです。
- webpack が「何でもできる」を実現した。 代わりに設定ファイルが数百行になった
- Parcel が「設定なし」で反撃した。 でも細かい調整が効かない
- esbuild が「言語を変えれば速い」を証明した。 JavaScript で書かれたツールを JavaScript で動かしていたのが遅さの原因だった
- Vite が「そもそも開発中はまとめなくていい」と発想を変えた。 ES モジュールがブラウザで使えるようになったから成立した
今から始めるなら Vite
理由は3つです。
- 設定ファイルを書かずに始められる。 今回
vite.config.jsを書いたのはソースマップの1箇所だけでした - 開発サーバーが速い。 これは「快適」というより学習効率の問題です。保存から確認までが1秒なら試行錯誤の回数が桁で変わります
- 中身が既存の実績あるツール。 開発は esbuild、本番は Rollup。Vite は独自実装ではなく、良いものの組み合わせです
ただし「webpack を知らなくていい」わけではありません。 既存プロジェクトに入れば
webpack.config.jsが待っています。 でも最初に学ぶ道具としては Viteです。やっていること(4つの作業)は同じなので、Vite で仕組みを理解しておけば webpack の設定も「どの作業の設定なのか」として読めます。道具が変わっても、目的は変わりません。
つまずいたところ
自分が実際に詰まった箇所を残しておきます。
npm run dev は動くのに、ホストのブラウザから繋がらない → --host 0.0.0.0 の付け忘れです。9割これです。ss -tlnp | grep 5173 で 127.0.0.1 になっていないか見てください。
--host を付けたのに 127.0.0.1 のまま → -- の付け忘れです。npm run dev --host 0.0.0.0 ではなく npm run dev -- --host 0.0.0.0 です。
dist/index.html をダブルクリックで開いたら真っ白 → file:// では ES モジュールが CORS で読めません。npm run preview か nginx 経由で開いてください。
ビルドは通るのに npm run preview で真っ白、Console に 404 → サブディレクトリに置いたときに起きます。dist/index.html の中の src="/assets/..." がサイトのルートからの絶対パスだからです。サブディレクトリに置くなら vite.config.js に base: "/サブパス/" が要ります。
修正したのに、ブラウザで古い画面が出る → キャッシュです。Ctrl+Shift+R を試してください。それでも駄目ならnpm run build を打ち忘れて、古い dist/ を配っている可能性があります。
npm run build が「node_modules が無い」で失敗する → cd vite-demo を忘れて、1つ上のディレクトリで打っています。 pwd で確認してください。
後片づけ —— 開けたポートを閉じる
この記事で開けた 5173番と 4173番は、もう使いません。閉じます。
Status: active
To Action From
-- ------ ----
22/tcp ALLOW Anywhere
8000/tcp ALLOW Anywhere
8000番はここで閉じても構いません。 次の第6段階では nginx が使う 80番に移るためです。素のHTMLをもう触らないなら、
「使い終わったら閉じる」を習慣にしてください。 開けっぱなしのポートは、そこで何かが待ち受けていれば外から叩かれます。 第2段階から数えて、開けたのは 8000 / 8001 / 5173 / 4173 の4つでした。
sudo ufw statusに、いま自分が説明できない行が無いかを、ときどき見てください。
プロジェクトごと消したいときは:
ただし次の nginx の回で dist/ を使うので、それまでは残しておくことをおすすめします。
まとめ
- 「ビルド」は1つの作業ではなく、4つの別々の作業の総称。 トランスパイル・バンドル・minify・tree shaking。それぞれ別の困りごとに対する別の答え
- トランスパイルは「人間が書きたい書き方」と「ブラウザが読める書き方」の翻訳。TypeScript も JSX も、新しい構文を古いブラウザ向けに直すのも、全部これ
- バンドルは通信回数を減らすため。ファイルが8個ならリクエストは8回、という DNS・HTTPの回 で数えた話がそのまま理由になっている
- minify は空白・改行・変数名を削るだけで動作は変わらない。そして、これがデバッグを不可能にしている犯人でもある
- tree shaking が成立するのは、
importが「何を使うか」を実行前に読み取れる形だから。ES モジュールの性質に乗っている - ビルドが無かった頃の困りごとは3つ。 グローバル汚染・読み込み順・依存の管理。ES モジュールが前の2つを、npm が3つ目を解決した
- ブラウザは今
importを理解できる(<script type="module">)。だからバンドルは必須ではなくなった。 それでも本番でまとめるのは、通信回数・依存の連鎖・パッケージ名の解決という別の理由が残っているから - Vite の開発サーバーが速いのは、最適化が上手いからではなく「まとめていないから」。 ブラウザが要求したファイルだけ、その場で変換して返している
npm run devは--host 0.0.0.0を付けないと、VMの外から見えない。 さらに--を忘れると npm が引数を食べるdist/のファイル名に付くハッシュはキャッシュ対策。 中身が変われば名前が変わるのでキャッシュが自動で切れ、変わらなければキャッシュが効き続ける- ビルド成果物はただの静的ファイル。 どこかに置いて配るだけで公開できる。Node.js も Vite も本番には要らない
node_modules/とdist/は Git に入れない。 どちらも作り直せるから。ただしpackage-lock.jsonは生成物だが入れる- ソースマップは「ビルド後のこの位置は、元のこの行」という対応表。 開発者ツールで元のコードが見えるのはこれのおかげで、魔法ではない
- 今から始めるなら Vite。 設定なしで始まり、開発が速く、中身は実績のある esbuild と Rollup の組み合わせ
第3段階でできるようになったこと
これで第3段階(プログラミング)は終わりです。 振り返ります。
| 回 | できるようになったこと |
|---|---|
| JavaScript の基本 | 変数・型・関数を書ける。== と === の罠を知っている |
| DOM 操作 | ページの中身を JavaScript から書き換えられる |
| 非同期処理 | サーバーからデータを取ってきて表示できる。await の意味が分かる |
| npm とパッケージ管理 | 他人が書いたコードを取り込める。package.json が読める |
| ビルドツール(この回) | npm run build の中で何が起きているか説明できる |
最初は「ボタンを押しても何も起きないページ」でした。 今は、データを取ってきて、画面を書き換えて、本番用にビルドして、Webサーバーで公開するところまで一本の線で繋がっています。
そして、ここまで一度もフレームワークを使っていません。 これは意図的です。フレームワークが何を代わりにやってくれているのかを判断するには、代わりにやってもらう前の姿を知っている必要があるからです。
第3段階でやったことの意味は、「動かせるようになった」ことより「壊れたときに、どこを見ればいいか分かるようになった」ことのほうが大きいと思っています。dist/ の中の1行しかないファイルを見ても、もう怖くありません。
参考リンク
- roadmap.sh — Frontend(Module Bundlers)
- Vite 公式ガイド
この段階の確認
【第3段階】プログラミング は、ここで終わりです。 次に進む前に、答えを見ずに試してください。
読み終えた直後は、たいてい「分かった気」になっています。 手が動くかどうかは別です。
説明できますか
"1" == 1がtrueになるのはなぜか。ではどう書けばよいか- 「1行目が書けない」ときに、最初にやることは何か。コードを書くことではありません
- AIが書いたコードが「動いた」ことは、何の証明になっていないのか
手が動きますか
- 大きいお題を、日本語の擬似コード3行に割ってから書き始める
- 書いた関数を、境界(0件・1件・ちょうど)で試す
- 自分が書いたコードを読み返し、名前だけを直して動きが変わらないことを確かめる
- DOM を書き換えて、画面を実際に変える
1つでも詰まったら、飛ばした回があります。 そこへ戻ってください。戻るのは後退ではありません。 戻り先の目安: JavaScriptの基本の回 / 問題の分け方の回 / 読めるコードの回 / AIの検算の回
全部答えられたなら、次の段階へ進んでください。
次に読む
この記事は 【第3段階】プログラミング の 7 / 7 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- Module Bundlers(Vite / webpack)
- Task Runners
- Linters and Formatters の前提
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント