安装
PHP安装
到PHP: Downloads进行安装
# Download and install PHP 8.5 - Thread-safe
winget install PHP.PHP.8.5
也可以下载压缩包，例如：https://downloads.php.net/~windows/releases/php-8.5.7-Win32-vs17-x64.zip 解压到某个目录下，例如：D:\php\php8.5.7 让你的AI将该路径添加到系统环境变量。
然后复制一份php.ini-development为php.ini并打开编辑：搜索curl找到类似;extension=curl这样的代码块，在前面添加一坨：
extension=curl
extension=fileinfo
extension=gd
extension=intl
extension=mbstring
extension=openssl
extension=zip
如果不打开，后面创建grav的时候会出错：PHP Modules: There were problems with required modules。
还要搜索extension_dir找到类似如下的地方：
; On windows:
;extension_dir = "ext"
修改为你的安装目录路径，例如：extension_dir = "D:/php/php8.5.7/ext"
安装grav
到 Releases · getgrav/grav下载，如果不需要管理后台的下载类似grav-v2.0.7.zip这样的包，如果需要管理后台的下载类似grav-admin-v2.0.7.zip这样的包。
然后解压到某个目录下，例如：F:\blog-test\myblog1
在命令行执行：
cd /d F:\blog-test\myblog1
php -S localhost:8080 system/router.php
浏览器访问：http://localhost:8080 后台访问：http://localhost:8080/admin 第一次运行后台会引导你创建管理员账号。
更新维护
下面假设你的本地 Grav 目录是：
D:\grav-sites\blog-main\
线上 FTP 目录是：
/www/wwwroot/blog/
自定义主题目录假设是：
user/themes/my-theme/
如果你的实际目录不同，把示例路径替换成自己的即可。
一、首次编写第一个博客文件，并整体部署 Grav 到 FTP 线上
1. 确认本地 Grav 能正常运行
进入本地 Grav 根目录：
cd /d D:\grav-sites\blog-main
启动本地服务：
php -S localhost:8080 system/router.php
浏览器访问：
http://localhost:8080
如果能正常打开，说明本地 Grav 环境已经可用。
2. 创建第一篇博客文章
进入博客文章目录。常见博客目录是：
D:\grav-sites\blog-main\user\pages\02.blog\
如果你当前没有 02.blog，可以先创建：
mkdir D:\grav-sites\blog-main\user\pages\02.blog
然后创建第一篇文章目录：
mkdir D:\grav-sites\blog-main\user\pages\02.blog\my-first-post
在这个目录下新建文章文件：
D:\grav-sites\blog-main\user\pages\02.blog\my-first-post\item.md
内容示例：
---
title: 我的第一篇 Grav 博客
date: 2026-07-06
taxonomy:
category:
- blog
tag:
- Grav
- 博客
- 建站
---
这是我的第一篇 Grav 博客文章。
## 为什么选择 Grav
Grav 是一个基于文件的 CMS，不需要数据库，文章、配置、主题都可以直接用文件管理。
## 本地维护方式
我计划使用以下方式维护博客：
1. Windows 本地运行 Grav 进行预览；
2. 使用 SVN 或 Git 管理文章、配置和主题；
3. 满意后通过 FTP 上传到线上。
## 后续计划
后面我会继续完善主题样式、文章分类和标签体系。
如果你想给文章加封面图，可以把图片放在同一目录：
D:\grav-sites\blog-main\user\pages\02.blog\my-first-post\cover.jpg
然后在文章里引用：
3. 本地预览第一篇文章
重新访问本地站点：
http://localhost:8080
检查：
首页是否正常
博客列表是否出现新文章
文章标题是否正确
文章正文是否正常
标签和分类是否正常
图片是否正常显示
如果文章没有出现在列表里，重点检查：
1. 文章目录是否放在 user/pages/02.blog/ 下
2. 文件名是否是 item.md
3. FrontMatter 的 --- 是否完整
4. 主题是否支持博客列表
5. 是否需要清理缓存
本地清理缓存可以直接删除：
D:\grav-sites\blog-main\cache\
或者执行：
bin\grav clear-cache
4. 提交到 SVN 或 Git
如果你用 SVN：
cd /d D:\grav-sites\blog-main
svn status
svn add user\pages\02.blog\my-first-post --force
svn commit -m "add first blog post"
如果你用 Git：
cd /d D:\grav-sites\blog-main
git status
git add user/pages/02.blog/my-first-post
git commit -m "add first blog post"
建议首次部署前，至少把这些目录提交：
user/pages
user/config
user/themes
user/plugins
user/images
user/data
5. 首次整体部署到 FTP 线上
首次部署时，如果线上还没有 Grav，需要上传一整套 Grav 文件。
本地需要上传：
D:\grav-sites\blog-main\index.php
D:\grav-sites\blog-main\.htaccess
D:\grav-sites\blog-main\system\
D:\grav-sites\blog-main\user\
D:\grav-sites\blog-main\vendor\
D:\grav-sites\blog-main\bin\
D:\grav-sites\blog-main\composer.json
D:\grav-sites\blog-main\composer.lock
不建议上传：
cache\
logs\
tmp\
backup\
也就是说，首次上传到线上后，线上目录大致应该是：
/www/wwwroot/blog/
├── index.php
├── .htaccess
├── system/
├── user/
├── vendor/
├── bin/
├── composer.json
└── composer.lock
如果你是 Apache 环境，.htaccess 很重要，建议上传。
如果你是 Nginx 环境，.htaccess 不生效，需要服务器里配置 Nginx 重写规则。你的虚拟主机如果已经支持 PHP 和伪静态，一般问题不大。
6. FTP 上传建议
用 FileZilla、WinSCP 或其他 FTP 工具连接服务器。
上传前建议先确认线上目标目录，例如：
/www/wwwroot/blog/
不要误传到：
/www/wwwroot/
也不要传到：
/www/wwwroot/blog/blog-main/
否则访问路径可能会变成：
https://你的域名/blog-main/
正确结果应该是：
https://你的域名/
对应线上目录里直接能看到：
index.php
system/
user/
vendor/
7. 首次部署后检查
浏览器访问你的线上域名：
https://你的域名/
检查：
首页是否打开
第一篇文章是否显示
文章详情页是否能打开
图片是否正常显示
主题是否生效
后台是否能访问
后台通常是：
https://你的域名/admin
如果页面异常，优先检查：
1. vendor 是否上传完整
2. user 是否上传完整
3. .htaccess 是否上传
4. PHP 版本是否符合 Grav 要求
5. 线上目录权限是否允许写 cache/logs
6. 线上是否需要清理 cache
如果需要清理缓存，可以通过 FTP 删除线上：
/www/wwwroot/blog/cache/
Grav 会自动重新生成缓存。
二、后续新建一篇博客，只上传该文章到线上
第一次整站部署完成后，后续新增文章就不需要整站上传了。
只需要上传新增文章目录。
1. 本地新建第二篇文章
创建目录：
mkdir D:\grav-sites\blog-main\user\pages\02.blog\second-post
创建文件：
D:\grav-sites\blog-main\user\pages\02.blog\second-post\item.md
内容示例：
---
title: 第二篇博客：Grav 本地维护流程
date: 2026-07-06
taxonomy:
category:
- blog
tag:
- Grav
- 维护
- FTP
---
这篇文章记录 Grav 博客的日常维护流程。
## 本地编辑
文章在 Windows 本地编辑，使用 VS Code 或 Typora 编写 Markdown。
## 本地预览
通过 PHP 内置服务器启动 Grav：
```bat
php -S localhost:8080 system/router.php
然后访问：
http://localhost:8080
上传线上
确认效果后，只需要上传本篇文章目录即可。
注意：上面 Markdown 里面有代码块，实际写文章时要注意代码块的反引号不要嵌套混乱。
为了避免嵌套问题，也可以写成简单版本：
```markdown
---
title: 第二篇博客：Grav 本地维护流程
date: 2026-07-06
taxonomy:
category:
- blog
tag:
- Grav
- 维护
- FTP
---
这篇文章记录 Grav 博客的日常维护流程。
## 本地编辑
文章在 Windows 本地编辑，使用 VS Code 或 Typora 编写 Markdown。
## 本地预览
通过 PHP 内置服务器启动 Grav，然后访问本地站点查看效果。
## 上传线上
确认效果后，只需要上传本篇文章目录即可。
2. 本地预览
启动本地 Grav：
cd /d D:\grav-sites\blog-main
php -S localhost:8080 system/router.php
访问：
http://localhost:8080
检查第二篇文章：
是否出现在博客列表
标题是否正确
正文排版是否正常
标签是否正常
图片是否正常
3. 提交到 SVN 或 Git
SVN：
cd /d D:\grav-sites\blog-main
svn status
svn add user\pages\02.blog\second-post --force
svn commit -m "add second blog post"
Git：
cd /d D:\grav-sites\blog-main
git status
git add user/pages/02.blog/second-post
git commit -m "add second blog post"
4. 只上传这篇文章目录到线上
本地目录：
D:\grav-sites\blog-main\user\pages\02.blog\second-post\
上传到线上：
/www/wwwroot/blog/user/pages/02.blog/second-post/
也就是说，只上传：
second-post/
├── item.md
└── 图片文件，如果有
不需要上传：
system/
vendor/
整个 user/
整个 themes/
5. 线上检查
访问线上首页或博客列表页：
https://你的域名/
检查：
第二篇文章是否出现
文章详情页是否能打开
图片是否正常
分类标签是否正常
如果文章没有出现，可以通过 FTP 删除线上缓存：
/www/wwwroot/blog/cache/
或者登录后台清理缓存。
6. 后续修改已有文章怎么做
如果只是修改已有文章：
本地修改：
D:\grav-sites\blog-main\user\pages\02.blog\second-post\item.md
本地预览满意后提交：
svn commit user\pages\02.blog\second-post\item.md -m "update second post"
然后只上传：
item.md
到线上：
/www/wwwroot/blog/user/pages/02.blog/second-post/item.md
如果同时改了图片，也上传图片。
三、修改主题，并更新到线上
主题修改比文章修改风险更高，所以流程要更谨慎。
1. 确认当前使用的主题
查看本地配置文件：
D:\grav-sites\blog-main\user\config\system.yaml
里面通常会有类似：
pages:
theme: my-theme
这说明当前主题是：
my-theme
对应目录：
D:\grav-sites\blog-main\user\themes\my-theme\
如果你不确定主题名，也可以在 Grav 后台里看当前启用的主题。
2. 主题修改前先提交一次干净版本
修改主题前先确认工作区状态。
SVN：
cd /d D:\grav-sites\blog-main
svn status
Git：
cd /d D:\grav-sites\blog-main
git status
如果有未提交内容，先提交。
SVN 示例：
svn add user --force
svn commit -m "backup before theme update"
Git 示例：
git add user
git commit -m "backup before theme update"
这样 Codex 或手工修改不满意时，可以回滚。
3. 做一个简单主题修改示例
假设你想修改文章标题样式。
主题 CSS 可能在：
D:\grav-sites\blog-main\user\themes\my-theme\css\custom.css
或者：
D:\grav-sites\blog-main\user\themes\my-theme\css\theme.css
如果没有 custom.css，可以新建一个：
D:\grav-sites\blog-main\user\themes\my-theme\css\custom.css
添加示例样式：
.post-title,
.blog-title,
h1 {
letter-spacing: 0.02em;
line-height: 1.35;
}
如果你想更明显地测试主题是否生效，可以临时加一条：
body {
font-size: 17px;
}
注意：不要一开始做很大改版，先做小修改验证流程是否跑通。
4. 确认 CSS 是否被主题引用
如果你修改的是已有 CSS 文件，比如 theme.css，一般不需要额外处理。
如果你新建了 custom.css，需要确认主题模板是否加载了它。
常见模板位置：
D:\grav-sites\blog-main\user\themes\my-theme\templates\partials\base.html.twig
或者：
D:\grav-sites\blog-main\user\themes\my-theme\templates\partials\head.html.twig
你需要找到类似 CSS 加载的地方：
{% block stylesheets %}
{% do assets.addCss('theme://css/theme.css') %}
{% endblock %}
加上：
{% do assets.addCss('theme://css/custom.css') %}
示例：
{% block stylesheets %}
{% do assets.addCss('theme://css/theme.css') %}
{% do assets.addCss('theme://css/custom.css') %}
{% endblock %}
如果你的主题结构不同，不要硬改。可以先搜索：
assets.addCss
或者搜索：
theme.css
找到 CSS 加载位置。
5. 本地预览主题修改
启动本地 Grav：
cd /d D:\grav-sites\blog-main
php -S localhost:8080 system/router.php
访问：
http://localhost:8080
检查：
首页是否正常
博客列表是否正常
文章详情页是否正常
标题样式是否变化
移动端是否正常
后台是否还能访问
如果样式没有生效，尝试：
1. 清理 Grav 缓存
2. 浏览器 Ctrl + F5 强制刷新
3. 检查 custom.css 是否真的被模板引用
4. 检查路径是否写成 theme://css/custom.css
本地可以删除：
D:\grav-sites\blog-main\cache\
或者执行：
bin\grav clear-cache
6. 查看主题变更
SVN：
cd /d D:\grav-sites\blog-main
svn status
svn diff user\themes\my-theme
Git：
cd /d D:\grav-sites\blog-main
git status
git diff user/themes/my-theme
确认只改了预期文件，例如：
user/themes/my-theme/css/custom.css
user/themes/my-theme/templates/partials/base.html.twig
不要误改：
system/
vendor/
cache/
logs/
tmp/
7. 提交主题修改
SVN：
svn add user\themes\my-theme --force
svn commit user\themes\my-theme -m "update theme styles"
Git：
git add user/themes/my-theme
git commit -m "update theme styles"
8. 上传主题修改到线上
如果只改了 CSS，可以只上传：
D:\grav-sites\blog-main\user\themes\my-theme\css\custom.css
到线上：
/www/wwwroot/blog/user/themes/my-theme/css/custom.css
如果你还改了模板，例如：
D:\grav-sites\blog-main\user\themes\my-theme\templates\partials\base.html.twig
也要上传到：
/www/wwwroot/blog/user/themes/my-theme/templates/partials/base.html.twig
如果不确定改了哪些文件，可以上传整个主题目录：
D:\grav-sites\blog-main\user\themes\my-theme\
到线上：
/www/wwwroot/blog/user/themes/my-theme/
首次主题修改建议上传整个主题目录，后续熟悉后可以只上传改动文件。
9. 清理线上缓存并检查
主题修改后，线上建议清理缓存。
方式一：后台清理缓存。
访问：
https://你的域名/admin
找到清理缓存功能。
方式二：FTP 删除：
/www/wwwroot/blog/cache/
然后访问正式站，强制刷新浏览器：
Ctrl + F5
检查：
首页是否正常
文章列表是否正常
文章详情页是否正常
CSS 是否生效
手机端是否正常
后台是否还能打开
10. 如果主题上线后出问题，怎么回滚
SVN 回滚
查看主题历史：
svn log user\themes\my-theme
恢复到指定版本：
svn update -r 版本号 user\themes\my-theme
确认本地正常后，再提交回滚结果：
svn commit user\themes\my-theme -m "rollback theme update"
重新上传：
D:\grav-sites\blog-main\user\themes\my-theme\
到线上：
/www/wwwroot/blog/user/themes/my-theme/
Git 回滚
查看提交：
git log --oneline
恢复主题目录：
git checkout 提交ID -- user/themes/my-theme
git add user/themes/my-theme
git commit -m "rollback theme update"
然后重新上传主题目录到线上。
四、三个场景的最简流程总结
1. 首次部署
本地搭好 Grav
↓
创建第一篇文章
↓
本地 php -S 预览
↓
SVN/Git 提交
↓
FTP 上传整站：index.php、system、user、vendor、bin、.htaccess
↓
线上访问域名检查
↓
清理缓存
2. 新增文章
本地创建 user/pages/02.blog/文章目录/item.md
↓
本地预览
↓
SVN/Git 提交
↓
FTP 只上传该文章目录
↓
线上检查文章
上传范围：
user/pages/02.blog/文章目录/
3. 修改主题
先提交当前稳定版本
↓
本地修改 user/themes/你的主题
↓
本地预览首页、列表页、详情页、移动端
↓
SVN/Git 提交
↓
FTP 上传主题目录或改动文件
↓
线上清缓存
↓
线上检查
上传范围：
user/themes/你的主题/
五、建议你固定下来的日常习惯
每次更新都按这个顺序：
1. 本地修改
2. 本地预览
3. SVN/Git 提交
4. FTP 上传
5. 线上清缓存
6. 线上检查
不要反过来：
先 FTP 改线上
满意后再下载备份
最终你要保持这个原则：
本地 Grav 是主库，SVN/Git 是版本记录，FTP 只是发布通道，线上只负责运行。
文档信息
- 本文作者：zhupite
- 本文链接：https://zhupite.com/dev/grav-blog.html
- 版权声明：自由转载-非商用-非衍生-保持署名（创意共享3.0许可证）