Go Nav

一个配置驱动的个人 / 团队导航站，基于 Next.js 16、React 19、HeroUI v3 和 Tailwind CSS v4 构建。

Go Nav 既可以作为带登录后台的 Node.js 应用运行，也可以打包成不依赖 Node.js 的静态网站。推荐使用新的 HTML 运行时配置模式：开发者只需构建一次，使用者下载 web/ 后直接修改 nav.json、website.json，不必再次安装依赖或执行构建。

交流与支持

在线体验

官网：https://www.gotab.cn
项目预览：https://nav.gotab.cn
GitHub：https://github.com/dengxiwang/go-nav

功能特性

JSON / YAML 配置驱动，无需数据库
多级分类、网址管理、站内搜索和外部搜索引擎
响应式布局、明暗主题、最近访问和移动端导航
Server 模式支持前台访问密码，验证后才显示导航内容
网站信息、页脚、布局、广告、搜索引擎和自定义插件配置
Server 模式支持登录、图片上传、投稿审核、备份还原和远端同步
HTML 模式内置免登录可视化编辑页，支持导入和导出配置 ZIP
Server / HTML 模式支持书签导入与 HTML 书签导出，方便迁移到浏览器及其它书签管理软件
支持 Node.js、Docker、纯静态托管等多种部署方式

三种部署模式

模式	构建命令	产物	服务器需要 Node.js	配置修改后需重新构建	`/admin/`
HTML	`pnpm build:html`	`web/`	否	否	免登录配置编辑器，导出 ZIP 后手动覆盖
Server	`pnpm build:server`	`.next/standalone/`	是	否	完整后台，可直接保存、上传和备份
Static	`pnpm build:static`	`out/`	否	是	不提供

简单选择：

想要“构建一次，下载后只改 JSON”——使用 HTML 模式。
想要登录后台在线保存、上传图片和管理备份——使用 Server / Docker 模式。
只发布固定内容，配置变化时可以重新构建——使用 Static 模式。

build:html 和 build:static 都会生成纯静态文件，但两者的数据加载方式不同：HTML 模式在浏览器运行时读取 JSON；Static 模式把数据固化在构建产物中。

HTML 运行时配置模式（推荐）

HTML 模式是面向静态分发的新打包方式。构建者需要 Node.js 和 pnpm，但生成的 web/ 不再依赖 Node.js；拿到成品的使用者只需要一个普通静态文件服务器。

1. 构建可分发成品

git clone https://github.com/dengxiwang/go-nav.git
cd go-nav
pnpm install
pnpm build:html

构建完成后会生成：

web/
├── index.html
├── admin/
├── nav.json
├── website.json
├── uploads/
├── images/
├── _next/
├── _headers
├── .nojekyll
└── 部署说明.txt

其中：

nav.json：站点信息、主题、布局、搜索、广告、页脚和插件等配置。
website.json：分类、子分类和网址数据。
uploads/：本地图片资源。
admin/：纯浏览器端可视化配置编辑器。
_headers：为 Cloudflare Pages、Netlify 等平台声明 JSON 不缓存。
.nojekyll：避免 GitHub Pages 忽略下划线开头的静态资源目录。

需要发布下载包时，可以压缩整个目录：

cd web
zip -r ../go-nav-web.zip .

也可以直接把 web/ 提交到 Git，供其他人下载或部署。

2. 上传到静态网站

将 web/ 目录里面的全部文件 上传到网站运行根目录，确保 index.html、nav.json 和 website.json 位于同一级。

适用平台包括：

Nginx、Caddy、Apache
1Panel、宝塔等面板的 HTML 网站
GitHub Pages
Cloudflare Pages、Netlify
对象存储静态网站、CDN、NAS 静态站点服务

HTML 模式目前按照网站根路径生成资源地址。例如：

https://nav.example.com/
https://nav.example.com/nav.json
https://nav.example.com/website.json
https://nav.example.com/admin/

不建议直接部署到 https://example.com/go-nav/ 这类子目录；如需子路径部署，需要在构建前额外配置 Next.js basePath。

3. 修改配置

