手动安装 Astro

本指南将引导你如何手动安装和配置一个新的 Astro 项目。

前提准备

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

安装

如果你不打算使用 create astro 命令工具来自动化创建项目，你可以根据以下说明来自行设置你的项目。

1. 创建项目目录

创建一个空目录，目录名称是你打算使用的项目名称，并导航到该目录。

mkdir my-astro-project
cd my-astro-project

在该目录内，创建 package.json 文件，该文件将管理你的项目依赖，包括 Astro，如果你不熟悉这种文件格式，可以运行下面的命令来直接创建一个。

npm init --yes

pnpm init

yarn init --yes

2. 安装 Astro

首先，需要在你的项目目录内安装 Astro 的项目依赖。

npm install astro

pnpm add astro

yarn add 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 项目。

3. 创建第一个页面

打开你的编辑器，在 src/pages/ 目录下创建一个新文件 index.astro，这将会是你的第一个页面。

复制并粘贴以下内容到该页面 index.astro 内（包含 --- 内的内容）。

---
// 欢迎来到 Astro！这些三横线所围住的代码
// 就是你的“组件 frontmatter”。它不会运行在浏览器中。
console.log('它运行在终端而非浏览器！');
---
<!-- 下面是你的“组件模板”。 这仅仅是 HTML，但是
     带有魔法点缀可以帮助构建更棒的模板。 -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

4. 创建静态文件

同样，你可以创建一个 public/ 目录来存储你的静态文件。Astro 会在最后的编译中包含进这些文件，以便你可以在你的组件模板内安全地引用他们。

用编辑器在 public/ 目录下创建一个 robots.txt 的文件，该文件将会告诉类似 Google 这样的搜索引擎怎样去对待该站点。

针对该教程，复制并粘贴以下内容至 robots.txt 内：

# 示例：运行所有爬虫抓取并索引你的站点。
# 全部语法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /

5. 创建 `astro.config.mjs` 配置文件

Astro 使用 astro.config.mjs 来配置项目。这个文件是可选的，你可以选择不配置它，但还是希望你现在创建该文件。

在你的项目根目录创建 astro.config.mjs 文件，并复制粘贴下面的内容至该文件内：

import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});

如果你想集成像 React、Svelte 这样的UI 框架组件或是使用其他类似 Tailwind 或 Partytown 这样的工具，你可以在手动导入并配置集成章节内获取更多信息。

阅读 Astro 的 API 配置参考章节来获得更多内容。

6. 添加 TypeScript 支持

TypeScript 使用tsconfig.json进行配置。即使你不编写 TypeScript 代码，这个文件也很重要，因为 Astro 和 VS Code 等工具知道如何理解你的项目。如果没有 tsconfig.json 文件，编辑器将不完全支持某些功能（如 npm 包导入）。

如果你打算编写 TypeScript 代码，建议使用 Astro 的strict或strictest的模板。你可以在 astro/tsconfigs/ 查看和比较三个模板配置。

在项目的根目录创建 tsconfig.json，并将下面的代码复制到其中。（你可以为 TypeScript 模板使用 base、strict 或 strictest）：

{
  "extends": "astro/tsconfigs/base"
}

最后，创建src/env.d.ts让 TypeScript 知道 Astro 项目中可用的环境类型：

/// <reference types="astro/client" />

阅读 Astro 的 TypeScript 设置指南来获取更多信息。

7. 接下来

如果你按上述一步步操作，你的项目目录应该看上去像是这样：

文件夹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 了！

如果你完成了这个指南的全部内容，你可以跳转至步骤 2：启动 Astro继续并学习如何首次运行 Astro。

编辑此页 Translate

Contribute

Community

手动安装 Astro

前提准备

安装

1. 创建项目目录

2. 安装 Astro

3. 创建第一个页面

4. 创建静态文件

5. 创建 `astro.config.mjs` 配置文件

6. 添加 TypeScript 支持

7. 接下来

你有什么想法？

创建 GitHub Issue

发送反馈

发送反馈

手动安装 Astro

前提准备

安装

1. 创建项目目录

2. 安装 Astro

3. 创建第一个页面

4. 创建静态文件

5. 创建 astro.config.mjs 配置文件

6. 添加 TypeScript 支持

7. 接下来

5. 创建 `astro.config.mjs` 配置文件