TypeScript 路徑別名

TypeScript 路徑別名讓您可以使用簡短的別名來替代冗長的相對路徑，使程式碼更易讀且易於維護。

什麼是路徑別名？

路徑別名允許您將長路徑替換為簡短的識別符：

// 使用相對路徑（冗長）
import { Button } from '../../../components/ui/Button';
import { useAuth } from '../../../../hooks/useAuth';
 
// 使用路徑別名（簡潔）
import { Button } from '@/components/ui/Button';
import { useAuth } from '@/hooks/useAuth';

設定 tsconfig.json

在 tsconfig.json 中的 compilerOptions 中定義路徑別名：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@hooks/*": ["src/hooks/*"],
      "@utils/*": ["src/utils/*"],
      "@assets/*": ["src/assets/*"]
    }
  }
}

設定 Webpack（Remotion 必需）

僅設定 tsconfig.json 中的路徑別名還不夠，因為 Remotion 使用 Webpack 進行打包，Webpack 並不自動讀取 TypeScript 的路徑設定。

您需要使用 tsconfig-paths-webpack-plugin 或手動設定 Webpack 的 resolve.alias。

方法一：使用 tsconfig-paths-webpack-plugin

安裝套件：

npm install -D tsconfig-paths-webpack-plugin

在 remotion.config.ts 中設定：

import { Config } from '@remotion/cli/config';
import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
 
Config.overrideWebpackConfig((config) => {
  return {
    ...config,
    resolve: {
      ...config.resolve,
      plugins: [
        ...(config.resolve?.plugins ?? []),
        new TsconfigPathsPlugin(),
      ],
    },
  };
});

方法二：手動設定 resolve.alias

import { Config } from '@remotion/cli/config';
import path from 'path';
 
Config.overrideWebpackConfig((config) => {
  return {
    ...config,
    resolve: {
      ...config.resolve,
      alias: {
        ...config.resolve?.alias,
        '@': path.resolve(__dirname, 'src'),
        '@components': path.resolve(__dirname, 'src/components'),
        '@hooks': path.resolve(__dirname, 'src/hooks'),
        '@utils': path.resolve(__dirname, 'src/utils'),
      },
    },
  };
});

在 bundle() 和 deploySite() 中使用

當使用 Node.js API 進行渲染時，也需要傳遞 Webpack 覆蓋函數：

// webpack-override.ts
import { WebpackOverrideFn } from '@remotion/bundler';
import path from 'path';
 
export const webpackOverride: WebpackOverrideFn = (config) => {
  return {
    ...config,
    resolve: {
      ...config.resolve,
      alias: {
        ...config.resolve?.alias,
        '@': path.resolve(__dirname, '../src'),
      },
    },
  };
};

// render.ts
import { bundle } from '@remotion/bundler';
import { webpackOverride } from './webpack-override';
 
const bundleLocation = await bundle({
  entryPoint: './src/index.ts',
  webpackOverride,
});

完整範例

設定完成後，您可以這樣使用路徑別名：

// src/compositions/IntroVideo.tsx
import { AbsoluteFill } from 'remotion';
import { AnimatedText } from '@components/AnimatedText';
import { useVideoTransition } from '@hooks/useVideoTransition';
import { formatDuration } from '@utils/formatDuration';
 
export const IntroVideo = () => {
  const { opacity } = useVideoTransition();
  return (
    <AbsoluteFill style={{ opacity }}>
      <AnimatedText text="Hello World" />
    </AbsoluteFill>
  );
};

驗證設定

安裝 @types/node 並執行 TypeScript 編譯器檢查：

npx tsc --noEmit

若無錯誤輸出，表示路徑別名設定正確。

常見問題

路徑解析錯誤

如果遇到 Cannot find module '@/...' 錯誤，請確認：

tsconfig.json 中的 baseUrl 設定正確
Webpack 的 resolve.alias 路徑為絕對路徑
tsconfig-paths-webpack-plugin（若使用）已正確安裝

渲染時找不到模組

確保在所有使用 bundle() 的地方都傳遞了相同的 webpackOverride 函數。