安装并设置 Astro

create astro CLI 命令是从头开始启动新 Astro 项目的最快方法。它将引导你完成设置新 Astro 项目的每个步骤，并允许你从几个不同的官方入门模板中进行选择。

¥The create astro CLI command is the fastest way to start a new Astro project from scratch. It will walk you through every step of setting up your new Astro project and allow you to choose from a few different official starter templates.

或者，你可以开始你的项目使用任何现有主题或入门模板。

¥Or, you can begin your project using any existing theme or starter template.

要手动安装 Astro，请参阅我们的分步手动安装指南。

¥To install Astro manually instead, see our step-by-step manual installation guide.

先决条件

¥Prerequisites

Node.js - v18.17.1 或 v20.3.0 或更高版本。（不支持 v19。）
文本编辑器 - 我们建议将 VS Code 与我们的官方 Astro 扩展一起使用。
终端 - Astro 可通过其命令行接口 (CLI) 访问。

浏览器兼容性

¥Browser compatibility

Astro 是使用 Vite 构建的，默认情况下针对具有现代 JavaScript 支持的浏览器。有关完整参考，请参阅 Vite 中当前支持的浏览器版本列表。

¥Astro is built with Vite which targets browsers with modern JavaScript support by default. For a complete reference, you can see the list of currently supported browser versions in Vite.

启动新项目

¥Start a new project

从 CLI 向导安装

¥Install from the CLI wizard

Run the following command in your terminal to start our handy install wizard:
- npm
- pnpm
- yarn
Terminal window
# create a new project with npm npm create astro@latest
Terminal window
# create a new project with pnpm pnpm create astro@latest
Terminal window
# create a new project with yarn yarn create astro
You can run create astro anywhere on your machine, so there’s no need to create a new empty directory for your project before you begin. If you don’t have an empty directory yet for your new project, the wizard will help create one for you automatically.

If all goes well, you will see a success message followed by some recommended next steps. Now that your project has been created, you can cd into your new project directory to begin using Astro.
If you skipped the “Install dependencies?” step during the CLI wizard, then be sure to install your dependencies before continuing.
You can now start the Astro dev server and see a live preview of your project while you build!

使用主题或入门模板

¥Use a theme or starter template

你还可以通过将 --template 参数传递给 create astro 命令，基于任何 GitHub 存储库的官方示例或 main 分支启动新的 astro 项目。

¥You can also start a new astro project based on an official example or the main branch of any GitHub repository by passing a --template argument to the create astro command.

Explore our themes and starters showcase where you can browse themes for blogs, portfolios, documentation sites, landing pages, and more! Or, search on GitHub for even more starter projects.

Run the following command in your terminal, substituting the official Astro starter template name, or the GitHub username and repository of the theme you want to use:

# create a new project with an official example
npm create astro@latest -- --template <example-name>

# create a new project based on a GitHub repository’s main branch
npm create astro@latest -- --template <github-username>/<github-repo>

# create a new project with an official example
pnpm create astro@latest --template <example-name>

# create a new project based on a GitHub repository’s main branch
pnpm create astro@latest --template <github-username>/<github-repo>

# create a new project with an official example
yarn create astro --template <example-name>

# create a new project based on a GitHub repository’s main branch
yarn create astro --template <github-username>/<github-repo>

By default, this command will use the template repository’s main branch. To use a different branch name, pass it as part of the --template argument: <github-username>/<github-repo>#<branch>.

Answer the questions and follow the instructions of the CLI wizard.
You can now start the Astro dev server and see a live preview of your project while you make it your own!

编辑你的项目

¥Edit your project

要更改你的项目，请在代码编辑器中打开你的项目文件夹。在开发模式下运行开发服务器，你可以在编辑代码时查看网站的更新。

¥To make changes to your project, open your project folder in your code editor. Working in development mode with the dev server running allows you to see updates to your site as you edit the code.

你还可以配置 TypeScript 或安装官方 Astro 编辑器扩展等自定义开发环境的各个方面。

¥You can also customize aspects of your development environment such as configuring TypeScript or installing the official Astro editor extensions.

启动 Astro 开发服务器

¥Start the Astro dev server

Astro 配备了内置开发服务器，其中包含项目开发所需的一切。astro dev CLI 命令将启动本地开发服务器，以便你可以第一次看到新网站的运行情况。

¥Astro comes with a built-in development server that has everything you need for project development. The astro dev CLI command will start the local development server so that you can see your new website in action for the very first time.

每个入门模板都附带一个预配置的脚本，将为你运行 astro dev。导航到你的项目目录后，使用你最喜欢的包管理器运行此命令并启动 Astro 开发服务器。

¥Every starter template comes with a pre-configured script that will run astro dev for you. After navigating into your project directory, use your favorite package manager to run this command and start the Astro development server.

npm run dev

pnpm run dev

yarn run dev

如果一切顺利，Astro 现在将在 http://localhost:4321/ 上为你的项目提供服务。访问浏览器中的该链接并查看你的新网站！

