简介：Neo4j 5.23.0 社区版 Windows 压缩包，面向图数据库初学者、后端开发者以及需要快速搭建图数据实验环境的工程人员，帮助他们在 Windows 平台上从零部署图数据库，并验证 Cypher 查询与关系建模。包内共 264 个文件，以 235 个 jar 依赖为核心运行时与浏览器组件，辅以 3 个 bat 与 6 个 ps1 启停脚本、2 个 conf 配置文件、2 个 exe 服务注册程序，另有 txt 说明、xml、cer 证书等配套文件，整体约 119.26MB；解压后即可按目录结构启动服务。配置层面保留了 neo4j.conf、neo4j-admin.conf 等服务端与运维参数，启动后可直接用 Cypher 完成节点、边与属性的增删改查，并借助内置浏览器组件做数据可视化。已有 527 人学习下载，适合用来熟悉图模型建模、关系遍历与深度查询的完整流程。

1. 版本选型：5.23.0 社区版在 Windows 上到底装哪一份

一个跑了两周的图数据库 Demo，最后卡在 Neo4j 起不来的黑窗口上——这种情况我见过不止一次。neo4j-chs-community-5.23.0-windows.zip是 Neo4j 5.23.0 社区版面向 Windows 的中文包，解压即用、不写注册表、不污染系统，看起来比 Linux 上那套源安装省事得多。但 JDK 版本、配置项键名、默认监听地址这三处，5.x 和网上大多数 4.x 教程完全不是一回事。装对了十分钟跑通，装错了就是反复重启加一堆看不懂的日志。下面按我实际落地的顺序，从环境盘点一路写到冒烟验证。

2. 装前环境盘点：JDK 17、端口与目录先对齐

Windows 上装 Neo4j 翻车，八成不是数据库本身的问题，是前置条件没对齐。Neo4j 5.x 的启动脚本会自己去找 Java，找错了就一句话报错退出，窗口一闪而过，连日志都不给你留。所以动手解压之前，先把 Java、端口、落地路径这三件事固定下来，后面能省掉一大半排查时间。

2.1 JDK 版本必须固定在 17，别用 8 和 11

Neo4j 5.23 跑在 Java 17 上，21 也能用，但 8 和 11 会直接抛UnsupportedClassVersionError退出。很多人机器上本来就装着 JDK 8 跑别的项目，java -version一看是 1.8，就以为是版本低点没事——不是低点没事，是根本起不来。

先确认当前窗口里的 Java 到底是谁：

where java java -version echo %JAVA_HOME%

where java会按 PATH 顺序列出所有java.exe。如果第一条指向C:\Program Files\Common Files\Oracle\Java\javapath这种目录，说明是安装器塞进去的转发壳，版本未必是你想要的那个。java -version看首行是不是17.0.x；echo %JAVA_HOME%输出为空或者指向...\jre，都是不合格的，后面 Neo4j 启动脚本会拿它去找 JVM。

我一般会把 JDK 单独解压到一个干净的目录，比如D:\env\jdk-17.0.11，然后写系统变量：

setx JAVA_HOME "D:\env\jdk-17.0.11" /M setx PATH "%JAVA_HOME%\bin;%PATH%" /M

/M表示写系统变量，必须用管理员身份开命令行，否则会写到当前用户变量里，注册成 Windows 服务之后又读不到。第二条命令里的%JAVA_HOME%是在命令执行那一刻展开的，如果当前窗口的JAVA_HOME还是空的，写进去的就是字面量%JAVA_HOME%\bin，这是个很隐蔽的坑——所以先执行第一条，新开一个窗口再执行第二条。另外setx对 PATH 有长度截断的风险，PATH 已经很长的话直接用「系统属性 → 环境变量」的图形界面改更稳妥。

JAVA_HOME一定要指向 JDK 根目录，不是bin，也不是jre子目录。改完之后关掉所有命令行窗口重开，java -version能出 17 才算这一步过了。

提示：如果不想动全局环境变量，也可以在bin\neo4j.bat同目录下临时设set JAVA_HOME=D:\env\jdk-17.0.11再执行，只对当前窗口生效，适合多版本共存时试跑。