发布后有两种修改方式。

直接编辑 JSON

直接修改网站根目录的：

nav.json
website.json

保存并刷新页面即可生效，不需要运行：

pnpm install
pnpm build:html
pnpm build:static

如果需要使用本地图片，把文件放入 uploads/，配置中填写：

/uploads/图片文件名.png

使用可视化编辑器

访问：

https://你的域名/admin/

HTML 模式的后台不需要登录，因为它没有服务端 API，也不能直接改写服务器文件。编辑流程如下：

打开 /admin/，页面会读取当前的 nav.json 和 website.json。
在可视化页面中修改站点、分类、网址、主题、布局等配置。
没有产生修改时，“导出配置”按钮保持禁用。
修改后点击“导出配置”，浏览器会下载一个 ZIP。
解压 ZIP，将其中的 nav.json 和 website.json 覆盖到网站根目录。
刷新前台页面检查结果。

编辑器也支持导入之前导出的配置 ZIP，继续编辑后再次导出。

4. HTML 模式的能力边界

HTML 模式完全运行在浏览器内，因此：

可以编辑配置、导入配置和导出配置 ZIP。
不能直接把修改写回远程服务器。
不提供账号登录，因为不存在需要保护的服务端写入接口。
不提供图片上传、远端同步、自动抓取、在线备份还原和投稿审核队列。
图片需要手动上传到 uploads/。
静态投稿会根据配置生成预填邮件，不会写入服务端审核队列。

如果需要这些服务端能力，请使用 Server 或 Docker 模式。

5. 静态服务器缓存

页面每次读取 JSON 时会附加缓存破坏参数，构建产物也包含 _headers。如果使用自己的 Nginx，仍建议显式禁止缓存两个配置文件：

server {
    listen 80;
    server_name nav.example.com;

    root /var/www/go-nav;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location = /nav.json {
        add_header Cache-Control "no-cache, no-store, must-revalidate" always;
    }

    location = /website.json {
        add_header Cache-Control "no-cache, no-store, must-revalidate" always;
    }
}

修改 JSON 后如果仍看到旧内容，请依次检查浏览器缓存、CDN 缓存和服务器缓存规则。

6. 本地预览

构建完成后，macOS 可以双击 web/本地预览.command，Windows 可以双击 web/本地预览.bat，单个 .mjs 可以跨平台，但通常必须执行 node 本地预览.mjs，不能可靠双击。启动器会自动建立本地 HTTP 服务并打开浏览器。

也可以在项目目录中执行：

pnpm preview:html

默认访问地址：

http://127.0.0.1:4173/
http://127.0.0.1:4173/admin/

浏览器安全策略不允许 file:// 页面读取旁边的 JSON，因此仍不能直接双击 index.html；请双击随分发包生成的本地预览启动器。

7. 更新分发包

项目维护者修改 data/nav.json、data/website.json 或源码后，重新执行：

pnpm build:html

该命令会重新生成 web/，并把 data/ 中的配置转换为 web/nav.json 和 web/website.json。因此：