¥If all goes well, Astro will now be serving your project on http://localhost:4321/. Visit that link in your browser and see your new site!

在开发模式下工作

¥Work in development mode

Astro 将监听 src/ 目录中的实时文件更改，并在构建时更新站点预览，因此你在开发过程中进行更改时无需重新启动服务器。当开发服务器运行时，你将始终能够在浏览器中看到你网站的最新版本。

¥Astro will listen for live file changes in your src/ directory and update your site preview as you build, so you will not need to restart the server as you make changes during development. You will always be able to see an up-to-date version of your site in your browser when the dev server is running.

在浏览器中查看你的网站时，你将可以访问 Astro 开发工具栏。在你构建时，它将帮助你检查 islands、发现可访问性问题等。

¥When viewing your site in the browser, you’ll have access to the Astro dev toolbar. As you build, it will help you inspect your islands, spot accessibility issues, and more.

如果启动开发服务器后无法在浏览器中打开项目，请返回运行 dev 命令的终端并检查显示的消息。它应该告诉你是否发生了错误，或者你的项目是否在与 http://localhost:4321/ 不同的 URL 上提供服务。

¥If you aren’t able to open your project in the browser after starting the dev server, go back to the terminal where you ran the dev command and check the message displayed. It should tell you if an error occurred, or if your project is being served at a different URL than http://localhost:4321/.

配置你的开发环境

¥Configure your dev environment

浏览以下指南以定制你的开发体验。

¥Explore the guides below to customize your development experience.

Editor Setup Customize your code editor to improve the Astro developer experience and unlock new features.

Dev Toolbar Explore the helpful features of the dev toolbar.

Astro 中的 TypeScript

¥TypeScript in Astro

Astro 附带对 TypeScript 的内置支持，可以通过定义代码中对象和组件的形状来帮助防止运行时出现错误。

¥Astro ships with built-in support for TypeScript, which can help prevent errors at runtime by defining the shapes of objects and components in your code.

你无需在 Astro 项目中编写 TypeScript 代码即可从中受益。Astro 始终将你的组件代码视为 TypeScript，并且 Astro VSCode 扩展将尽可能地进行推断，以在编辑器中提供自动补齐、提示和错误。

¥You don’t need to write TypeScript code in your Astro projects to benefit from it. Astro always treats your component code as TypeScript, and the Astro VSCode Extension will infer as much as it can to provide autocompletion, hints, and errors in your editor.

Read more about using and configuring TypeScript in Astro

构建和预览你的网站

¥Build and preview your site

要检查将在构建时创建的站点版本，请退出开发服务器 (Ctrl + C) 并在终端中为你的包管理器运行适当的构建命令：

¥To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command for your package manager in your terminal:

npm run build

pnpm build

yarn run build

Astro 将在单独的文件夹（默认为 dist/）中构建可部署的站点版本，你可以在终端中查看其进度。这将在你部署到生产之前提醒你项目中的任何构建错误。如果 TypeScript 配置为 strict 或 strictest，build 脚本还将检查你的项目是否存在类型错误。