2.2 端口、磁盘和路径的三条硬约束

Neo4j 默认占用三个端口，社区版不存在集群通信那堆端口，冲突概率不算高，但撞上了排查起来很费时间：

启动前扫一眼有没有被占：

netstat -ano | findstr ":7474 :7473 :7687"

findstr后面多个关键词用空格隔开，是「或」的关系，任意一个命中就打印行。有输出就记下最后一列的 PID，用tasklist | findstr <PID>看是哪个进程。我遇到过一次 7474 被某个本地调试工具占了，Neo4j 启动日志里只有一行Address already in use，不熟悉的人容易以为是配置写错了。

磁盘方面，社区版默认的data目录会随着写入持续增长，加上事务日志和页面缓存文件，我个人习惯给数据盘留 20G 起步。还有一条容易被忽略：别把 Neo4j 放在 OneDrive、坚果云这类同步目录里，同步客户端会去读正在被数据库加锁的文件，轻则启动报锁文件冲突，重则data目录被同步成半截状态。路径上也不要带空格和中文，更不要放C:\Program Files下面——UAC 的目录虚拟化会把写入重定向到用户目录，配置文件改了不生效，这种问题查起来最费劲。放在D:\neo4j\这种一级目录下最省心。

2.3 解压后先认目录：每个文件夹各管什么

解压完先别急着启动，花两分钟把目录结构过一遍，后面调参和排错都靠它定位：

data是整个安装的唯一命根子，升级、换机器、重装之前，先neo4j.bat stop停库，再把整个data目录拷走。直接热拷文件系统的做法在 Windows 上大概率拿到不一致的状态，恢复回去起不来。logs目录相反，出问题的时候随便清，重启会自己重建。

3. 解压即安装：zip 包落地与首次启动

这套包没有安装向导，所谓的「安装」其实就是解压 + 改配置 + 启动三步。但每一步都有个二选一：解压到哪、怎么跑、密码怎么设。选错了不影响首次启动，会在后面某个时刻反过来找你麻烦。

3.1 解压位置与服务注册的二选一

别用资源管理器右键那个「全部解压缩」，它会默认解到一层带中文名的临时目录里，路径又长又不好找。用 7-Zip 之类的工具直接解到目标位置，最终目录是D:\neo4j\neo4j-community-5.23.0。

接下来是运行方式的选择，这一步决定了你后面怎么启停：

cd /d D:\neo4j\neo4j-community-5.23.0\bin neo4j.bat console

console是前台模式，日志直接刷在窗口里，Ctrl+C 停库，窗口关掉库就停了。第一次装、第一次调配置，我都用这个模式跑一遍，因为启动过程中的异常会直接打印在屏幕上，不用去翻日志文件。

确认能正常起来之后，再考虑注册成服务：

neo4j.bat install-service neo4j.bat start neo4j.bat status neo4j.bat stop

install-service必须用管理员身份执行，服务名默认就叫neo4j。status输出Neo4j is running at pid xxxx才算真的起来了，只看到start命令返回成功不算数——服务注册成功但进程立刻退出，start也是返回成功的。同一台机器上不要给两个版本都注册服务，服务名会冲突，我一般只把常用的那个注册成服务，另一个留着用console临时起。

3.2 neo4j.conf 里 5.x 必须改的几行

配置文件在conf\neo4j.conf，用任意编辑器打开，按下面这几块改。注意键名，5.x 把大量dbms.前缀改成了server.，照抄 4.x 教程的写法在 5.23 上是不生效的：

# 监听地址，5.x 默认只监听 localhost，局域网内其它机器连不上 server.default_listen_address=0.0.0.0 # Bolt 端口，Python/Java/JS 驱动都走这里 server.bolt.listen_address=:7687 # 浏览器控制台 server.http.listen_address=:7474 server.https.enabled=true server.https.listen_address=:7473 # 堆内存，5.x 是 server.memory.*，不是 dbms.memory.* server.memory.heap.initial_size=2G server.memory.heap.max_size=2G server.memory.pagecache.size=1G # LOAD CSV 的相对路径基准目录，默认就是 import server.directories.import=import

