| title | description | i18nReady |
|---|---|---|
安装并设置 Astro |
如何安装 Astro 并开始一个新项目。 |
true |
import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components'; import ReadMore from '~/components/ReadMore.astro';
create astro CLI 命令 是从零开始创建一个新的 Astro 项目的最快方式。它将引导你完成设置新 Astro 项目的每一个步骤，并允许你从几个不同的官方起始模板中选择。
或者，你可以使用任何现有的主题或起始模板开始你的项目。
如果想要手动安装 Astro，请查看我们的逐步手动安装指南。
:::tip[在线预览] 想在浏览器中尝试 Astro 吗？访问 astro.new 浏览我们的起始模板，并在不离开浏览器的情况下启动一个新的 Astro 项目。 :::
- Node.js -
v18.17.1或v20.3.0或更高版本。（不支持v19。） - 文本编辑器 - 我们推荐使用 VS Code 并安装我们的 官方 Astro 扩展。
- 终端 - Astro 通过其命令行界面（CLI）访问。
<Tabs>
<TabItem label="npm">
```shell
# 使用 npm 创建一个新项目
npm create astro@latest
```
</TabItem>
<TabItem label="pnpm">
```shell
# 使用 pnpm 创建一个新项目
pnpm create astro@latest
```
</TabItem>
<TabItem label="yarn">
```shell
# 使用 yarn 创建一个新项目
yarn create astro
```
</TabItem>
</Tabs>
你可以在你的机器上的任何地方运行 `create astro`，因此在开始之前无需创建一个新的空目录。如果你还没有为你的新项目准备一个空目录，向导将会自动为你创建一个。
如果一切顺利，你将看到一个成功信息，随后是一些推荐的后续步骤。现在你的项目已经创建好了，你可以 `cd` 进入你的新项目目录开始使用 Astro。
-
如果你在 CLI 向导中跳过了
npm install步骤，那么在继续之前请确保安装你的依赖。 -
现在你可以 启动 Astro 开发服务器 并在构建时看到你的项目的实时预览！
你也可以通过向 create astro 命令传递 --template 参数，基于 官方示例 或任何 GitHub 仓库的 main 分支开始一个新的 Astro 项目。
-
在你的终端运行以下命令，替换官方 Astro 起始模板的名称，或你想使用的 GitHub 用户名和仓库：
```shell # 使用官方示例创建一个新项目 npm create astro@latest -- --templatenpm create astro@latest -- --template /
```shell # 使用官方示例创建一个新项目 yarn create astro --template</TabItem> <TabItem label="pnpm"> ```shell # 使用官方示例创建一个新项目 pnpm create astro@latest --template <example-name> # 基于 GitHub 仓库的 main 分支创建一个新项目 pnpm create astro@latest --template <github-username>/<github-repo>yarn create astro --template /
</TabItem> </Tabs> 默认情况下，此命令将使用模板仓库的 `main` 分支。如果要使用不同的分支名称，请在 `--template` 参数中指定：`<github-username>/<github-repo>#<branch>`。 -
回答 CLI 向导的问题并遵循其指示。
-
现在你可以 启动 Astro 开发服务器 并在自定义项目的同时查看实时预览！
本指南将指导你手动安装和配置新的 Astro 项目。
如果你不想使用我们的自动 create astro CLI 工具，可以按照下面的指南自行设置你的项目。
创建一个以你的项目命名的空目录，然后进入该目录。
```bash
mkdir my-astro-project
cd my-astro-project
```
进入你的新目录后，创建你的项目 `package.json` 文件。这是你管理项目依赖项（包括 Astro）的方式。如果你不熟悉这种文件格式，请运行以下命令创建一个。
<Tabs>
<TabItem label="npm">
```shell
npm init --yes
```
</TabItem>
<TabItem label="pnpm">
```shell
pnpm init
```
</TabItem>
<TabItem label="yarn">
```shell
yarn init --yes
```
</TabItem>
</Tabs>
-
安装 Astro
首先，在你的项目中安装 Astro 的依赖项。
:::note[重要] Astro 必须安装在本地，不能全局安装。确保你没有运行
```shell npm install astro ``` ```shell pnpm add astro ``` ```shell yarn add astro ```npm install -g astro、pnpm add -g astro或yarn add global astro。 :::然后，用以下内容替换你的
package.json中的任何占位符 "scripts" 部分："scripts": { "test": "echo \"Error: no test specified\" && exit 1", "dev": "astro dev", "start": "astro dev", "build": "astro build", "preview": "astro preview" },
你将在本指南后面使用这些脚本来启动 Astro 并运行其不同的命令。
-
创建你的第一个页面
在你的文本编辑器中，在你的目录下的
src/pages/index.astro创建一个新文件。这将是你项目中的第一个 Astro 页面。对于本指南，请将以下代码片段（包括
---破折号）复制并粘贴到你的新文件中：--- // 欢迎使用 Astro！这些三破折号代码围栏之间的内容是你的 "component frontmatter"。它不会在浏览器中运行。 console.log('这段代码在你的终端运行，而不是在浏览器中！'); --- <!-- 下面是你的 "component template"。它只是 HTML，但加入了一些魔法，帮助你构建出色的模板。 --> <html> <body> <h1>Hello, World!</h1> </body> </html> <style> h1 { color: orange; } </style>
-
创建你的第一个静态资源
你还需要创建一个
public/目录来存储你的静态资源。Astro 将始终在你的最终构建中包含这些资源，因此你可以安全地从你的组件模板中引用它们。在你的文本编辑器中，在你的目录下的
public/robots.txt创建一个新文件。robots.txt是大多数网站会包含的一个简单文件，用于告诉像 Google 这样的搜索机器人如何处理你的网站。对于本指南，请将以下代码片段复制并粘贴到你的新文件中：
# 示例：允许所有机器人扫描并索引你的网站。 # 完整语法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt User-agent: * Allow: /
-
创建
astro.config.mjsAstro 使用
astro.config.mjs进行配置。如果你不需要配置 Astro，这个文件是可选的，但你现在可能希望创建它。在你项目的根目录下创建
astro.config.mjs，并将下面的代码复制到其中：import { defineConfig } from 'astro/config'; // https://astro.build/config export default defineConfig({});
如果你想在你的项目中包含 UI 框架组件，如 React、Svelte 等，或使用其他工具，如 Tailwind 或 Partytown，这里是你手动导入和配置集成的地方。
阅读 Astro 的 API 配置参考 以获取更多信息。
-
添加 TypeScript 支持
TypeScript 使用
tsconfig.json进行配置。即使你不编写 TypeScript 代码，这个文件也很重要，以便工具（如 Astro 和 VS Code）了解你的项目。某些功能（如 npm 包导入）在没有tsconfig.json文件的情况下在编辑器中不完全支持。如果你打算编写 TypeScript 代码，建议使用 Astro 的
strict或strictest模板。你可以在 astro/tsconfigs/ 查看并比较三种模板配置。在你项目的根目录下创建
tsconfig.json，并将下面的代码复制到其中。（你可以使用base、strict或strictest作为你的 TypeScript 模板）：{ "extends": "astro/tsconfigs/base" }最后，创建
src/env.d.ts，让 TypeScript 知道 Astro 项目中可用的环境类型：/// <reference types="astro/client" />阅读 Astro 的 TypeScript 设置指南 以获取更多信息。
-
接下来
如果你已经按照上面的步骤操作，你的项目目录现在应该如下所示：
- node_modules/ - public/ - robots.txt - src/ - pages/ - index.astro - env.d.ts - astro.config.mjs - package-lock.json 或 `yarn.lock`、`pnpm-lock.yaml` 等。 - package.json - tsconfig.json -
现在你可以启动 Astro 开发服务器 并在构建项目的同时查看实时预览了！
Astro 自带了一个内置的开发服务器，它包含了项目开发所需的一切。astro dev CLI 命令将启动本地开发服务器，让你第一次看到你的新网站。
每个起始模板都预配置了一个脚本，该脚本将为你运行 astro dev。在进入你的项目目录后，使用你喜欢的包管理器运行此命令并启动 Astro 开发服务器。
如果一切顺利，Astro 将在 http://localhost:4321/ 上为你的项目提供服务。在浏览器中访问该链接，查看你的新网站！
Astro 将监听你的 src/ 目录中的实时文件更改，并在你构建时更新你的网站预览，因此在开发过程中你无需重启服务器。当开发服务器运行时，你总能在浏览器中看到你网站的最新版本。
在浏览器中查看你的网站时，你将能够访问 Astro 开发工具栏。在你构建时，它将帮助你检查你的 群岛，发现无障碍问题等。
如果在启动开发服务器后无法在浏览器中打开你的项目，请返回运行 dev 命令的终端并检查显示的消息。它应该会告诉你是否发生了错误，或者你的项目是否在不同的 URL http://localhost:4321/ 上提供服务。
若要检查将在构建时创建的网站版本，请退出开发服务器（Ctrl + C）并在你的终端中运行适用于你的包管理器的相应构建命令：
```shell npm run build ``` ```shell pnpm build ``` ```shell yarn run build ```Astro 将在一个单独的文件夹（默认为 dist/）中构建你的网站的可部署版本，并且你可以在终端中看到其进度。这将在你部署到生产环境之前提醒你项目中的任何构建错误。如果 TypeScript 配置为 strict 或 strictest，build 脚本还将检查你的项目中的类型错误。
当构建完成后，在你的终端中运行适当的 preview 命令（例如 npm run preview），你就可以在同一个浏览器预览窗口中本地查看你的网站的构建版本。
请注意，这将预览你在最后一次运行构建命令时的代码状态。这旨在让你预览你的网站在 部署到网络 时的样子。在构建后对代码进行的任何更改都不会在你预览网站时反映出来，直到你再次运行构建命令。
使用（Ctrl + C）退出预览并在终端中运行另一个命令，例如重新启动开发服务器以返回 开发模式工作，它会随着你的编辑更新以显示你的代码更改的实时预览。
阅读更多关于 Astro CLI 和你在使用 Astro 构建时将使用的终端命令。
你可能希望 立即部署你的新网站，在你开始添加或更改太多代码之前。这有助于发布你的网站的最小工作版本，并可以节省你以后排查部署问题的时间和精力。
好了！你现在可以开始使用 Astro 构建了！🥳
以下是我们建议接下来探索的几个主题，你可以按任何顺序阅读它们。你甚至可以暂时离开我们的文档去玩转你的新 Astro 项目代码库，当你遇到麻烦或有疑问时，欢迎你随时返回这里。