Vueアプリのビルドと公開｜npm run build・base・404対策

Vueアプリのビルドと公開とは

Vite で作った Vue のアプリは、開発中は npm run dev で動かしますが、公開するときは npm run build で公開用のファイルを作り、それをサーバーに置きます。できあがるのは、HTML・CSS・JavaScript だけのファイル（静的ファイル）なので、HTML のサイトと同じようにレンタルサーバーなどに置けます。

公開でつまずく原因は、ほとんどが2つです。置き場所の設定（base）と、Vue Router で直接開いた URL が 404 になる問題です。この記事では、2026年10月時点の Vite 8.3.3 で実際にビルドして確かめた結果をもとに、手順と対策をまとめます。

基本（3つのコマンド）

コマンド すること 結果
npm run build 公開用にファイルをまとめて小さくする dist フォルダができる
npm run preview dist を手元で表示して確かめる 既定で http://localhost:4173/
（アップロード） dist の中身をサーバーの公開用フォルダに置く 公開 URL で表示される

Vite の公式は、vite preview はビルドをローカルで確かめるためのもので、本番のサーバーとしては使えないと注意しています。また、Vue 公式は、create-vue（Vite ベース）で作ったプロジェクトは、本番向けのビルドがあらかじめ設定されていると説明しています。

具体例（ビルドの結果と base）

npm run build を実行すると、次のような一覧が表示され、dist ができました（ファイル名の英数字はビルドごとに変わります）。

dist/index.html                     0.42 kB
dist/assets/index-BTqy5bqE.css      0.05 kB
dist/assets/AboutView-C6Tgs5jo.js   0.33 kB
dist/assets/index-CqZUqdwX.js      93.54 kB
✓ built in 170ms

何も設定しないと、dist/index.html の中は /assets/index-….js のように、ドメインの直下を前提にした場所を指します。https://example.com/myapp/ のようにフォルダの中に置くときは、vite.config.js に base を足します。

// vite.config.js（create-vue が作ったものに、base の1行を足した全体）
import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'

// https://vite.dev/config/
export default defineConfig({
  base: '/myapp/',
  plugins: [
    vue(),
    vueDevTools(),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

base を /myapp/ にしてビルドすると、index.html の中の場所が /myapp/assets/… に変わることを確かめました。

動作確認（検証環境と結果）

  • Node.js v24.19.0、Vue 3.5.43、Vite 8.3.3、Vue Router 5.3.1、Microsoft Edge、2026年10月。
  • npm run preview では、トップからの移動も、/about の直接表示（再読み込み）も表示されました。
  • フォールバックの設定がない簡易サーバーに dist を置くと、トップからの移動では表示されましたが、/about の再読み込みでは 404 になりました。
  • 下の .htaccess を public フォルダに置いてビルドすると dist にコピーされ、Apache（XAMPP に入っている版）で配信すると、/about を直接開いても表示されました。/myapp/ に置く版の .htaccess と、ハッシュモード（/#/about）でも表示を確かめました。
  • dist/index.html をダブルクリックして直接開くと、画面は真っ白でした（file:// では JavaScript のモジュールが読み込めないため）。

Vueアプリのビルドと公開の実践ステップ

  1. 開発用サーバーを止め、npm run build を実行します。
  2. npm run preview を実行し、表示された URL で、全画面の表示と切り替えを確かめます。
  3. フォルダの中に置く場合は、vite.config.js に base を設定してから、もう一度ビルドします。
  4. dist の中身を、サーバーの公開用フォルダに SFTP などでアップロードします。
  5. Vue Router の createWebHistory を使っている場合は、サーバーにフォールバックを設定します。サーバーが Apache なら、プロジェクトの public フォルダに .htaccess を作り、Vue Router 公式の例を書きます（public のファイルは、ビルドで dist にそのままコピーされます。使えるかはサーバーのマニュアルで確認してください）。
<IfModule mod_negotiation.c>
  Options -MultiViews
</IfModule>
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . index.html [L]
</IfModule>

nginx の場合、公式の例は、サーバーの設定ファイルの location / { } の中に try_files $uri $uri/ /index.html; の1行を書く形です。設定ファイルを自分で書き換えられるかは、サーバー会社の案内で確かめます。

フォルダの中（例：/myapp/）に置く場合は、base: '/myapp/' に加えて、.htaccess の RewriteBase と最後の行も合わせます。

<IfModule mod_negotiation.c>
  Options -MultiViews
</IfModule>
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /myapp/
  RewriteRule ^index.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /myapp/index.html [L]
</IfModule>

設定ができない・サーバーの種類が分からない場合は、src/router/index.js の2か所を書き換えてハッシュモードにします。

// 変更前
import { createRouter, createWebHistory } from 'vue-router'
  history: createWebHistory(import.meta.env.BASE_URL),
// 変更後
import { createRouter, createWebHashHistory } from 'vue-router'
  history: createWebHashHistory(import.meta.env.BASE_URL),

URL は /#/about のように # 付きになり、# から後ろはサーバーに送られないので、直接開いても 404 になりません。

  1. 公開 URL で、トップと、/about などの URL を直接開いて表示されるかを確かめます。

Vueアプリのビルドと公開の注意点

  • 上の最初の Apache の例は、ドメインの直下に置く前提です。フォルダの中に置くときは、RewriteBase なども合わせて変える必要があると、Vue Router 公式は説明しています。
  • ハッシュモードはサーバーの設定が要りません。ただし、Vue Router の公式は SEO に悪い影響があると説明しています。
  • ビルドしたファイルは誰でも中身を読めます。API キーなどの秘密の値を書かないようにします。

Vueアプリのビルドと公開でよくあるミス

  • dist フォルダごとアップロードして、URL に /dist/ が付く。
  • フォルダの中に置いたのに base を設定せず、画面が真っ白になる。
  • npm run preview で問題がなかったので、本番のフォールバックを設定し忘れる。
  • 直したのにビルドし直さず、古い dist を送る。

Vueアプリのビルドと公開のチェックリスト

  • [ ] npm run build で dist を作った
  • [ ] npm run preview で全画面を確かめた
  • [ ] 置き場所がフォルダの中なら、base を設定した
  • [ ] dist の中身をアップロードした
  • [ ] URL を直接開いても 404 にならないことを確かめた

Vueアプリのビルドと公開のFAQ（よくある質問）

Q. npm run build で TypeScript のエラーが出ます。

A. TypeScript を選んで作ったプロジェクトでは、ビルドの前に型のチェックが行われる設定になっています。表示されたファイルと行を直してから、もう一度ビルドします。

Q. 画面が真っ白で、Console に JavaScript ファイルの 404 が出ます。

A. 置き場所と base が合っていません。dist/index.html の中の /assets/… の場所と、実際に置いた場所を見比べます。

Q. CDN で作った Vue のページを公開するときの注意は？

A. Vue 公式は、本番では末尾が .prod.js の本番向けビルドを使うよう案内しています。

筆者の見解（Vueアプリのビルドと公開）

ビルドと公開は、開発中には見えなかった問題がまとめて出てくる工程だと感じます。私は、最初のアプリでは、作り込む前に一度「空に近い状態で公開してみる」ことを勧めます。base やフォールバックの問題は、画面が少ないうちに解決しておくほうが、原因を切り分けやすいからです。npm run preview で確かめたうえで、本番の URL を直接開く確認までを1セットにすると安心だと考えます。

Vueアプリのビルドと公開の関連項目

出典（一次情報）

タイトルとURLをコピーしました