几处说明。server.default_listen_address是总开关，4.x 后期和 5.x 都把它收紧成了localhost，这是出于安全考虑的默认值，本机开发不用改，但只要想让同事的浏览器打开控制台，就必须改成0.0.0.0。initial_size和max_size设成一样是常见做法，避免运行期堆反复伸缩带来的 GC 抖动，代价是启动时就把内存占住。pagecache.size的取值思路是尽量装下整个 store 文件，后面第 4 章会细说。

改完保存，回到bin目录用console起一次，看日志里有没有Unrecognized setting之类的告警。5.x 对未知配置项比较严格，写错的键名会直接在启动日志里点名。

3.3 首次启动、初始密码与 neo4j-admin 的用法

认证这块有两条路。第一条是不管它，直接用默认的neo4j/neo4j登录，浏览器会强制你改密码，改完才能进控制台。第二条是启动前就把密码定死：

neo4j-admin.bat dbms set-initial-password "你的强密码"

这个命令有个硬性前提：必须在第一次启动之前执行，一旦data\dbms\auth文件已经生成，再执行就不起作用了，有的场景下还不报错，让人以为是密码没设对。密码策略要求至少 8 位，太简单的会被拒绝。

首次console启动，正常的日志末尾会看到类似Started.的提示，然后浏览器打开http://localhost:7474，Bolt 地址那一栏填bolt://localhost:7687，用户名neo4j，密码填你刚设的。如果窗口停在Starting Neo4j...超过一分钟不动，别干等，切到logs\neo4j.log看最后二十行，绝大多数问题那里都有明确结论。

4. 内存、端口与中文环境：三块配置的取舍

配置项改完能起来，只是及格线。真正决定这套图数据库在你机器上是流畅还是卡顿的，是内存怎么分、端口怎么开、中文怎么处理这三块。这三块也是版本差异最集中的地方，照抄老教程翻车的概率最高。

4.1 堆内存和页缓存：别照抄 4.x 的 dbms.memory

Neo4j 的内存分两池：JVM 堆和页缓存。堆给查询执行、事务状态、临时结果集用，页缓存给磁盘文件的映射页用。两者抢同一块物理内存，配比失衡的表现完全不同——堆太小会频繁 Full GC，表现为查询间歇性卡顿几秒；页缓存太小会频繁读盘，表现为「第一次查很慢，第二次还是慢」。

5.x 的键名是server.memory.heap.initial_size、server.memory.heap.max_size、server.memory.pagecache.size。老的dbms.memory.*在 5.x 上要么被忽略，要么启动告警，网上大量 4.x 的调优文章直接抄过来是无效的，这是我在真机上验证过的差异。

配比按机器内存来，我常用的经验值：

页缓存的目标是能装下整个 store 文件。先看数据有多大：

dir /s D:\neo4j\neo4j-community-5.23.0\data\databases\neo4j

把neostore.*系列文件加起来的体积乘以 1.2，就是页缓存比较理想的取值。超过物理内存的 60% 就别再往上加了，Windows 一旦开始换页，整机都会跟着卡，那种卡不是数据库慢，是鼠标都拖不动。批量导入 CSV 的时候我会临时把堆抬到 8G，导完再降回来，因为LOAD CSV的中间结果在堆里，堆不够会直接 OOM 中断导入。

4.2 监听地址与端口：从 localhost 放开到局域网

server.default_listen_address是兜底值，具体端口的listen_address优先级更高。也就是说，如果你只改了server.bolt.listen_address=0.0.0.0:7687，Bolt 会对外开放，但 HTTP 控制台仍然只听 localhost——很多人以为自己「全开了」，结果同事打开 7474 还是转圈，问题就出在这。

端口撞了的时候，改法很直接：

# 7474 被占，改成 7475 server.http.listen_address=:7475 server.https.listen_address=:7476 server.bolt.listen_address=:7688

改完端口，应用侧的连接串也要同步改，bolt://host:7688。这类改动我一般会在项目里记一行注释，不然过两个月换机器部署，忘了当初为什么不是默认端口。

局域网要能访问，光改配置不够，还得在防火墙上开口子：

netsh advfirewall firewall add rule name="Neo4j HTTP" dir=in action=allow protocol=TCP localport=7474 netsh advfirewall firewall add rule name="Neo4j Bolt" dir=in action=allow protocol=TCP localport=7687