项目开发者编辑 data/*。
静态成品使用者编辑 web/*。
重新构建会覆盖 web/，构建前请备份只存在于 web/ 中的手工修改。

Server 模式

Server 模式包含完整后台、API、登录、上传和备份功能。

本地开发

git clone https://github.com/dengxiwang/go-nav.git
cd go-nav
pnpm install
cp .env.example .env.local
pnpm dev

访问：

前台：http://localhost:3000/
后台：http://localhost:3000/admin/

默认后台账号由环境变量提供：

ADMIN_USER=admin
ADMIN_PASS=admin123

生产环境务必修改密码。

前台访问密码

在 Server 模式后台打开「站点设置 → 访问保护」，设置访问密码并开启开关后保存。此后访问首页或网站详情页会先显示密码验证页，验证通过的设备会保留 7 天访问授权。

访问密码使用带随机盐的哈希保存在 nav.json，不会以明文写入配置。
修改访问密码后，之前签发的访问授权会立即失效。
管理后台和登录页不受前台访问保护影响。
HTML 和 Static 模式没有服务端校验能力，因此不支持该功能。

Node.js 生产部署

pnpm install
pnpm build:server
pnpm start

默认数据目录为项目根目录下的 data/。可以通过 DATA_DIR 使用外部持久化目录：

DATA_DIR=/var/lib/go-nav pnpm start

外部目录至少需要包含：

/var/lib/go-nav/
├── nav.json
├── website.json
└── uploads/

Docker 部署

Docker 使用 Server 模式，适合需要完整后台但不想手动维护 Node.js 环境的用户。

Docker Compose

cp .env.example .env

至少修改：

ADMIN_USER=admin
ADMIN_PASS=change-this-password
PORT=3000

启动：

pnpm docker:up

常用命令：

pnpm docker:logs
pnpm docker:down

默认使用项目目录下的 go-nav-data/ 持久化 /app/data。配置、上传文件和自动生成的登录密钥都保存在该目录中。

直接运行镜像

mkdir -p ./go-nav-data

docker run -d \
  --name go-nav \
  --restart unless-stopped \
  -p 3000:3000 \
  -e ADMIN_USER=admin \
  -e ADMIN_PASS=change-this-password \
  -v "$(pwd)/go-nav-data:/app/data" \
  doxwant/go-nav:latest

容器内的数据目录固定为 /app/data。挂载目录为空时，镜像会初始化默认配置和素材；已有文件不会被覆盖。

需要固定登录密钥时，可以额外设置：

SESSION_SECRET=change-this-to-a-long-random-string

Static 模式

Static 模式只导出前台页面：

pnpm build:static

产物位于 out/，可以部署到任意静态托管平台。该模式没有 /admin/、登录、API 和上传功能，data/ 中的数据会在构建时固化到页面中。

修改 data/nav.json 或 data/website.json 后必须再次执行 pnpm build:static。如果你的目标是部署后直接修改 JSON，请改用 pnpm build:html。

配置文件

默认数据目录：

data/
├── nav.json
├── website.json
├── submissions.json
└── uploads/

`nav.json`

主要配置项：

字段	说明
`title`、`name`、`description`、`keywords`	站点名称和 SEO 信息
`logo`、`favicon`	Logo 和浏览器图标
`author`、`copyright`	作者和版权信息
`icp`、`beian`	备案信息
`footerLinks`	页脚链接
`themeMode`	`light`、`dark` 或 `system`
`accessProtection`	Server 模式前台访问密码保护
`search`	站内搜索和搜索引擎配置
`ads`	首页和侧边栏广告配置
`submission`	投稿入口和静态投稿邮箱
`layout`	页面布局和显示开关
`plugins`	自定义 CSS / JavaScript

`website.json`

{
	"categories": [
		{
			"id": "tools",
			"name": "效率工具",
			"icon": "⚙️",
			"description": "常用工具集合",
			"sites": [
				{
					"title": "Go Nav",
					"description": "导航站项目",
					"url": "https://github.com/dengxiwang/go-nav",
					"icon": "/images/logo.svg",
					"previewImage": "/uploads/go-nav-cover.webp",
					"previewImages": [
						"/uploads/go-nav-home.webp",
						"/uploads/go-nav-admin.webp"
					],
					"detailMarkdown": "## 项目介绍\n\n支持 **Markdown** 详情正文。",
					"tags": ["nav", "nextjs"]
				}
			],
			"children": []
		}
	]
}

分类支持多级嵌套。网站图标可以使用 emoji、本地路径或远程 URL。

description 用于首页卡片摘要和本地搜索；previewImage 只作为预览图卡片的封面。开启网址详情页后，可以通过 previewImages 配置最多 8 张详情预览图，通过 detailMarkdown 配置支持 GFM 表格和普通换行的 Markdown 正文。未配置 previewImages 时，详情页会自动回退到 previewImage，已有数据无需迁移。Markdown 中的原始 HTML 不会执行。

项目也支持 nav.yaml 和 website.yaml。设置 DATA_FILE_FORMAT=yaml 时优先使用 YAML；HTML 构建最终仍会输出浏览器使用的 nav.json 和 website.json。

环境变量

变量	默认值	说明
`BUILD_MODE`	`server`	`server`、`static` 或 `html`
`ADMIN_USER`	`admin`	Server 模式后台用户名
`ADMIN_PASS`	`admin123`	Server 模式后台密码
`SESSION_SECRET`	自动生成或运行时生成	登录 Session 密钥
`DATA_DIR`	`./data`	Server 模式和构建时的数据目录
`DATA_FILE_FORMAT`	`json`	配置文件优先格式，可选 `json` / `yaml`
`NEXT_PUBLIC_SITE_URL`	-	用于生成 sitemap 的网站地址
`PORT`	`3000`	Docker Compose 宿主机映射端口

HTML 和 Static 模式没有服务端登录与请求校验能力，因此后台登录和前台访问密码保护均不可用，ADMIN_USER、ADMIN_PASS 和 SESSION_SECRET 对它们无效。

常用命令

命令	说明
`pnpm dev`	启动 Server 模式开发环境
`pnpm dev:static`	启动不包含后台和 API 的静态开发环境
`pnpm build`	等同于 `pnpm build:server`
`pnpm build:server`	构建 Node.js standalone 版本
`pnpm build:static`	构建到 `out/`，配置变化后需重建
`pnpm build:html`	构建到 `web/`，部署后可直接修改 JSON
`pnpm start`	启动 Server 模式生产服务
`pnpm lint`	运行 ESLint
`pnpm docker:build`	构建本地 Docker 镜像
`pnpm docker:up`	构建并启动 Docker Compose
`pnpm docker:logs`	查看 Docker Compose 日志
`pnpm docker:down`	停止 Docker Compose
`pnpm docker:push`	构建多架构镜像并推送到 Docker Hub

项目结构

go-nav/
├── app/                 # Next.js 页面和路由
├── components/          # 前台与后台组件
├── data/                # 源配置和上传数据
├── hooks/               # 自定义 Hooks
├── lib/                 # 配置读取、状态和服务端工具
├── public/              # 公共静态资源
├── scripts/             # 构建和 Docker 脚本
├── out/                 # Static 模式产物
├── web/                 # HTML 运行时配置版产物
├── Dockerfile
└── docker-compose.yml

常见问题

修改 `web/nav.json` 后为什么没有生效？

确认访问的是 HTTP / HTTPS 地址，并清理浏览器或 CDN 缓存。服务器应对 nav.json 和 website.json 设置 Cache-Control: no-cache。

为什么 HTML 后台点击导出后没有直接保存到服务器？

HTML 模式是纯静态网站，浏览器没有服务器文件系统写入权限。导出 ZIP 后，需要手动覆盖网站根目录中的两个 JSON 文件。

为什么 HTML 后台不需要登录？

它只是本地配置编辑器，没有服务端写入、上传或管理接口。任何人在浏览器里做的修改都不会自动影响线上文件，只有拥有服务器上传权限的人才能真正发布配置。

可以直接打开 `web/index.html` 吗？

浏览器会限制 file:// 页面读取 JSON，因此不能直接双击 index.html。HTML 分发包已附带本地预览启动器：macOS 双击 本地预览.command，Windows 双击 本地预览.bat，即可自动打开网站。

HTML 模式可以部署到子目录吗？

默认不支持。当前资源和配置请求以网站根路径为准；部署到子目录前需要配置 basePath 并重新构建。

`web/` 是否可以直接提交到 Git？

可以。也可以只在 Release 中发布 go-nav-web.zip。需要注意 .nojekyll 是隐藏文件，打包和上传时不要遗漏。

技术栈

开源协议

本项目基于 MIT License 开源。你可以自由使用、修改和商用，但请保留原始项目署名信息。

捐赠支持

如果这个项目帮到了你，欢迎扫码支持。

Name		Name	Last commit message	Last commit date
.pnpm-store/v11		.pnpm-store/v11
.vscode		.vscode
app		app
components		components
data		data
hooks		hooks
lib		lib
public		public
scripts		scripts
types		types
web		web
.claude		.claude
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.ncurc		.ncurc
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation