Vue Router 路由模式配置指南

路由模式概述

Vue Router 提供了兩種主要的路由模式：Hash 模式和 History 模式。每種模式都有其特定的使用場(chǎng)景和配置要求。

Hash 模式 vs History 模式

Hash 模式 (#)

• URL 格式: http://localhost:3002/#/dashboard
• 特點(diǎn): URL 中包含 # 符號
• 優(yōu)點(diǎn):
  • 兼容性好，支持所有瀏覽器
  • 無(wú)需服務(wù)器配置
  • 部署簡(jiǎn)單
• 缺點(diǎn):
  • URL 不夠美觀(guān)
  • SEO 不友好

History 模式

• URL 格式: http://localhost:3002/dashboard
• 特點(diǎn): 干凈的 URL，無(wú) # 符號
• 優(yōu)點(diǎn):
  • URL 美觀(guān)
  • SEO 友好
  • 更符合傳統網(wǎng)站習慣
• 缺點(diǎn):
  • 需要服務(wù)器配置支持
  • 兼容性要求較高

配置切換方法

1. 修改路由配置文件

編輯 src/router/index.ts 文件：

切換到 Hash 模式

import { createRouter, createWebHashHistory } from 'vue-router';
import { routes } from './routes';

const router = createRouter({
  // 使用 Hash 模式
  history: createWebHashHistory(),
  routes,
  scrollBehavior() {
    return {
      el: '#app',
      top: 0,
      behavior: 'smooth',
    };
  },
});

export default router;

切換到 History 模式

import { createRouter, createWebHistory } from 'vue-router';
import { routes } from './routes';

const router = createRouter({
  // 使用 History 模式
  history: createWebHistory(import.meta.env.VITE_BASE_URL || '/'),
  routes,
  scrollBehavior() {
    return {
      el: '#app',
      top: 0,
      behavior: 'smooth',
    };
  },
});

export default router;

2. 環(huán)境變量配置

在 .env 文件中配置基礎路徑：

# 基礎路徑配置（History 模式需要）
VITE_BASE_URL=/

# 如果部署在子目錄，例如：
# VITE_BASE_URL=/my-app/

3. Vite 配置調整

編輯 vite.config.ts 文件：

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

export default defineConfig({
  plugins: [vue()],
  base: process.env.VITE_BASE_URL || '/',
  server: {
    port: 3002,
    host: '0.0.0.0',
    // History 模式開(kāi)發(fā)服務(wù)器配置
    historyApiFallback: {
      index: '/index.html',
    },
  },
});

服務(wù)器配置（History 模式必需）

Nginx 配置

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/your/dist;
    index index.html;

    # History 模式關(guān)鍵配置
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 靜態(tài)資源緩存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Apache 配置

在項目根目錄創(chuàng )建 .htaccess 文件：

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

Express.js 配置

const express = require('express');
const path = require('path');
const app = express();

// 靜態(tài)文件服務(wù)
app.use(express.static(path.join(__dirname, 'dist')));

// History 模式支持
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist/index.html'));
});

app.listen(3000);

部署配置示例

1. GitHub Pages 部署（Hash 模式推薦）

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm install
        
      - name: Build
        run: npm run build
        
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

2. Vercel 部署（History 模式）

創(chuàng )建 vercel.json 文件：

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

3. Netlify 部署（History 模式）

創(chuàng )建 _redirects 文件：

/*    /index.html   200

選擇建議

使用 Hash 模式的場(chǎng)景

• 快速原型開(kāi)發(fā)
• 內部管理系統
• 不需要 SEO 的應用
• 簡(jiǎn)單的靜態(tài)部署環(huán)境
• 兼容性要求高的項目

使用 History 模式的場(chǎng)景

• 面向用戶(hù)的網(wǎng)站
• 需要 SEO 優(yōu)化
• 對 URL 美觀(guān)度有要求
• 有完整的服務(wù)器控制權
• 現代瀏覽器環(huán)境

常見(jiàn)問(wèn)題解決

1. History 模式刷新頁(yè)面 404

原因: 服務(wù)器沒(méi)有正確配置 fallback

解決方案:

• 確保服務(wù)器配置了 try_files 或類(lèi)似的 fallback 機制
• 檢查 base 路徑配置是否正確

2. 子目錄部署問(wèn)題

配置示例:

// 部署在 /my-app/ 子目錄
const router = createRouter({
  history: createWebHistory('/my-app/'),
  routes,
});

# .env
VITE_BASE_URL=/my-app/

3. 開(kāi)發(fā)環(huán)境和生產(chǎn)環(huán)境不一致

解決方案:

const router = createRouter({
  history: createWebHistory(
    import.meta.env.MODE === 'development' 
      ? '/' 
      : import.meta.env.VITE_BASE_URL
  ),
  routes,
});

切換步驟總結

1. 修改路由配置 - 更改 createWebHistory 或 createWebHashHistory
2. 更新環(huán)境變量 - 設置正確的 VITE_BASE_URL
3. 配置構建工具 - 更新 vite.config.ts 的 base 選項
4. 服務(wù)器配置 - History 模式需要配置 fallback
5. 測試驗證 - 確保路由跳轉和刷新都正常工作

選擇合適的路由模式對項目的用戶(hù)體驗和部署便利性都有重要影響，建議根據具體需求進(jìn)行選擇。