Przejdź do głównej zawartości

Instalacja i konfiguracja Astro

Polecenie CLI create astro to najszybszy sposób na rozpoczęcie nowego projektu Astro od zera. Przeprowadzi Cię ono przez każdy etap konfiguracji nowego projektu Astro i pozwoli wybrać pomiędzy różnymi szablonami startowymi.

Możesz również rozpocząć swój projekt używając istniejącego motywu lub szablonu startowego.

Aby zainstalować Astro ręcznie, zapoznaj się z naszym szczegółowym przewodnikiem instalacji ręcznej.

  • Node.js - v18.17.1 lub v20.3.0 albo nowsza. ( v19 nie jest wspierana.)
  • Edytor kodu - Polecamy VS Code z naszą oficjalną wtyczką Astro.
  • Terminal - Astro jest dostępne poprzez interfejs wiersza poleceń (CLI).

Astro jest budowane przy użyciu bundlera Vite, który domyślnie generuje kod dla przeglądarek obsługujących współczesny JavaScript. Aby uzyskać pełne informacje, możesz sprawdzić listę przeglądarek aktualnie wspieranych przez Vite.

  1. Uruchom poniższe polecenie w swoim terminalu, żeby zainicjalizować projekt:

    Okno terminala
    # stwórz nowy projekt przy użyciu npm
    npm create astro@latest

    Możesz uruchomić polecenie create astro w dowolnym miejscu na swoim komputerze, więc nie musisz tworzyć nowego, pustego katalogu dla Twojego projektu przed rozpoczęciem. Jeżeli nie masz jeszcze pustego folderu na Twój nowy projekt, asystent inicjalizacji stworzy go automatycznie.

    Jeśli wszystko poszło zgodnie z planem, to zobaczysz wiadomość o sukcesie, po której pojawią się kolejne sugerowane kroki. Teraz, kiedy Twój projekt został stworzony, możesz przy pomocy polecenia cd przejść do folderu z projektem, aby zacząć korzystać z Astro.

  2. Jeżeli podczas inicjalizacji pominąłeś krok wykonujący npm install, to upewnij się, żeby zainstalować zależności projektu przed przejściem dalej.

  3. Teraz możesz uruchomić serwer deweloperski Astro i sprawdzać podgląd Twojego projektu na żywo podczas tworzenia aplikacji!

Możesz również rozpocząć nowy projekt Astro i oprzeć go o oficjalny przykład albo o gałąź main dowolnego repozytorium na GitHubie, przekazując argument z flagą --template do polecenia create astro.

  1. Przejrzyj nasze motywy i przykładowe szablony, gdzie znajdziesz motywy dla blogów, portfolio, stron z dokumentacją, stron docelowych i wiele więcej! Możesz także poszukać na GitHubie, aby znaleźć jeszcze więcej projektów startowych.

  2. Uruchom następujące polecenie w swoim terminalu, podając nazwę oficjalnego szablonu startowego Astro lub nazwę użytkownika i repozytorium GitHub motywu, którego chcesz użyć:

    Okno terminala
    # stwórz nowy projekt przy użyciu oficjalnego przykładu
    npm create astro@latest -- --template <example-name>
    # stwórz nowy projekt oparty na gałęzi "main" repozytorium z GitHub
    npm create astro@latest -- --template <github-username>/<github-repo>

    W trybie domyślnym, polecenie użyje gałęzi “main” danego repozytorium. Żeby użyć innej nazwy gałęzi, jako część flagi --template przekaż argument: <github-username>/<github-repo>#<branch>.

  3. Odpowiedz na pytania i podążaj za instrukcjami konfiguratora CLI.

  4. Możesz teraz uruchomić serwer deweloperski Astro i zobaczyć podgląd swojego projektu na żywo, podczas gdy dostosowujesz go do swoich potrzeb!

Aby wprowadzić zmiany w swoim projekcie, otwórz folder z projektem w edytorze kodu. Praca w trybie deweloperskim z uruchomioną funkcją serwera deweloperskiego umożliwia bieżący podgląd zmian w przeglądarce.

