Node.js環境の準備
Vue 3の開発環境を構築，首先要安装Node.js运行环境。Node.jsの公式ウェブサイトから最新のLTSバージョンをダウンロードしてインストールしてください。インストールが完了したら、コマンドプロンプトまたはターミナルで以下のコマンドを実行して、正常にインストールされているか確認します。
node -v
バージョン番号が表示されれば、インストールは成功です。
パッケージマネージャーの選択
Node.jsをインストールすると、npmが自動的に利用可能になりますが、在中国大陸ではnpmのレジストリへのアクセスが遅い場合があります。解決策として、淘宝（TaoBao）が提供するcnpmを使用することを推奨します。cnpmのインストールは以下のコマンドを実行してください。
npm install -g cnpm --registry=https://registry.npmmirror.com
または、Facebookが開発したYarnを使用することもできます。
npm install -g yarn
Vue CLIのインストールとプロジェクト作成
Vue CLIのセットアップ
Vue CLIは、Vue.js公式のプロジェクトスキャフォールディングツールです。以下のコマンドのいずれかでインストールを行います。
# npmを使用する場合
npm install -g @vue/cli
# Yarnを使用する場合
yarn global add @vue/cli
# cnpmを使用する場合（高速）
cnpm install -g @vue/cli
インストールが成功したか確認するには、バージョン確認コマンドを実行します。
vue --version
バージョン情報が表示されれば、Vue CLIのインストールは完了です。
新規Vue 3プロジェクトの作成
ターミナルで、プロジェクトを配置したいディレクトリに移動し、以下のコマンドを実行して新規プロジェクトを作成します。
vue create my-vue-project
コマンドを実行すると、2つのオプションが表示されます。
- default (babel, eslint): デフォルト設定でシンプルなプロジェクトを構築
- Manually select features: 必要な機能をカスタマイズして構築
本ガイドでは、カスタム設定を選択することを推奨します。矢印キーで選択し、Enterキーで確定します。
TypeScriptの有無を選択
TypeScriptを使用する場合は、TypeScript関連のオプションを有効にします。TypeScriptを選択した場合、ファイル拡張子が.tsとなり、型安全性を確保しながら開発が行えます。TypeScriptを選択しない場合でも、Vue 3のComposition API（<script setup>構文）を利用することは可能です。
カスタマイズ設定の選択
カスタム設定を選択した後、有効化する機能を選択する画面が表示されます。スペースキーで各機能を選択し、矢印キーで移動します。
基本的な構成として、以下の2つにチェックを入れることを推奨します。
- Babel（JavaScriptのトランスパイル）
- Vue Router（ルーティング機能）
Vue Routerのモード選択
Routerの設定後、historyモードを使用するかどうか尋ねられます。特殊な要件がない限り、通常のhashモード（番号付きURL）を使用することを推奨するため、「No」を選択します。
設定の確定
残りの設定は默认值のままEnterキーで進めば問題ありません。設定が完了すると、プロジェクトの生成が開始されます。
完了後、作成されたプロジェクトディレクトリに移動して開発サーバーを起動します。
cd my-vue-project
npm run serve
# または
yarn serve
ブラウザでローカルサーバーが表示されれば、プロジェクト作成は成功です。
プロジェクトの初期最適化
Vue CLIで生成されたプロジェクトには、デモ用のファイルや設定が含まれています。本番開発に向けて、不要なファイルを削除し、構成をクリーンアップします。
アセットフォルダーの整理
src/assetsフォルダ内のロゴファイル（logo.pngなど）を削除します。これらのファイルはデモ目的で使用されていたものです。
App.vueのクリーンアップ
src/App.vueファイルを編集し、デモ用のナビゲーションコードを削除します。必要なのはルーティング出口（<router-view>）のみです。
<template>
<div id="app">
<router-view />
</div>
</template>
<style>
#app {
font-family: Avenir, Helvetica, Arial, sans-serif;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
</style>
Home.vueの簡素化
src/views/Home.vueを демоコンテンツを含まない最小構成に更新します。
<template>
<div class="home">
</div>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
export default defineComponent({
name: 'Home',
});
</script>
HelloWorldコンポーネントの削除
src/components/HelloWorld.vueファイルを削除します。このファイルはデモ用のサンプルコンポーネントです。
Aboutページの削除
About機能が必要ない場合は、src/views/About.vueファイルと、Router設定（src/router/index.ts）からAboutルート関連の定義を削除します。
vue.config.jsの追加（オプション）
開発サーバーのポート番号や自動ブラウザ起動を設定する場合、ルートディレクトリにvue.config.jsを作成します。
module.exports = {
devServer: {
host: 'localhost',
port: 3000,
open: true,
},
};
ESLintによるコード品質管理
ESLintは、JavaScriptおよびTypeScriptのコード品質を維持するための静的解析ツールです。チームのコーディング規約を統一し、潜在的なバグを早期に発見するのに役立ちます。
ESLintのインストール
プロジェクトのルートディレクトリで以下のコマンドを実行して、ESLintをローカルインストールします。
npm install eslint -D
# または
yarn add eslint -D
# または
pnpm add eslint -D
設定ファイルの生成
ESLintの初期設定を行うため、以下のコマンドを実行します。
npx eslint --init
対話形式で設定が進みます。以下のように回答することを推奨します。
- To check syntax, find problems, and enforce code style: ESLintを使用
- JavaScript modules (import/export): モジュール方式を選択
- Framework: Vue.jsを使用
- TypeScriptを使用: はい
- Browser environment: ブラウザ環境
- JavaScript config file: JavaScript設定ファイル
ESLint設定ファイルの作成
生成される.eslintrc.cjsファイルを以下のように設定します。
module.exports = {
env: {
browser: true,
es2022: true,
node: true,
},
parser: 'vue-eslint-parser',
parserOptions: {
ecmaVersion: 'latest',
sourceType: 'module',
parser: '@typescript-eslint/parser',
},
extends: [
'eslint:recommended',
'plugin:vue/vue3-essential',
'plugin:@typescript-eslint/recommended',
'plugin:prettier/recommended',
],
plugins: ['vue', '@typescript-eslint'],
rules: {
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'@typescript-eslint/no-unused-vars': 'error',
'@typescript-eslint/no-explicit-any': 'warn',
},
};
除外ファイルの指定
.eslintignoreファイルを作成して、ESLintのチェック対象外のディレクトリを指定します。
dist
node_modules
public
package.jsonへのスクリプト追加
コードチェックと自動修正のためのスクリプトを追加します。
"scripts": {
"lint": "eslint src",
"lint:fix": "eslint src --fix"
}
Prettierによるコードフォーマット
ESLintが主に構文チェックを担当するのに対し、Prettierはコード整形を専門とするツールです。行の幅、引用符、スペースなどの統一されたフォーマットを自動的に適用します。
Prettier関連パッケージのインストール
npm install -D prettier eslint-config-prettier eslint-plugin-prettier
Prettier設定ファイルの作成
ルートディレクトリに.prettierrc.jsonファイルを作成し、以下の設定を適用します。
{
"printWidth": 120,
"tabWidth": 2,
"useTabs": false,
"semi": false,
"singleQuote": true,
"bracketSpacing": true,
"trailingComma": "all",
"arrowParens": "avoid"
}
Prettier除外ファイルの設定
.prettierignoreファイルを作成します。
dist
node_modules
public
*.md
動作確認
以下のコマンドを実行して、コードの整形が行われます。
npm run lint:fix
StyleLintによるCSS/SCSS品質管理
StyleLintは、CSSおよびSCSSのコードをLintするツールです。構文エラーや推奨されない書き方を検出し、統一されたスタイルを適用します。
StyleLint関連パッケージのインストール
npm install -D stylelint stylelint-config-standard stylelint-config-recommended-scss stylelint-scss stylelint-order postcss postcss-scss
StyleLint設定ファイルの作成
ルートディレクトリに.stylelintrc.cjsファイルを作成します。
module.exports = {
extends: [
'stylelint-config-standard',
'stylelint-config-recommended-scss',
],
rules: {
'selector-class-pattern': null,
'value-keyword-case': null,
'no-descending-specificity': null,
},
};
StyleLint除外ファイルの設定
.stylelintignoreファイルを作成します。
node_modules
dist
public
Gitフックによるコミット時自動チェック
Huskyとlint-stagedを組み合わせて、Gitコミット時に自動的にコード品質チェックを実行する仕組みを構築します。これにより、品質基準を満たさないコードがリポジトリにコミットされることを防ぎます。
Huskyのセットアップ
npm install -D husky
npx husky init
lint-stagedのセットアップ
npm install -D lint-staged
package.jsonの設定
scriptsとlint-stagedの設定を追加します。
"scripts": {
"prepare": "husky install",
"lint:staged": "lint-staged"
},
"lint-staged": {
"*.{ts,vue,js}": ["eslint --fix", "prettier --write"],
"*.{css,scss}": ["stylelint --fix", "prettier --write"],
"*.json": ["prettier --write"]
}
pre-commitフックの設定
カスケードディレクトリにpre-commitファイルを追加します。
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npm run lint:staged
CommitLintによるコミットメッセージ管理
CommitLintは、Gitコミットメッセージの形式を検証するツールです。統一されたコミットメッセージ規約を適用することで、履歴の可読性を向上させます。
CommitLintのインストール
npm install -D @commitlint/cli @commitlint/config-conventional
設定ファイルの作成
ルートディレクトリにcommitlint.config.jsファイルを作成します。
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
'subject-case': [2, 'never', ['sentence-case']],
'header-max-length': [2, 'always', 72],
},
};
コミットメッセージの形式
コミットメッセージは、以下の形式に従います。
<type>: <subject>
feat: ログイン機能を追加
fix: ボタンクリック時のバグを修正
docs: READMEを更新
Huskyへのフック追加
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'
パスエイリアスの設定
srcディレクトリへのインポートを簡潔にするため、エイリアス（別名）を設定します。
Viteプロジェクトの場合
vite.config.tsファイルを以下のように設定します。
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import path from 'path';
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
},
},
});
TypeScript認識の設定
TypeScriptがエイリアスを認識するよう、tsconfig.json（またはjsconfig.json）に以下を追加します。
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
webpackプロジェクトの場合
vue.config.jsに設定を追加します。
const path = require('path');
module.exports = {
configureWebpack: {
resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
},
},
},
};
環境変数の設定
開発環境、本番環境、テスト環境で異なる設定を使用するため、環境変数を設定します。
環境ファイルの作成
ルートディレクトリに以下のファイルを作成します。
.env.development（開発環境用）
VITE_API_BASE_URL=http://localhost:8080/api
VITE_APP_TITLE=開発環境
.env.production（本番環境用）
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=本番環境
.env.test（テスト環境用）
VITE_API_BASE_URL=https://test-api.example.com
VITE_APP_TITLE=テスト環境
環境変数の使用方法
Vueコンポーネント内で以下のように環境変数を参照します。
console.log(import.meta.env.VITE_API_BASE_URL);
環境切り替えの実行
# 開発環境
npm run dev
# 本番環境
npm run build
# テスト環境
npm run build -- --mode test
開発サーバー設定のカスタマイズ
vite.config.tsファイルで開発サーバーの詳細設定を行います。
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
plugins: [vue()],
server: {
host: '0.0.0.0',
port: 3000,
open: true,
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
},
},
},
});
パッケージマネージャー強制設定
チーム内で統一されたパッケージマネージャーを使用するため、インストール時に強制チェックを行うスクリプトを作成します。
preinstallスクリプトの作成
scripts/preinstall.jsファイルを作成します。
if (!/npm/.test(process.env.npm_execpath || '')) {
console.warn('⚠️ This project requires npm as the package manager.');
process.exit(1);
}
package.jsonへの登録
"scripts": {
"preinstall": "node scripts/preinstall.js"
}
この設定により、npm以外のパッケージマネージャー（yarn、pnpmなど）でインストールを試みた場合、インストールが中止されます。
プロジェクトの起動確認
すべての設定が完了したら、以下のコマンドで開発サーバーを起動し、プロジェクトが正常に動作することを確認します。
npm install
npm run dev
ブラウザで指定されたURL（通常はhttp://localhost:3000）にアクセスし、ページが表示されれば環境構築は完了です。