本地部署与修改指南

《澳洲留学全通关指南》基于 VitePress 构建。按照本页步骤，你可以在自己的电脑上运行完整站点、修改内容，并在提交更改前检查最终页面。

安装运行环境

项目需要以下工具：

• Git，用于下载和管理项目代码；
• Node.js 22 或更高版本，用于运行 VitePress。Node.js 的官方安装包会同时安装 npm。

请根据操作系统选择一组安装命令。

macOS

如果已经安装 Homebrew，运行：

brew install git node

如果系统中还没有 Homebrew，先运行其官方安装命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，请按照终端提示将 Homebrew 加入 PATH，再运行上面的 brew install 命令。

Windows

在 PowerShell 中使用 WinGet 安装 Git 和 Node.js LTS：

winget install --id Git.Git --exact
winget install --id OpenJS.NodeJS.LTS --exact

命令执行完成后，关闭并重新打开 PowerShell，使新的环境变量生效。如果系统无法识别 winget，请先根据 Microsoft 文档安装或更新“应用安装程序”。

Ubuntu 或 Debian

先安装 Git 和 cURL：

sudo apt update
sudo apt install -y git curl

再通过 nvm 安装 Node.js 22：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

关闭并重新打开终端，然后运行：

nvm install 22
nvm alias default 22
nvm use 22

使用其他 Linux 发行版时，可参考 Git 安装说明 和 Node.js 下载页面。

确认安装结果

打开新的终端窗口，运行：

git --version
node --version
npm --version

三条命令均能输出版本号即表示环境已就绪。下文命令在 PowerShell、macOS 终端和常见 Linux 终端中均可直接运行。

下载项目并安装依赖

在终端中依次运行：

git clone https://github.com/chenzhi-liu/australia-study-guide.git
cd australia-study-guide
npm install

git clone 会下载项目源码，cd 会进入项目目录，npm install 则会安装 VitePress 及其依赖。首次安装所需时间取决于网络环境。

如果准备向项目提交贡献，请先在 GitHub 上 Fork 本仓库，再将上述 git clone 地址换成你自己的 Fork 地址。只需在本地阅读或预览时，可以直接使用上面的命令。

启动本地站点

运行开发服务器：

npm run docs:dev

终端出现本地访问地址后，在浏览器中打开该地址即可阅读指南。默认地址通常为 http://localhost:5173。

开发服务器运行期间，修改并保存文档后，浏览器中的页面会自动更新。结束运行时，在终端中按 Ctrl+C。

修改指南内容

项目的主要文件位于以下位置：

• docs/index.md：首页与使用说明；
• docs/ch1.md 至 docs/ch5.md：指南各章节；
• docs/.vitepress/config.mts：站点标题、导航栏和侧边栏配置。

正文使用 Markdown 编写。新增页面时，请在 docs 目录中创建 .md 文件；如果希望页面出现在侧边栏中，还需要在 docs/.vitepress/config.mts 中添加对应链接。

构建并检查最终版本

完成修改后，先生成用于发布的静态文件：

npm run docs:build

构建成功后，生成的文件位于 docs/.vitepress/dist。你可以继续运行以下命令，在本地检查构建结果：

npm run docs:preview

预览地址通常为 http://localhost:4173。检查完成后，同样可以按 Ctrl+C 结束运行。

提交更改前

建议至少运行一次 npm run docs:build。开发服务器能够正常显示页面，并不一定代表生产构建也能通过；构建命令可以帮助发现失效链接、配置错误和部分 Markdown 语法问题。

提交 Pull Request

提交前，请先阅读内容贡献指南。在自己的 Fork 中创建新分支，完成修改并通过构建后，提交并推送分支：

git switch -c docs/update-topic
git status
git add docs/ch1.md
git commit -m "docs: update guide content"
git push -u origin docs/update-topic

请将分支名、文件路径和提交说明换成与实际修改对应的内容。推送完成后，回到 GitHub 上的原项目页面，点击 Compare & pull request，说明修改内容、引用来源和 AI 使用情况后提交。

更详细的操作请参考 GitHub 官方的 Fork 仓库教程 和从 Fork 创建 Pull Request。

常见问题

端口已被占用

如果默认端口正在使用，可以指定其他端口：

npm run docs:dev -- --port 5174

局域网内的其他设备无法访问

开发服务器默认只供本机访问。如需使用同一局域网内的手机或平板预览，可以运行：

npm run docs:dev -- --host 0.0.0.0

终端会显示局域网访问地址。请仅在可信网络中使用这一选项，并确认系统防火墙允许访问。

安装或构建失败

先检查 Node.js 版本是否符合要求，并确认命令是在项目根目录（即包含 package.json 的目录）中运行。如果问题仍然存在，请复制完整的报错信息，并通过项目的 GitHub Issues 反馈。