常见问题
常见问题
安装和配置
Q: npm install 很慢或失败？
解决方案：
BASH
# 使用国内镜像
npm install --registry https://registry.npmmirror.com
# 或设置为永久镜像
npm config set registry https://registry.npmmirror.com
# 清除缓存
npm cache clean --force
Q: 启动时提示端口被占用？
解决方案：
BASH
# 使用其他端口启动
npx @11ty/eleventy --serve --port=8081
Q: 配置修改后没有生效？
解决方案：
重启开发服务器（按 Ctrl+C 停止，然后重新运行 npm run serve）
写作和内容
Q: 双链不生效，显示为普通文字？
检查：
- 确保目标文件存在于
content/目录下 - 检查文件名拼写（支持大小写不敏感）
- 查看构建警告是否有重名文件
Q: 图片不显示怎么办？
检查清单：
- 图片文件在
content/目录下 - 使用正确的语法：
![[图片.jpg]] - 文件格式支持：JPG、PNG、GIF、SVG、WebP
- 检查是否有重名文件
Q: 如何添加标签和分类？
在文件开头添加：
MARKDOWN
---
title: 文章标题
tags: [标签1, 标签2]
category: 分类名
---
Q: 重名文件警告如何处理？
解决方法：
重命名其中一个文件，使用更具描述性的名称：
- 将
笔记.md改为React学习笔记.md - 将
图片.jpg改为项目截图.jpg
功能使用
Q: 如何启用卡片视图？
在文件头部添加：
MARKDOWN
---
cssclasses: list-cards
---
Q: 搜索功能不工作？
检查：
- 确认
garden.config.js中search.enabled: true - 重启开发服务器
- 确保有内容可搜索
Q: 评论系统如何配置？
基本步骤：
- 选择评论系统（推荐 Giscus）
- 获取配置代码
- 添加到
garden.config.js的comments.html部分 - 重启服务器
Q: 如何自定义样式？
方法：
在 src/assets/css/custom/ 目录下创建 .css 文件，系统会自动合并。
部署问题
Q: GitHub Pages 部署失败？
检查：
- 仓库是否公开
- GitHub Actions 权限设置
- 构建脚本是否正确
Q: Vercel 部署提示错误？
常见解决：
- 确保 Node.js 版本 18+
- 检查
package.json中的构建命令 - 查看 Vercel 构建日志
性能优化
Q: 网站加载慢怎么办？
优化建议：
- 压缩大尺寸图片（建议 < 1MB）
- 减少不必要的插件
- 使用 CDN 加速
Q: 构建时间太长？
可能原因：
- 文件数量过多
- 图片文件过大
- 双链解析复杂度高
其他问题
Q: Windows 下权限问题？
解决方案：
POWERSHELL
# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Q: macOS 下安装报错？
常见解决：
BASH
# 使用 sudo 安装全局包
sudo npm install -g 包名
# 或配置 npm 默认目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
Q: 中文文件名有问题吗？
完全支持！ 系统对中文文件名支持很好，包括大小写不敏感匹配。
获取更多帮助
如果以上方案无法解决你的问题：
- 查看详细文档：README.md 文件有完整的功能说明
- 检查构建日志：查看命令行输出的错误信息
- 提交 Issue：GitHub Issues
- 社区讨论：GitHub Discussions
记住：大部分问题都有简单的解决方案，不要因为技术问题而放弃你的数字花园！