Vite + Vue 3 + Tailwind CSS 4 + shadcn-vue 安裝心得與常見踩坑

專案環境

• Vite 7
• Vue 3
• TypeScript
• Pinia
• Vue Router
• unplugin-vue-router
• Tailwind CSS 4
• shadcn-vue

1. Vite 與 Vike 的差異

Vite

• 前端建置工具（Build Tool）
• 提供快速開發伺服器（HMR）
• 不內建 Router、SSR

適合： - SPA - 後台系統 - Vue / React 專案

Vike

• 建立在 Vite 之上的 Web Framework
• 提供 SSR、Routing、SEO 等能力
• 類似 Next.js（React）或 Nuxt（Vue）

2. Vue 專案一定要安裝 vue-router 嗎？

如果只有一個畫面，可以不用。

只要有：

• /login
• /dashboard
• /house/:id

就需要 vue-router。

unplugin-vue-router 不是 Router

它只是：

• 自動產生 routes
• 提供型別安全
• 使用檔案式路由

底層仍然是 vue-router。

安裝：

npm install vue-router
npm install -D unplugin-vue-router

3. Tailwind CSS 4 的重大變更

Tailwind CSS 4 已經不能再把 tailwindcss 當作 PostCSS Plugin 使用。

以前：

tailwindcss

現在需要：

npm install -D @tailwindcss/postcss

PostCSS：

import tailwindcss from "@tailwindcss/postcss"
import autoprefixer from "autoprefixer"

export default {
  plugins: {
    tailwindcss,
    autoprefixer,
  },
}

4. package.json 使用 "type": "module" 要注意

如果 package.json：

{
  "type": "module"
}

代表：

• .js 會被視為 ESM
• 不可使用：

module.exports = {}

必須改成：

export default {}

或者把設定檔改成 .cjs。

5. 為什麼 npx tailwindcss init -p 失敗？

錯誤：

npm error could not determine executable to run

在 Tailwind CSS 4 已經不一定需要依賴這個指令。

可以直接：

• 手動建立 Tailwind Config
• 或直接使用官方新的設定方式

因此不用執著於 init -p。

6. shadcn-vue 是否可以使用？

可以。

React 使用：

• shadcn/ui

Vue 使用：

• shadcn-vue

不能直接把 React 的 shadcn/ui 放進 Vue 專案。

7. Element Plus → shadcn-vue

常見對照：

Element Plus shadcn-vue

el-card Card el-button Button el-input Input el-select Select el-dialog Dialog el-slider Slider el-table Table

8. Git Push 出現 Invalid username or token

如果看到：

Password authentication is not supported

代表目前還在使用 HTTPS。

建議改用 SSH：

git remote set-url origin git@github.com:USER/REPO.git

測試：

ssh -T git@github.com

本次重點整理

• Vite 是 Build Tool，不是 Framework。
• Vike 提供 SSR 與 Routing。
• Vue 多頁面專案需要 vue-router。
• unplugin-vue-router 只是自動產生 routes。
• Tailwind CSS 4 已改用 @tailwindcss/postcss。
• "type": "module" 專案要使用 ESM (export default) 或 .cjs。
• Vue 專案請使用 shadcn-vue，不是 React 的 shadcn/ui。
• GitHub 建議使用 SSH 推送，不要使用密碼。