Możesz również skonfigurować różne aspekty środowiska deweloperskiego, takie jak TypeScript lub dodanie oficjalnej wtyczki do edytora kodu.

Astro ma wbudowany serwer deweloperski, który zawiera wszystko, czego potrzebujesz do rozwoju projektu. Polecenie CLI astro dev uruchomi lokalny serwer deweloperski, dzięki czemu po raz pierwszy zobaczysz swoją nową stronę internetową w działaniu.

Każdy szablon startowy zawiera wstępnie skonfigurowany skrypt, który uruchomi astro dev za Ciebie. Po przejściu do katalogu projektu, użyj swojego ulubionego menedżera pakietów, aby uruchomić to polecenie i rozpocząć serwer deweloperski Astro.

Okno terminala
npm run dev

Jeżeli wszystko pójdzie zgodnie z planem, Astro uruchomi Twój projekt pod adresem http://localhost:4321/. Odwiedź ten link w przeglądarce i zobacz swoją nową stronę!

Astro będzie nasłuchiwać zmian w Twoim folderze src/ oraz aktualizować podgląd strony wraz z wprowadzanymi zmianami, więc nie musisz ponownie uruchamiać serwera, aby zobaczyć wprowadzone zmiany. Jeżeli serwer deweloperski jest uruchomiony, zawsze będziesz w stanie zobaczyć bieżącą wersję swojej strony w przeglądarce.

Przeglądając stronę, będziesz miał dostęp do deweloperskiego paska narzędzi Astro. Podczas budowania pomoże Ci on rewidować Twoje Wyspy, zauważać problemy z dostępnością oraz więcej.

Jeżeli po uruchomieniu serwera deweloperskiego nie jesteś w stanie otworzyć swojego projektu w przeglądarce, wróć do terminala, w którym uruchomiłeś komendę dev, i sprawdź wyświetloną wiadomość. Powinna poinformować Cię, dlaczego wystąpił błąd lub czy Twój projekt jest uruchomiony pod innym adresem URL niż http://localhost:4321/.

Skonfiguruj swoje środowisko dewelperskie

Dział zatytułowany Skonfiguruj swoje środowisko dewelperskie

Zapoznaj się z poniższymi przewodnikami, aby dostosować swoje środowisko deweloperskie.

Astro ma wbudowane wsparcie dla TypeScript, które może pomóc w zapobieganiu błędom w czasie wykonywania funkcji w środowisku uruchomieniowym poprzez definiowanie kształtów obiektów i komponentów w Twoim kodzie.

Nie musisz pisać kodu w TypeScript, żeby Twój projekt czerpał z niego korzyści. Astro zawsze potraktuje kod w Twoim komponencie jako TypeScript, a rozszerzenie Astro w VSCode wywnioskuje jak najwięcej, aby dostarczyć autouzupełnianie, wskazówki albo informacje o błędach w Twoim edytorze.

Przeczytaj więcej na temat wykorzystania i konfiguracji TypeScript w Astro

Aby sprawdzić wersję swojej strony, która zostanie stworzona podczas budowania finalnej wersji, wyjdź z serwera deweloperskiego (Ctrl + C) i uruchom odpowiednie polecenie menedżera paczek w swoim terminalu:

Okno terminala
npm run build

Astro zbuduje gotowy do wdrożenia na produkcję plik z zawartością Twojej strony w osobnym folderze (domyślnie dist/), a Ty możesz oglądać ten proces w terminalu. Poinformuje Cię o potencjalnych błędach, które pojawiły się podczas kompilacji. Jeżeli TypeScript jest skonfigurowany na ‘strict’ albo ‘strictest’, polecenie ‘build’ sprawdzi projekt pod względem błędów typowania.

Kiedy kompilacja się zakończy, uruchom odpowiednie polecenie preview (np. npm run preview) w terminalu, aby zobaczyć efekt końcowy kompilacji strony lokalnie w przeglądarce internetowej.

