Import Alias：~ vs @ 在不同框架的慣例

發佈於 2025-12-05 最後更新於 2025-12-08

5 min read

next.js

nuxt

nuxt3

Table of Contents

最近在重構專案時，發現自己一直習慣用 @ 來做 import alias，但 Nuxt3 的官方文件卻都用 ~。這讓我開始好奇：這兩個符號到底有什麼差異？各個框架的慣例又是什麼？

問題起源

我從 Nuxt2 / Vue2 時代就習慣這樣寫：

typescript

import MyComponent from '@/components/MyComponent'
import { api } from '@/api/request'

但在看 Nuxt3 官方文件時，卻常常看到這樣的寫法：

typescript

import MyComponent from '~/components/MyComponent'
import { api } from '~/api/request'

這讓我開始懷疑：我是不是用錯了？

~ 和 @ 的差異

在 Nuxt 中

Nuxt 2 時代：主要用 @

typescript

// Nuxt 2 常見寫法
import MyComponent from '@/components/MyComponent'

Nuxt 3 時代：官方文件主要用 ~

typescript

// Nuxt 3 官方範例
import { resolveAlias } from '@nuxt/kit'
const resolvedPath = resolveAlias('~/components/button')

但重點是：Nuxt 3 同時支援 ~ 和 @，兩者都指向專案根目錄。

你可以在 Nuxt 的官方文件¹中看到，resolveAlias 函式會根據 nuxt.options.alias 來解析路徑，而預設的 alias 設定包含了 ~ 和 @。

在 Next.js 中

根據 Next.js 官方文件²：

The default setup enables TypeScript, Tailwind, ESLint, App Router, and Turbopack, with import alias @/*.

Next.js 預設用 @：

typescript

// tsconfig.json (Next.js 預設)
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]  // ← Next.js 預設
    }
  }
}

typescript

// 使用範例
import Button from '@/components/Button'
import { api } from '@/lib/api'

在 Vite 中

Vite 本身不預設任何 alias，需要手動配置³：

typescript

// vite.config.ts
export default defineConfig({
  resolve: {
    alias: {
      '@': '/src',  // 常見做法
      '~': '/',     // 也可以
    }
  }
})

各框架的慣例總結

框架/工具	預設/推薦	說明
Next.js	`@`	官方預設，React 生態主流
Nuxt 2	`@`	早期預設
Nuxt 3	`~`	官方文件主要用這個
Vue CLI	`@`	Vue 2 時代的標準
Vite	無預設	看專案配置

為什麼會有這個差異？

~ 的語意

~ 在 Unix/Linux 系統中代表「home directory」，所以用 ~ 來代表專案根目錄在語意上是合理的。

@ 的由來

@ 最早是 Webpack 的慣例，後來被 Vue CLI 和 Create React App 採用，逐漸成為 JavaScript 生態系的主流。

TypeScript 的 paths 設定也常用 @：

json

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

我該用哪一個？

這個問題沒有標準答案，但我的建議是：

如果你是 Nuxt 專案

兩個都可以，選你習慣的。

用 ~：符合 Nuxt3 官方文件的風格
用 @：和 React/Next.js 生態一致，團隊如果有跨框架經驗會更熟悉

如果你是 Next.js 專案

用 @，因為這是官方預設。

如果你是跨框架開發者

用 @，因為它在整個 JavaScript 生態系更通用。

我的選擇

我決定繼續用 @，理由是：

習慣了：從 Nuxt2 時代就這樣寫
更通用：Next.js、Vue CLI、很多 Vite 專案都用 @
團隊友善：如果未來有 React 開發者加入，他們會更熟悉
Nuxt3 完全支援：沒有任何技術上的問題

實際範例

這是我目前專案的寫法：

typescript

// api/products/api.ts
import { createAuthenticatedFetch } from '~/api/request'  // 用 ~ 也可以
// 或
import { createAuthenticatedFetch } from '@/api/request'  // 用 @ 也可以

const { public: { API_BASE_URL } } = useRuntimeConfig()

export async function fetchProductList() {
  const request = createAuthenticatedFetch()
  
  const resp = await request('/api/products', {
    baseURL: API_BASE_URL,
  })
  return resp
}

兩種寫法在 Nuxt3 中都完全正常運作。

總結

~ 和 @ 在 Nuxt3 中都可以用，沒有對錯之分
Next.js 預設用 @，這是 React 生態的主流
選擇你習慣的就好，重點是團隊內保持一致
不需要為了符合官方文件而改變習慣，除非有實質的技術理由

最後，記得：程式碼的一致性比用哪個符號更重要。如果你的專案已經用 @ 了，就繼續用吧；如果是新專案，可以考慮用 ~ 來符合 Nuxt3 的風格。