¥Astro will build a deploy-ready version of your site in a separate folder (dist/ by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production. If TypeScript is configured to strict or strictest, the build script will also check your project for type errors.

构建完成后，在你的终端中运行适当的 preview 命令（例如 npm run preview），然后你可以在同一浏览器预览窗口中本地查看你网站的构建版本。

¥When the build is finished, run the appropriate preview command (e.g. npm run preview) in your terminal and you can view the built version of your site locally in the same browser preview window.

请注意，这将预览上次运行构建命令时的代码。这旨在让你预览你的网站在部署到网络时的外观。在构建后对代码所做的任何更改都不会在你预览网站时反映出来，直到你再次运行构建命令。

¥Note that this previews your code as it existed when the build command was last run. This is meant to give you a preview of how your site will look when it is deployed to the web. Any later changes you make to your code after building will not be reflected while you preview your site until you run the build command again.

使用（Ctrl + C）退出预览并运行另一个终端命令，例如重新启动开发服务器以返回到在开发模式下工作，它会在你编辑时更新以显示代码更改的实时预览。

¥Use (Ctrl + C) to quit the preview and run another terminal command, such as restarting the dev server to go back to working in development mode which does update as you edit to show a live preview of your code changes.

Read more about the Astro CLI and the terminal commands you will use as you build with Astro.

部署你的新站点

¥Deploy your new site

在开始添加或更改太多代码之前，你可能希望立即部署新站点。这有助于发布你网站的最小工作版本，并可以为你节省以后排除部署故障的额外时间和精力。

¥You may wish to deploy your new site right away, before you begin to add or change too much code. This is helpful to get a minimal, working version of your site published and can save you extra time and effort troubleshooting your deployment later.

下一步

¥Next Steps

成功！现在你已准备好开始使用 Astro 进行构建！🥳

¥Success! You are now ready to start building with Astro! 🥳

以下是我们建议接下来探索的一些内容。你可以按任何顺序阅读它们。你甚至可以暂时离开我们的文档，然后去玩新的 Astro 项目代码库，每当你遇到麻烦或有疑问时就回到这里。

¥Here are a few things that we recommend exploring next. You can read them in any order. You can even leave our documentation for a bit and go play in your new Astro project codebase, coming back here whenever you run into trouble or have a question.

探索 Astro 的功能

¥Explore Astro’s Features

Understand your codebase Learn about Astro’s file structure in our Project Structure guide.

Create content collections Add content to your new site with frontmatter validation and automatic type-safety.

Add view transitions Create seamless page transitions and animations.

Learn about Islands Read about Astro's island architecture.

参加入门教程

¥Take the introductory tutorial

从我们的入门教程中的一个空白页开始构建一个功能齐全的 Astro 博客。

¥Build a fully functional Astro blog starting from a single blank page in our introductory tutorial.

这是了解 Astro 工作原理的好方法，并引导你了解页面、布局、组件、路由、群岛等的基础知识。它还包括一个可选的、适合初学者的单元，适合那些对一般 Web 开发概念较新的人，它将指导你在计算机上安装必要的应用、创建 GitHub 账户以及部署你的网站。

¥This is a great way to see how Astro works and walks you through the basics of pages, layouts, components, routing, islands, and more. It also includes an optional, beginner-friendly unit for those newer to web development concepts in general, which will guide you through installing the necessary applications on your computer, creating a GitHub account, and deploying your site.

手动设置

¥Manual Setup

本指南将引导你完成手动安装和配置新 Astro 项目的步骤。

¥This guide will walk you through the steps to manually install and configure a new Astro project.

如果你不想使用我们的自动 create astro CLI 工具，你可以按照以下指南自行设置你的项目。

¥If you prefer not to use our automatic create astro CLI tool, you can set up your project yourself by following the guide below.

Create your directory

Create an empty directory with the name of your project, and then navigate into it.
Terminal window
```
mkdir my-astro-project
cd my-astro-project
```
Once you are in your new directory, create your project package.json file. This is how you will manage your project dependencies, including Astro. If you aren’t familiar with this file format, run the following command to create one.
- npm
- pnpm
- yarn
Terminal window
npm init --yes
Terminal window
pnpm init
Terminal window
yarn init --yes
Install Astro

First, install the Astro project dependencies inside your project.

Astro must be installed locally, not globally. Make sure you are not running npm install -g astro pnpm add -g astro or yarn add global astro.
- npm
- pnpm
- yarn
Terminal window
npm install astro
Terminal window
pnpm add astro
Terminal window
yarn add astro
Then, replace any placeholder “scripts” section of your package.json with the following:
package.json
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```
You’ll use these scripts later in the guide to start Astro and run its different commands.

Create your first page

In your text editor, create a new file in your directory at src/pages/index.astro. This will be your first Astro page in the project.

For this guide, copy and paste the following code snippet (including --- dashes) into your new file:

---
// Welcome to Astro! Everything between these triple-dash code fences
// is your "component frontmatter". It never runs in the browser.
console.log('This runs in your terminal, not the browser!');
---
<!-- Below is your "component template." It's just HTML, but with
    some magic sprinkled in to help you build great templates. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

Create your first static asset

You will also want to create a public/ directory to store your static assets. Astro will always include these assets in your final build, so you can safely reference them from inside your component templates.

In your text editor, create a new file in your directory at public/robots.txt. robots.txt is a simple file that most sites will include to tell search bots like Google how to treat your site.

For this guide, copy and paste the following code snippet into your new file:
public/robots.txt
```
# Example: Allow all bots to scan and index your site.
# Full syntax: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
Create astro.config.mjs

Astro is configured using astro.config.mjs. This file is optional if you do not need to configure Astro, but you may wish to create it now.

Create astro.config.mjs at the root of your project, and copy the code below into it:
astro.config.mjs
```
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```
If you want to include UI framework components such as React, Svelte, etc. or use other tools such as Tailwind or Partytown in your project, here is where you will manually import and configure integrations.

Read Astro’s API configuration reference for more information.
Add TypeScript support

TypeScript is configured using tsconfig.json. Even if you don’t write TypeScript code, this file is important so that tools like Astro and VS Code know how to understand your project. Some features (like npm package imports) aren’t fully supported in the editor without a tsconfig.json file.

If you do intend to write TypeScript code, using Astro’s strict or strictest template is recommended. You can view and compare the three template configurations at astro/tsconfigs/.

Create tsconfig.json at the root of your project, and copy the code below into it. (You can use base, strict, or strictest for your TypeScript template):
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
Read Astro’s TypeScript setup guide for more information.
Next Steps

If you have followed the steps above, your project directory should now look like this:
- Directorynode_modules/
  - …
- Directorypublic/
  - robots.txt
- Directorysrc/
  - Directorypages/
    index.astro
- astro.config.mjs
- package-lock.json or yarn.lock, pnpm-lock.yaml, etc.
- package.json
- tsconfig.json
You can now start the Astro dev server and see a live preview of your project while you build!