dir=in是入站方向，action=allow放行，localport指定端口；删规则把add换成delete，name保持一致就行。

注意：社区版没有细粒度的用户权限体系，把所有用户都当成管理员。把它直接暴露在公网端口上风险很高，只在受控的内网环境里放开监听地址。

4.3 中文包在 Windows 上的编码、日志与导入目录

包名里的chs表示这是中文版本，界面文案和自带文档做了本地化，但配置项的键名和社区版完全一致，改配置的时候不用去找什么「中文版专用写法」。

数据库内部存储的字符串统一是 UTF-8，这一点跟 Windows 的系统代码页没关系，属性值写中文存进去再读出来是乱码这类问题，几乎都发生在导入和日志输出两个环节：

# 让 JVM 用 UTF-8 输出，避免日志里的中文变成问号 server.jvm.additional=-Dfile.encoding=UTF-8

日志在logs\下，neo4j.log是运行日志，debug.log是详细诊断日志，排查启动失败主要看这两个。加了上面这行之后，日志里的中文节点名、中文报错信息才正常显示。

导入 CSV 时有两个具体注意点。一是文件编码，Excel 另存的 CSV 默认是 GBK，LOAD CSV读进来会把中文变成乱码或者替换字符，导入前用编辑器另存为「UTF-8 无 BOM」。二是路径，LOAD CSV只能读import目录下的相对路径：

// 文件放 D:\neo4j\neo4j-community-5.23.0\import\person.csv LOAD CSV WITH HEADERS FROM 'file:///person.csv' AS row RETURN row.name, row.city LIMIT 5;

file:///后面只写文件名，不要写D:\...这种绝对路径，5.x 默认不允许从 import 目录之外加载文件。先LIMIT 5看一眼中文有没有乱，再正式导入，这个小习惯帮我省过好几次重导的时间。

5. 排查：起不来、连不上、忘密码的五种翻车现场

前面按流程走，大部分情况能顺利跑通。真出问题的时候，症状往往只有一句很笼统的报错，剩下全靠经验定位。下面这五种是我在 Windows 上遇到频率最高的，按「现象 → 原因 → 解决」记下来。

5.1 双击 neo4j.bat，窗口一闪就没

现象：双击bin\neo4j.bat或者console，黑窗口闪一下就关了，什么信息都没留下。

原因：双击执行时没有带子命令，脚本执行完就退出；更常见的是JAVA_HOME指向了 JDK 8/11 或者指向了jre目录，JVM 启动阶段就抛UnsupportedClassVersionError，窗口来不及显示就没了。

解决：别双击，从命令行进到bin目录执行neo4j.bat console，把输出留在屏幕上。如果是UnsupportedClassVersionError或者Could not find or load main class，回头按 2.1 节把JAVA_HOME指到 JDK 17 根目录，用neo4j.bat里临时的set JAVA_HOME=方式先验证一遍再改全局。

5.2 启动日志里出现 Unrecognized setting

现象：库能起来，但日志开头一堆Unrecognized setting，或者明明改了内存参数，status里显示的堆大小没变。

原因：配置项键名写错。5.x 把dbms.memory.*、dbms.connector.*、dbms.directories.*这批前缀改成了server.*，从 4.x 教程里抄来的写法在 5.23 上不生效。

解决：逐行核对，堆和页缓存用server.memory.heap.initial_size、server.memory.heap.max_size、server.memory.pagecache.size；监听用server.default_listen_address、server.bolt.listen_address；导入目录用server.directories.import。改完重启，日志里那条告警消失才算改对。

5.3 本机能开控制台，同事浏览器打不开

现象：自己机器上http://localhost:7474正常，同事访问http://你的IP:7474一直转圈，Bolt 驱动也连不上。

原因：两层。第一层是server.default_listen_address还是默认的localhost，进程根本没在网卡上监听；第二层是 Windows 防火墙拦了入站。

解决：先把server.default_listen_address=0.0.0.0改上并重启，用netstat -ano | findstr :7474确认监听地址是0.0.0.0:7474而不是127.0.0.1:7474；再按 4.2 节的netsh命令放行 7474 和 7687。两步都做完还不行，八成是中间隔着别的网络设备。

