@/ エイリアスは三箇所に設定する。どれが欠けても壊れる

../../.. を禁止するのは言うのは簡単ですが、三つのツールチェーンすべてで成立させるのは難しい作業です。このサイトは @/ を src に向け、設定は三箇所に分かれています。

それぞれの担当

• astro.config.mjs の vite.resolve.alias：バンドルと dev のモジュール解決。
• tsconfig.json の paths：エディタの補完と astro check の型解決。
• SCSS の loadPaths：スタイル内 @use のパス解決。

三つは独立した解決経路で、互いの設定を読みません。

一つ欠けたときの症状

Vite だけ：エディタで @/components/X.astro が赤くなるがビルドは通ります。tsconfig だけ：エディタは快適でビルドがモジュールを見つけられません。loadPaths が無い：スタイルの @use が File not found になります。

三つの症状は同じ原因には見えないので、ここは記憶より表のほうが確実です。

スタイルで @/ を書かない理由

SCSS の @use は Vite のエイリアスを通らず、loadPaths しか見ません。したがってスタイル内はルート相対で書きます。

@use 'styles/settings/tokens';

@/ と同じ目的地を別のツールチェーン向けに書いたもので、互いの代わりにはなりません。

相対パスが必須の二箇所

import.meta.glob はビルド時の静的解析で、リテラルのパスが必要です。エイリアスは効かず、パターンを変数にもできません。そのため lib/registry.ts と lib/mount.ts のレジストリが唯一の相対パスで、これはフレームワークの制約であって手抜きではありません。

得られるもの

ファイルを移動しても import を直さずに済み、@/ は外部パッケージと即座に見分けられ、階層の深さが読みやすさに影響しなくなります。代償はこの三箇所を同時に更新する必要があることです。