Zwróć uwagę, że ten podgląd pokazuje kod w takiej formie, w jakiej istniał w momencie ostatniej kompilacji na produkcję. Ma to na celu umożliwienie podglądu tego, jak Twoja strona będzie wyglądać po wdrożeniu na Internet. Wszelkie późniejsze zmiany w kodzie, dokonane po zbudowaniu, nie będą widoczne podczas podglądu strony, dopóki ponownie nie uruchomisz polecenia budującego.

Użyj kombinacji klawiszy (Ctrl + C), żeby wyjść z podglądu i uruchomić inne polecenie, takie jak restart serwera deweloperskiego, żeby wrócić do pracy w trybie deweloperskim, który na bieżąco aktualizuje podgląd strony w przeglądarce wraz ze zmianami w edytorze kodu.

Czytaj więcej na temat CLI Astro i poleceń, których będziesz używać podczas pracy z Astro.

Możesz rozważyć wdrożenie swojej aplikacji na produkcję od razu, zanim dodasz albo zmienisz zbyt dużo kodu. Jest to pomocne w opublikowaniu minimalnej, działającej wersji Twojej strony i może zaoszczędzić Ci trochę czasu oraz zapobiec problemom związanym z wdrożeniem produkcyjnym w późniejszym terminie.

Gratulacje! Teraz jesteś gotów, żeby rozpocząć budowanie z Astro! 🥳

Poniżej znajdziesz kilka tematów, z którymi polecamy się zapoznać. Możesz je czytać w dowolnej kolejności. Możesz też zostawić dokumentację na później i poeksperymentować trochę ze swoim nowym projektem Astro oraz wrócić do niej, kiedy pojawią się jakieś trudności bądź będziesz mieć pytania.

Zbuduj w pełni funkcjonalny blog w Astro, rozpoczynając od pojedynczej pustej strony, korzystając z poradnika wprowadzającego.

Jest to świetny sposób żeby sprawdzić jak działa Astro i zrozumieć podstawowe zasady funkcjonowania stron, układów, komponentów, routingu, Wysp i wielu innych. Poradnik zawiera również opcjonalną, przyjazną dla początkujących sekcję, która wyjaśnia podstawowe pojęcia związane z tworzeniem stron internetowych. Przeprowadza ona przez proces instalacji niezbędnych aplikacji na Twoim komputerze, tworzenia konta na GitHub oraz wdrożenia produkcyjnego Twojej strony na produkcję.

Ten poradnik przeprowadzi Cię krok po kroku przez ręczną instalację i konfigurację nowego projektu Astro.

