企业官网建设流程全解析

从零到贡献：Address 本地开发环境搭建与测试体系完整指南

【免费下载链接】addressA self-hosted address and synthetic test-profile generator for 27 countries and regions, built from real open-data streets, administrative areas, coordinates, and postcodes. Supports multilingual output, IP-nearby generation, map previews, and API access. 基于真实开放数据的自托管地址与合成测试资料生成器，覆盖 27 个国家和地区，支持多语言地址、IP 附近生成、地图预览与 API 调用项目地址: https://gitcode.com/gh_mirrors/address4/address

Address是一个基于真实开放数据的自托管地址与合成测试资料生成器，覆盖 27 个国家和地区，支持多语言输出、IP 附近生成、地图预览与 API 调用。本文带你从零搭建它的本地开发环境，并系统讲解内置的测试体系——从无需真实数据库的单元测试，到 Playwright 端到端测试与线上验收脚本，让你在提交第一份贡献前对质量门禁心中有数。

一、开发环境要求：3 个组件就够

开始前先确认本地工具链，配置非常简单：

💡 好消息：日常开发不需要任何第三方 API Key。地图平台、Google 地理编码、翻译服务都只用于增强特定国家的数据，本地开发可以完全绕开它们。

二、克隆仓库并配置环境变量

克隆项目（国内可直接使用加速地址）：

git clone https://gitcode.com/gh_mirrors/address4/address cd address npm ci

项目根目录提供了完整的环境变量模板 .env.example，本地开发只需关注其中两项：

cp .env.example .env # 在 .env 中至少填写数据库连接，例如： # POSTGRES_URL=postgresql://address:你的密码@127.0.0.1:5432/address

其余配置（API 端口、同步队列、可选的地图/翻译密钥等）保持默认即可。全部可配置项及其含义都能在 .env.example 的注释中找到。

三、一键启动本地开发服务

数据库迁移和服务启动只需 3 条命令：

npm run db:migrate # 创建或迁移数据库表结构 npm run dev # 构建 WebUI 并以监听模式运行 API

启动后访问http://127.0.0.1:8787即可使用地址生成器；管理后台位于/admin/（初始密码admin）。

如果需要前端热更新，改为并行运行两条命令，Astro 开发服务器运行在 4321 端口，并把/api代理到后端：

npm run dev:api # 终端 1：Hono API 监听模式 npm run dev:web # 终端 2：Astro 热更新

下面是在本地环境生成的美国地址效果，右侧地图可点击跳转外部地图应用：

新数据库初始只有表结构。想在本地真正生成地址，按开发文档的做法，先导入行政目录，再挑一个数据量小的国家（如新加坡 SG）做增量导入即可，整个过程无需访问任何外部数据源密钥。

四、读懂测试体系：分层设计是核心

Address 的测试分为四层，由快到慢、由隔离到真实，这也是你贡献代码后需要逐层通过的质量门禁。

第 1 层：单元测试（秒级，零依赖）

npm test

这是最重要也最轻量的一层：基于 pg-mem 内存数据库和小型数据夹具运行完整 Vitest 套件，不需要启动真实的 PostgreSQL。tests/ 目录下 90 余个测试文件按职责划分：

• 域逻辑：generator-determinism.test.ts（生成器确定性）、postal-grade-format.test.ts（邮编格式）、china-address.test.ts等
• 数据管线：address-pool-v2.test.mjs、address-policy.test.mjs、sync-etl.test.mjs
• 接口与契约：api.test.ts、client-context-api.test.ts、translation-recovery.test.mjs

第 2 层：静态检查与生产构建

npm run check # Astro 诊断 + TypeScript 全量检查 npm run build # 生产构建 npm run check:public # 检查忽略规则、必需文件与密钥泄露形态

第 3 层：端到端测试（Playwright）

npm run test:admin-e2e # 管理后台控制台端到端流程 npm run test:ui-e2e # WebUI 稳定性与布局测试

这两组测试会真实启动浏览器执行页面操作，分别对应 tests/admin-console.e2e.mjs 和 tests/ui-reliability.e2e.mjs。只要你改了后台界面，这两条命令必须跑通：

第 4 层：线上验收脚本（可选）

部署到可访问环境后，还有一组面向真实运行实例的验收脚本，例如 scripts/validate-live-api.mjs 逐端点校验 API 契约，npm run test:production-live可一次性跑完 API、地址、契约、浏览器四项线上检查。

五、提交前检查清单：5 条命令对齐 CI

项目 CI 在 Ubuntu 与 Windows 双平台上执行的标准检查与本地完全一致，提交前按顺序跑完即可：

npm test npm run check npm run build npm run check:public git diff --check

CI 额外还会用bash -n校验所有 Shell 脚本语法、用python3 -m py_compile编译 server/sync/ 下的 Python 导出器——如果你动到了这两类文件，记得本地先验证。

六、开始贡献：目录结构与协作约定

第一次打开源码时，对照下面这张速查表找文件会快得多（完整版见 docs/DEVELOPMENT.zh-CN.md）：

几条值得记住的协作约定：

• 改公开 API：响应统一为{ data }或{ error }结构，需同步更新src/domain/api-contract.ts的 OpenAPI 描述和三语 API 文档（如 docs/API.zh-CN.md）
• 改数据库：新增版本化迁移，绝不修改已发布的迁移
• 改国家/数据源：国家元数据、地址格式、邮编规则、来源分片、测试与docs/strategies/中的策略文档需同时更新
• 不要提交真实凭据、数据库、日志或含私密数据的截图

结语

Node 24 + PostgreSQL 16，5 条命令启动，分四层测试把关——这就是 Address 从本地运行到贡献代码的完整路径。建议按顺序实践：先跑通npm run dev亲眼看到生成结果，再挑一个感兴趣的测试文件（比如generator-determinism.test.ts）读懂它，最后带着提交前检查清单发出你的第一份贡献。祝你在 27 个国家与地区的真实街道数据中，写出漂亮的第一个 Commit！🚀

【免费下载链接】addressA self-hosted address and synthetic test-profile generator for 27 countries and regions, built from real open-data streets, administrative areas, coordinates, and postcodes. Supports multilingual output, IP-nearby generation, map previews, and API access. 基于真实开放数据的自托管地址与合成测试资料生成器，覆盖 27 个国家和地区，支持多语言地址、IP 附近生成、地图预览与 API 调用项目地址: https://gitcode.com/gh_mirrors/address4/address