5.4 密码忘了，登录直接被拒

现象：控制台登录提示认证失败，试了几次彻底想不起来当初设的密码。

原因：密码存在data\dbms\auth里，社区版没有「找回密码」这回事，只能重置。

解决：先neo4j.bat stop确保库停了，把data\dbms\auth这个文件改名备份或删掉，再neo4j.bat start。库会退回到初始的neo4j/neo4j，登录后强制改新密码。这个操作只动认证文件，不碰data\databases里的图数据，节点和关系都在。也正因为如此，auth文件我一直是跟data一起备份的，不然恢复完数据还得重新配一遍账号。

5.5 注册成服务后 start 成功但进程不在

现象：neo4j.bat install-service返回成功，neo4j.bat start也没报错，但status显示没在跑，7474 打不开。

原因：Windows 服务是以LocalSystem身份跑的，它读的是系统环境变量。如果你的JAVA_HOME是在用户变量里配的，服务进程根本看不到，JVM 起不来就直接退了。

解决：按 2.1 节用setx ... /M把JAVA_HOME写到系统变量，或者干脆在服务的环境里补一条。改完neo4j.bat uninstall-service再install-service重新注册一次——服务注册时会把当时的环境快照进去，不重新注册的话改了变量也不生效。另外服务方式启动失败时，logs\neo4j.log里通常有痕迹，别只看命令行输出。

6. 验证跑通：cypher-shell 与浏览器控制台的三级冒烟测试

服务起来、端口通，只能说明进程活着，不代表这套环境能用。我自己的习惯是跑三级冒烟，从「进程在不在」一路验到「Bolt 驱动能不能写读」，三级都过才算装完。

第一级看进程和服务状态：

neo4j.bat status

期望输出里带running at pid，PID 每次重启会变，重点是running。这一步不过，直接回第 5 章。

第二级用cypher-shell走 Bolt 协议，绕开浏览器，直接验证数据库本身：

cd /d D:\neo4j\neo4j-community-5.23.0\bin cypher-shell.bat -a bolt://localhost:7687 -u neo4j -p "你的密码" "RETURN 'ok' AS ping;"

-a是连接地址，-u用户名，-p密码，最后那个引号包起来的是要执行的 Cypher。能返回一行ok就说明 Bolt 通道和认证都没问题。接着做一次最小的写读：

CREATE (a:Person {name: 'A同学'})-[:KNOWS]->(b:Person {name: 'B同学'}) RETURN a.name AS from, b.name AS to;

再查回来确认数据落了盘：

MATCH (a:Person)-[r:KNOWS]->(b:Person) RETURN a.name, type(r), b.name; SHOW DATABASES;

SHOW DATABASES里默认库neo4j的状态应该是online，另有一个system库，那是存用户和权限元数据的，别往里写业务数据。

第三级是用应用侧驱动连一次，因为驱动版本和 Bolt 协议版本不匹配是另一类问题。以 Python 为例：

from neo4j import GraphDatabase # 5.x 的驱动统一用 bolt:// 或 neo4j:// 前缀 driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "你的密码")) with driver.session(database="neo4j") as session: count = session.run("MATCH (n) RETURN count(n) AS c").single()["c"] print("节点数:", count) driver.close()

database="neo4j"显式指定默认库，省得依赖驱动的默认行为。最后做一次重启验证，neo4j.bat restart之后再跑一遍计数，数字对得上，说明数据确实持久化了，不是只在内存里待着。

把这几步整理成一张对照表，装完照着勾一遍：

血泪经验是：以前我装完看到Started就以为完事，结果第一次真跑业务导入，才发现页缓存设成了默认的几百兆，整个导入过程一直在读盘，跑了三个小时。从那以后我每次装完这套环境，都会先跑一遍上面的冒烟，再顺手用dir /s data\databases\neo4j看一眼 store 大小，把页缓存按实际数据量重新校一遍，不再直接沿用模板值。这套习惯没什么技术含量，但确实让后续所有玄学问题都少了一大半。希望帮到你。

本文还有配套的精品资源，点击获取