Сопоставление путей TypeScript paths

paths — это опция конфигурации в tsconfig.json, используемая для настройки псевдонимов путей к модулям.

Он делает пути импорта более краткими, сохраняя структуру кода организованной и понятной.


SVG-диаграмма: Как работает сопоставление путей Background Title How Path Mapping paths Works Original Import Original Import Path import Button from "../../components/Button" Arrow After Path Mapping Import Using Alias import Button from "@/components/Button" Arrow tsconfig paths Configuration Bottom Section: Configuration Options paths Configuration Option Configuration 1 baseUrl Base Path Configuration 2 paths Path Aliases Configuration 3 rootDirs Root Directories Arrow Marker

Зачем нужно сопоставление путей

По мере роста размера проекта структура каталогов файлов становится глубже.

Использование относительных путей для импорта файлов (например, ../../../components/Button) делает код трудным для чтения и поддержки.

Сопоставление путей позволяет использовать псевдонимы (например, @/components/Button) для замены длинных относительных путей.

Псевдоним:Псевдонимы путей делают пути импорта более краткими и упрощают изменение структуры проекта.


Базовая конфигурация

Настройте paths и baseUrl в tsconfig.json.

tsconfig.json

{
    "compilerOptions": {
        // Базовый путь: корневой каталог для всех псевдонимов путей
        "baseUrl": ".",

        // Конфигурация сопоставления путей
        "paths": {
            // Псевдоним, начинающийся с @/, указывающий на каталог src
            "@/*": ["src/*"],

            // Псевдоним, начинающийся с @components
            "@components/*": ["src/components/*"],

            // Псевдоним, начинающийся с @utils
            "@utils/*": ["src/utils/*"],

            // Псевдоним, начинающийся с @services
            "@services/*": ["src/services/*"],

            // Псевдоним, начинающийся с @assets
            "@assets/*": ["src/assets/*"],

            // Псевдоним, начинающийся с @types
            "@types/*": ["src/types/*"]
        }
    }
}

baseUrl:После установки baseUrl пути в параметре paths будут разрешаться относительно этого каталога.


Использование псевдонимов путей

После завершения настройки вы можете использовать псевдонимы для импорта модулей в вашем коде.

src/components/Button.tsx

// Импорт с использованием псевдонима пути
import { Button } from '@/components/Button';
import { User } from '@types/user';
import { fetchUser } from '@services/userApi';
import { formatDate } from '@utils/date';

// Импорт стилей
import styles from '@/components/Button.module.css';

// Импорт изображений
import logo from '@assets/logo.png';

// Использовать импортированный модуль
const handleClick = () => {
    console.log('Button clicked');
};

const userButton = new Button({
    text: 'Пользователь',
    onClick: handleClick
});

console.log('Компонент успешно загружен');

Синтаксис:Используйте * как подстановочный знак в конфигурации paths и сопоставляйте фактический путь с * при импорте.


Конфигурация псевдонимов Webpack

Если вы используете Webpack, также необходимо настроить resolve.alias для поддержки во время выполнения.

webpack.config.js

// Импорт модуля webpack
const path = require('path');

// Конфигурация Webpack
module.exports = {
    // Другая конфигурация...
    resolve: {
        // Конфигурация псевдонимов путей должна оставаться согласованной с tsconfig.json
        alias: {
            // Псевдоним, начинающийся с @
            '@': path.resolve(__dirname, 'src'),

            // Другие псевдонимы
            '@components': path.resolve(__dirname, 'src/components'),
            '@utils': path.resolve(__dirname, 'src/utils'),
            '@services': path.resolve(__dirname, 'src/services'),
            '@types': path.resolve(__dirname, 'src/types'),
            '@assets': path.resolve(__dirname, 'src/assets')
        },

        // Расширения файлов
        extensions: ['.ts', '.tsx', '.js', '.jsx', '.json']
    }
};

Согласованность во время выполнения:Конфигурация alias в Webpack должна быть согласована с конфигурацией paths в TypeScript, иначе во время выполнения возникнет ошибка «модуль не найден».


Конфигурация Vite

При использовании Vite необходимо настроить как tsconfig.json, так и vite.config.ts.

vite.config.ts

// Импорт модуля vite
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

// Конфигурация Vite
export default defineConfig({
    plugins: [react()],

    // Конфигурация псевдонимов путей
    resolve: {
        alias: {
            '@': path.resolve(__dirname, './src'),
            '@components': path.resolve(__dirname, './src/components'),
            '@utils': path.resolve(__dirname, './src/utils'),
            '@services': path.resolve(__dirname, './src/services'),
            '@types': path.resolve(__dirname, './src/types'),
            '@assets': path.resolve(__dirname, './src/assets')
        }
    }
});

Vite:Vite использует Rollup в качестве движка сборки, поэтому вам нужно настроить псевдонимы в resolve.alias.


Конфигурация путей для нескольких проектов

В проектах Monorepo можно настроить псевдонимы путей между пакетами.

tsconfig.json (Monorepo)

{
    "compilerOptions": {
        // Базовый путь
        "baseUrl": ".",

        // Сопоставление путей, поддерживает ссылки между пакетами
        "paths": {
            // Ссылки на модули из текущего пакета
            "@/*": ["src/*"],

            // Ссылки на модули из других пакетов
            "@my-ui/button": ["packages/ui-button/src/index.ts"],
            "@my-ui/modal": ["packages/ui-modal/src/index.ts"],
            "@my-utils/date": ["packages/utils-date/src/index.ts"],
            "@my-hooks/useFetch": ["packages/hooks-use-fetch/src/index.ts"]
        }
    }
}

Monorepo:В проектах Monorepo пути могут ссылаться на исходные пути других пакетов.


Примечания

  • Требуется baseUrl:paths должны использоваться вместе с baseUrl
  • Сопоставление по шаблону:Используйте * для сопоставления с любым путём
  • Соблюдайте согласованность:Конфигурация Webpack/Vite должна оставаться согласованной с tsconfig
  • Относительные пути:Пути в опции paths указываются относительно baseUrl

Лучшие практики:Использование псевдонимов путей может сделать код более кратким, но не злоупотребляйте ими; рекомендуется унифицировать соглашения об именовании.


Итог

Сопоставление путей — важный инструмент для управления путями импорта в проектах TypeScript.

  • paths:Настройте псевдонимы путей
  • baseUrl:Задайте базовый путь
  • Подстановочный знак:Используйте * для сопоставления с любыми символами
  • Инструменты сборки:Webpack/Vite требуют синхронизированной конфигурации

Рекомендация:Настройте псевдонимы путей для часто используемых каталогов, чтобы улучшить читаемость и поддерживаемость кода.

Другие расширения