astro网站内容编写指南

本文档面向内容编写人员，介绍如何在本地运行 astro 项目并编写、修改网站内容。

一、前期准备：安装必要软件

在开始之前，需要在电脑上安装以下三个工具：

安装 Node.js（运行环境）

Node.js 是运行本项目所必需的环境。

访问 https://nodejs.org/zh-cn/download
下载 xx.x LTS 的版本(LTS是长期支持版本，稳定性更好)
按默认选项安装完成
安装完成后，在终端输入以下命令验证：
Terminal window
```
node --version
```
应显示 vxx.x.x。

同时验证 npm（Node.js 自带的包管理器）：
Terminal window
```
npm --version
```

安装 Git（版本管理工具）

Git 用于从远程服务器下载项目代码，以及将你的修改上传回去。

访问 https://git-scm.com/downloads
下载对应你操作系统（Windows / macOS）的安装包
按默认选项安装完成即可
安装完成后，打开终端（Windows 是「命令提示符」或「PowerShell」，macOS 是「终端」），输入以下命令验证安装成功：
Terminal window
```
git --version
```
如果看到类似 git version 2.x.x 的输出，说明安装成功。

安装完成后，配置你的身份信息（只需做一次）：

打开终端，依次运行以下两条命令（替换为你的真实姓名和邮箱）：
Terminal window
```
git config --global user.name "你的姓名"
git config --global user.email "你的邮箱@example.com"
```
这是 Git 记录每次提交者身份的必要配置，不配置则无法提交。

安装 VSCode（代码编辑器）

VSCode 是编辑文件的主要工具。

访问 https://code.visualstudio.com/
下载并安装
安装完成后打开 VSCode，推荐安装的 VSCode 插件：

打开 VSCode 后，点击左侧扩展图标（四个方块），搜索并安装以下插件：
- Modern MDX Preview - 在编辑 Markdown 文件时实时预览效果
- Astro - 为 Astro 页面提供语法提示

二、获取并运行项目

克隆项目到本地

打开终端，切换到你想存放项目的目录（例如桌面），然后运行：
Terminal window
```
git clone https://github.com/youchaoyun/deru-website.git
```
这会在当前目录下创建一个名为 deru-website 的文件夹，里面包含完整的项目代码。
安装项目依赖

进入VSCode，打开项目目录：File - Open Folder - 选择 deru-website 文件夹

打开TERMINAL（Ctrl/Cmd+Shift+Y）, 安装所有依赖（第一次运行，可能需要几分钟）：
Terminal window
```
npm i
```
启动本地开发服务器
Terminal window
```
npm run dev
```
启动成功后，终端会显示类似：
```
Local    http://localhost:4321/
```
在浏览器中打开 http://localhost:4321，即可看到网站效果。每次修改内容文件后，浏览器会自动刷新，如果没有变化，手动刷新浏览器（Ctrl+R / Cmd+R）。

停止服务器：在终端按 Ctrl + C

三、项目目录结构说明

文件夹deru-website
- 文件夹public 静态资源（图片等直接放这里）
  - images ← 所有图片文件放在这里
- 文件夹src
  - 文件夹content ← 网站内容（你主要在这里工作）
    文件夹en 英文内容
    homepage 首页
    about 页面1
    blog 页面2
    features 页面3
    how-it-works 页面4
    careers 页面5
    integrations 页面6
    pricing 页面7
    contact 联系我们
    pages 其他页面（页面8 页面9等）
    zh 中文内容（结构与 en/ 相同）
  - 文件夹config
    config.json ← 网站全局配置（网站名、联系方式等）
    menu.json ← 导航菜单（英文）
    menu.zh.json ← 导航菜单（中文）

你需要修改的文件几乎全部在 src/content/ 和 src/config/ 下，以及 public/images/ 中的图片。

四、中英双语内容说明

本网站同时支持中文和英文两个版本：

语言	访问地址	内容文件位置
英文	`https://你的域名.com/`	`src/content/en/`
中文	`https://你的域名.com/zh/`	`src/content/zh/`

重要规则：

两套内容相互独立，修改英文不会影响中文，反之亦然
如果需要同时更新两种语言，需要分别修改 en/ 和 zh/ 下对应的文件
中文内容文件位于 src/content/zh/，目录结构与英文完全相同
如果某个语言版本下没有对应文件（例如 zh/ 下没有某篇博客），该语言页面不会显示

示例： 修改首页中文内容

修改文件：src/content/zh/homepage/-index.md
对应页面：http://localhost:4321/zh/

五、如何编写网站内容

了解内容文件格式

所有内容文件都是 .md（Markdown）格式。文件由两部分组成：

---
这里是"前置数据"区域（YAML 格式）
用于设置标题、图片、按钮等结构化内容
---

这里是正文区域（Markdown 格式）
可以写段落、标题、列表等

前置数据区域（--- 之间）的规则：

每行是 键: 值 的格式
注意缩进

Markdown 正文常用语法：

markdown语法参照

关于图标字段（icon）：

部分内容文件中有 icon: FiXxx 这样的字段，例如：

- icon: "FiLock"
  title: 卡片标题

这些图标来自 React Icons - Feather 系列，以 Fi 开头。你可以在上述页面浏览所有可用图标，点击图标即可复制其名称（如 FiStar、FiMail、FiGlobe 等）。直接将名称替换到 icon: 字段即可。

修改首页内容

文件：src/content/en/homepage/-index.md（英文）或 src/content/zh/homepage/-index.md（中文）

修改网站基本信息

{
  "site": {
    "title": "网站名称",
    "base_url": "https://你的域名.com"
  },
  "params": {
    "email": "联系邮箱@example.com",
    "phone": "联系电话"
  },
  "metadata": {
    "meta_author": "作者/机构名",
    "meta_description": "网站描述，显示在搜索引擎结果中"
  }
}

修改导航菜单

英文导航：src/config/menu.json 中文导航：src/config/menu.zh.json

{
  "main": [
    { "name": "首页", "url": "/" },
    { "name": "关于我们", "url": "/about" },
    { "name": "博客", "url": "/blog" },
    {
      "name": "更多",
      "url": "",
      "hasChildren": true,
      "children": [
        { "name": "定价", "url": "/pricing" },
        { "name": "联系我们", "url": "/contact" }
      ]
    }
  ]
}

替换和添加图片

将图片文件（.jpg、.png、.webp 等）放入 public/images/ 目录下（可创建子文件夹分类）
在内容文件中引用时，路径从 /images/ 开始写，例如：

image: "/images/about/team-photo.jpg"

图片命名建议：

使用英文或数字命名，避免中文和空格
示例：team-photo-2025.jpg、banner-hero.png

六、提交并同步你的修改

修改内容后，需要通过 Git 将改动提交并推送到远程仓库。

在 VSCode 中使用图形界面提交（推荐新手）

打开 VSCode，点击左侧源代码管理图标（分叉图标）
可以看到所有改动的文件列表
在上方输入框填写提交说明（例如：更新首页文字）
点击 提交（Commit） 按钮
点击 同步更改（Sync Changes） 将改动推送到远程仓库

推荐：每次开始工作前，先将远程最新代码同步到本地，避免冲突： git pull

使用命令行提交

# 查看改动了哪些文件
git status

# 将所有改动加入暂存
git add .

# 提交，填写描述本次改动的说明
git commit -m "更新首页内容和博客文章"

# 推送到远程仓库
git push

七、发布网站

提交代码后，无需操作，自动发布