Jeśli nie chcesz korzystać z automatycznej inicjalizacji poleceniem CLI create astro, możesz skonfigurować projekt samodzielnie, podążając za przedstawionym poniżej poradnikiem.

  1. Stwórz folder na projekt

    Stwórz pusty folder z nazwą Twojego projektu, a później do niego przejdź.

    Okno terminala
    mkdir my-astro-project
    cd my-astro-project

    Gdy znajdziesz się w nowym katalogu, stwórz plik package.json. W ten sposób będziesz zarządzać zależnościami swojego projektu, w tym również Astro. Jeżeli nie jesteś zaznajomiony z tym formatem pliku, uruchom następujące polecenie, aby go utworzyć.

    Okno terminala
    npm init --yes
  2. Zainstaluj Astro

    Najpierw zainstaluj zależności Astro w Twoim projekcie.

    Okno terminala
    npm install astro

    Teraz podmień zawartość swojego package.json na poniższą sekcję scripts:

    package.json
    "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
    },

    Użyjesz tych skryptów później w poradniku uruchamiania Astro i korzystania z różnych poleceń.

  3. Stwórz swoją pierwszą stronę

    W edytorze tekstowym stwórz nowy plik src/pages/index.astro. Będzie to Twoja pierwsza strona w projekcie Astro.

    W tym kroku skopiuj i wklej następujące fragmenty kodu (uwzględniając kreski ---) w nowo powstałym pliku:

    src/pages/index.astro
    ---
    // Witaj w Astro! Wszystko pomiędzy tymi potrójnymi kreskami
    // to Twój "frontmatter komponentu". Nigdy nie uruchamia się w przeglądarce.
    console.log('To uruchamia się w Twoim terminalu, a nie w przeglądarce!');
    ---
    <!-- Poniżej znajduje się Twój "szablon komponentu". To po prostu HTML, ale
    z dodatkiem magii, aby pomóc Ci tworzyć świetne szablony. -->
    <html>
    <body>
    <h1>Hello, World!</h1>
    </body>
    </html>
    <style>
    h1 {
    color: orange;
    }
    </style>
  4. Stwórz swój pierwszy zasób statyczny

    Stwórz również folder public/ w celu przechowywania plików statycznych. Astro zawsze będzie je uwzględniać przy kompilacji na produkcję, więc możesz swobodnie tworzyć odnośniki do nich wewnątrz szablonów komponentów.

    W edytorze tekstu stwórz nowy plik public/robots.txt. robots.txt to prosty plik, który większość stron uwzględnia, aby powiedzieć botom takim jak Google, jak obchodzić się z Twoją stroną.

    W tym kroku skopiuj i wklej następujące fragmenty kodu w nowo powstałym pliku:

    public/robots.txt
    # Przykład: Pozwól wszystkim botom na skanowanie i indeksowanie Twojej strony.
    # Pełna składnia: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /
  5. Stwórz astro.config.mjs

    Astro jest konfigurowane przy użyciu astro.config.mjs. Choć ten plik jest opcjonalny, jeśli nie potrzebujesz specjalnej konfiguracji Astro, warto go stworzyć od razu na przyszłość.

    Stwórz astro.config.mjs w ‘root’ projektu i skopiuj do niego kod poniżej:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    // https://astro.build/config
    export default defineConfig({});

    Jeżeli chcesz uwzględnić framework z komponentami UI, taki jak React, Svelte itp., albo używać w swoim projekcie narzędzi jak Tailwind lub Partytown, to w tym miejscu możesz je ręcznie zaimportować i skonfigurować.

    Zapoznaj się z dokumentacją konfiguracji API Astro w celu uzyskania większej ilości informacji.

  6. Dodaj wsparcie TypeScript

    TypeScript jest konfigurowany przy użyciu tsconfig.json. Nawet jeżeli nie piszesz kodu w Typescript, ten plik jest ważny dla narzędzi takich jak Astro i VS Code, żeby wiedziały, jak rozumieć Twój projekt. Niektóre funkcjonalności (np. importy paczek npm) nie są w pełni wspierane w edytorze bez pliku tsconfig.json.

    Jeżeli planujesz pisać kod w TypeScript, to użycie szablonu Astro strict lub strictest jest rekomendowane. Możesz przejrzeć i porównać trzy szablony konfiguracyjne w astro/tsconfigs/.

    Stwórz tsconfig.json w folderze ‘root’ swojego projektu i skopiuj do niego poniższy kod. (Możesz użyć base, strict, lub strictest dla swojego szablonu TypeScript):

    tsconfig.json
    {
    "extends": "astro/tsconfigs/base"
    }

    Na koniec, stwórz src/env.d.ts, aby poinformować TypeScript o dostępnych typach globalnych w projekcie Astro:

    src/env.d.ts
    /// <reference types="astro/client" />

    Przeczytaj poradnik instalacji TypeScript w Astro w celu uzyskania większej ilości informacji.

  7. Kolejne kroki

    Jeżeli przeszedłeś powyższe kroki, to struktura w Twoim projekcie powinna wyglądać w ten sposób.

    • Foldernode_modules/
    • Folderpublic/
      • robots.txt
    • Foldersrc/
      • Folderpages/
        • index.astro
      • env.d.ts
    • astro.config.mjs
    • package-lock.json bądź yarn.lock, pnpm-lock.yaml, itd.
    • package.json
    • tsconfig.json
  8. Możesz teraz uruchomić serwer deweloperski Astro i sprawdzić podgląd Twojego projektu na żywo podczas tworzenia aplikacji!

Pomóż nam

Jak chcesz ją przekazać?

Otwórz Issue na GitHubie

Najszybszy sposób na powiadomienie nas o problemie.

Społeczność
京ICP备15031610号-99