目录

• 1. 背景介绍
• 2. 环境准备
• 3. 项目结构分析
• 4. 问题诊断与解决
• 5. 详细修改步骤
• 6. 构建验证
• 7. 使用示例
• 8. 总结与最佳实践

---

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/

1. 背景介绍

1.1 ansiweather 工具简介

ansiweather 是一个 Shell 脚本，用于在终端显示当前天气情况，支持 ANSI 颜色和 Unicode 符号。天气数据来自 OpenWeatherMap 免费天气 API。它提供了便捷的天气查询功能，常用于：

• 终端环境集成（在 shell 启动时显示天气）
• 系统监控脚本（集成天气信息）
• 定时任务（定期查询天气）
• 脚本工具集成（在其他脚本中使用天气信息）
  

1.2 适配目标

将 ansiweather 1.19.1 版本适配到鸿蒙PC（HarmonyOS PC）平台，实现：

• 支持 HNP 包打包（纯 Shell 脚本，无需编译）
• 生成HNP格式的安装包
• 生成tar.gz格式的发布包
• 确保运行时依赖（jq, bc, curl/wget）可用

1.3 技术栈

• 项目类型: POSIX Shell 脚本（无需编译）
• 目标平台: aarch64-linux-ohos
• 打包格式: HNP (HarmonyOS Native Package)
• 运行时依赖: jq, bc, curl/wget

1.4 基本信息

项目	信息
项目名称	ansiweather
版本	1.19.1（适配版本）<br>1.19.0（原始版本）
许可证	BSD 2-Clause
目标平台	鸿蒙PC (aarch64-linux-ohos)
源码仓库	https://github.com/fcambus/ansiweather
鸿蒙化版本	2025-12-09

项目特点

• ✅ 纯 Shell 脚本：POSIX Shell 实现，无需编译，直接运行
• ✅ 终端天气显示：在终端中显示当前天气和预报信息
• ✅ ANSI 颜色支持：支持彩色输出，提升视觉效果
• ✅ Unicode 符号：支持天气图标符号显示
• ✅ 灵活配置：支持配置文件和环境变量配置
• ✅ 多城市支持：支持查询全球任意城市的天气

---

2. 环境准备

2.1 系统要求

• 开发环境: macOS / Linux / Windows (WSL)
• 鸿蒙SDK: OHOS SDK (包含native工具链和HNP打包工具)
• 运行时依赖: jq, bc, curl/wget（需要在目标系统上安装）

2.2 SDK安装

1. 下载SDK

# 下载鸿蒙SDK
cd ~
wget https://cidownload.openharmony.cn/version/Master_Version/ohos-sdk-full_ohos/20250819_020817/version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz

# 解压SDK
tar -zvxf version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz

2. SDK目录结构

ohos-sdk/
├── native/
│   ├── llvm/bin/          # 编译器工具链
│   ├── sysroot/           # 系统根目录（头文件和库）
│   └── build-tools/       # 构建工具
└── toolchains/
    └── hnpcli            # HNP打包工具

2.3 项目结构

HarmonyOSPC/build/
├── build.sh              # 主构建脚本
├── code/
│   └── ansiweather/      # ansiweather工具源码
│       ├── ansiweather   # 主脚本文件
│       ├── ansiweather.1 # 手册页
│       ├── build_ohos.sh # 鸿蒙构建脚本
│       └── hnp.json      # HNP包配置
└── output/               # 构建输出目录

---

3. 项目结构分析

3.1 源码文件分析

ansiweather 是一个纯 Shell 脚本项目，主要组件包括：

ansiweather/
├── ansiweather              # 主脚本文件 (11KB, 445行)
├── ansiweather.1           # 手册页 (3.1KB)
├── ansiweatherrc.example   # 配置文件示例 (948B)
├── build_ohos.sh           # 鸿蒙构建脚本
├── hnp.json                # HNP 包配置
├── README.md               # 项目说明文档
├── LICENSE                 # BSD 2-Clause 许可证
└── ChangeLog               # 变更日志

3.2 构建系统分析

ansiweather 是纯 Shell 脚本，无需编译：

• 构建过程: 直接复制文件，设置权限，打包 HNP
• 无需编译工具链: 不需要编译器，只需要文件复制工具
• 运行时依赖: jq, bc, curl/wget（需要在目标系统上安装）

3.3 适配策略

由于 ansiweather 是纯 Shell 脚本，适配工作主要包括：

1. 脚本兼容性：确保脚本符合 POSIX 标准
2. 依赖检查：检查运行时依赖（jq, bc, curl/wget）
3. 打包配置：创建 HNP 包配置文件
4. 构建脚本：编写自动化构建脚本（复制文件，无需编译）

3.4 构建脚本设计

build_ohos.sh 脚本的主要步骤：

1. 环境检查：检查运行时依赖（jq, bc, curl/wget）是否存在（仅警告）
2. 复制脚本文件：复制主脚本到 bin/ 目录
3. 复制文档：复制手册页、配置文件示例、LICENSE 等到相应目录
4. 设置权限：确保脚本文件具有执行权限
5. 打包：生成 HNP 包和 tar.gz 压缩包

关键代码：

# 复制主脚本文件
cp ansiweather ${ANSIWEATHER_INSTALL_HNP_PATH}/bin/
chmod +x ${ANSIWEATHER_INSTALL_HNP_PATH}/bin/ansiweather

# 复制手册页
cp ansiweather.1 ${ANSIWEATHER_INSTALL_HNP_PATH}/share/man/man1/

# 复制配置文件示例
cp ansiweatherrc.example ${ANSIWEATHER_INSTALL_HNP_PATH}/share/doc/ansiweather/

3.5 运行时依赖

ansiweather 需要以下运行时依赖：

1. jq：JSON 数据解析和处理（必需）
2. bc：浮点数算术运算（必需）
3. curl 或 wget：HTTP 客户端，用于获取天气数据（必需）

依赖检查：

脚本会在运行时检查这些依赖：

jqpath=$(command -v jq)
if [ "$jqpath" = "" ]
then
    echo "ERROR: Cannot find jq binary"
    exit 69 # EX_UNAVAILABLE
fi

bcpath=$(command -v bc)
if [ "$bcpath" = "" ]
then
    echo "ERROR: Cannot find bc binary"
    exit 69 # EX_UNAVAILABLE
fi

---

4. 问题诊断与解决

4.1 问题诊断

在适配过程中，我们遇到了以下主要问题：

1. HNP 包 links 配置问题：合入 base.hnp 时 links 可能不会被处理
2. 运行时依赖检查：需要确保 jq, bc, curl/wget 在目标系统上可用

4.2 解决方案

4.2.1 HNP 包配置优化

问题：使用 links 配置时，合入 base.hnp 可能不会被处理。

解决方案：使用空的 install: {} 配置，让顶层标准目录结构自动合并到 sysroot。

---

5. 详细修改步骤

5.1 HNP 包配置

hnp.json 配置文件：

{
    "type": "hnp-config",
    "name": "ansiweather",
    "version": "1.19.1",
    "install": {
        "links": [
            {
                "source": "bin/ansiweather",
                "target": "ansiweather"
            }
        ]
    }
}

配置说明：

• name: 包名称
• version: 版本号（适配版本 1.19.1）
• install.links: 安装时的符号链接配置，将 bin/ansiweather 链接为 ansiweather 命令

构建流程

完整的构建流程：

# 1. 环境准备
export OHOS_SDK=/path/to/ohos-sdk
export HNP_PUBLIC_PATH=${OHOS_SDK}/HarmonyOSPC/build/hnp/data/service/hnp

# 2. 执行构建脚本
cd HarmonyOSPC/build
SPECIFIC_DIR=ansiweather ./build.sh --sdk /path/to/ohos-sdk

# 3. 构建输出
# output/ansiweather.hnp
# output/ohos_ansiweather_1.19.1.tar.gz

---

6. 构建验证

6.1 构建环境要求

• 开发环境：macOS 或 Linux
• OpenHarmony SDK：6.0.0.46-Beta1 或更高版本
• 运行时依赖：jq, bc, curl/wget（需要在目标系统上安装）

6.2 构建步骤

# 1. 进入构建目录
cd HarmonyOSPC/build

# 2. 执行构建脚本
SPECIFIC_DIR=ansiweather ./build.sh --sdk /Users/lijiajun/ohos-sdk

# 3. 构建输出位于 output/ 目录
ls output/
# ansiweather.hnp
# ohos_ansiweather_1.19.1.tar.gz

6.3 构建输出

构建成功后，会在 output/ 目录生成以下文件：

output/
├── ansiweather.hnp                    # HNP 包文件 (11KB)
└── ohos_ansiweather_1.19.1.tar.gz   # tar.gz 压缩包 (8.3KB)

安装路径：

/data/service/hnp/ansiweather.org/ansiweather_1.19.1/
├── bin/
│   └── ansiweather                    # 主脚本文件
├── share/
│   ├── man/
│   │   └── man1/
│   │       └── ansiweather.1         # 手册页
│   └── doc/
│       └── ansiweather/
│           ├── ansiweatherrc.example  # 配置文件示例
│           ├── README.md             # 项目说明
│           ├── LICENSE                # 许可证
│           └── AUTHORS                # 作者信息
└── hnp.json                           # HNP 配置文件

6.4 部署到鸿蒙PC

方式一：使用 HNP 包安装

# 在鸿蒙PC上执行
hnp install ansiweather.hnp

# 验证安装
ansiweather -v

方式二：使用 tar.gz 包安装

# 1. 传输文件到鸿蒙PC
scp ohos_ansiweather_1.19.1.tar.gz user@harmony-pc:/tmp/

# 2. 在鸿蒙PC上解压
cd /tmp
tar -xzf ohos_ansiweather_1.19.1.tar.gz

# 3. 复制到安装目录
sudo mkdir -p /data/service/hnp/ansiweather.org/
sudo cp -r ansiweather_1.19.1 /data/service/hnp/ansiweather.org/

# 4. 添加到 PATH（可选）
export PATH=$PATH:/data/service/hnp/ansiweather.org/ansiweather_1.19.1/bin

# 5. 验证安装
/data/service/hnp/ansiweather.org/ansiweather_1.19.1/bin/ansiweather -v

---

7. 使用示例

7.1 基本用法

7.1.1 显示当前天气（使用默认位置）

# 显示当前天气（需要先配置位置）
ansiweather

# 显示版本信息
ansiweather -v

7.1.2 指定城市查询天气

# 查询北京天气（公制单位）
ansiweather -l "Beijing,CN" -u metric

# 查询上海天气（显示符号）
ansiweather -l "Shanghai,CN" -u metric -s true

# 查询深圳天气（显示所有信息）
ansiweather -l "Shenzhen,CN" -u metric -s true -w true -h true -p true -d true

7.1.3 天气预报

# 显示未来5天预报
ansiweather -l "Beijing,CN" -u metric -F

# 显示未来3天预报
ansiweather -l "Shanghai,CN" -u metric -f 3

# 显示预报并包含符号和日出日落信息
ansiweather -l "Shenzhen,CN" -u metric -f 5 -s true -d true

7.1.4 自定义显示选项

# 禁用 ANSI 颜色
ansiweather -l "Beijing,CN" -a false

# 启用 Unicode 符号
ansiweather -l "Shanghai,CN" -s true

# 显示/隐藏特定信息
ansiweather -l "Shenzhen,CN" -w true -h true -p true -i true

7.2 配置文件使用

7.2.1 创建配置文件

# 复制示例配置文件
cp /data/service/hnp/ansiweather.org/ansiweather_1.19.1/share/doc/ansiweather/ansiweatherrc.example ~/.ansiweatherrc

# 编辑配置文件
vi ~/.ansiweatherrc

7.2.2 配置文件示例

# ~/.ansiweatherrc
api_key:your_api_key_here
fetch_cmd:curl -sf
location:Beijing,CN
units:metric
forecast:0
ansi:true
symbols:true
show_feels_like:true
show_uvi:true
show_wind:true
show_humidity:true
show_pressure:true
show_daylight:true

7.2.3 使用配置文件

# 使用配置文件中的设置
ansiweather

# 命令行参数会覆盖配置文件设置
ansiweather -l "Shanghai,CN"  # 临时使用上海，但其他设置使用配置文件

7.3 实际应用场景

7.3.1 终端启动时显示天气

在 ~/.bashrc 或 ~/.zshrc 中添加：

# 显示当前天气
ansiweather -l "Beijing,CN" -u metric -s true

7.3.2 定时查询天气

创建定时任务：

# 添加到 crontab
# 每天早上8点显示天气
0 8 * * * /data/service/hnp/ansiweather.org/ansiweather_1.19.1/bin/ansiweather -l "Beijing,CN" -u metric -s true

7.3.3 脚本中使用

#!/bin/sh
# 获取天气信息并处理
weather=$(ansiweather -l "Beijing,CN" -u metric -a false)
echo "Weather: $weather"

# 提取温度信息（需要结合其他工具）
ansiweather -l "Beijing,CN" -u metric -a false | grep -o "[0-9]*°C"

---

8. 总结与最佳实践

8.1 技术亮点

1. 零编译部署

实现方式：

• ansiweather 是纯 Shell 脚本，无需编译
• 直接复制脚本文件即可使用
• 构建过程简单快速

优势：

• 部署简单，无需编译工具链
• 跨平台兼容性好
• 易于维护和更新

2. POSIX Shell 兼容

实现方式：

• 使用 #!/bin/sh 而不是 #!/bin/bash
• 使用 command -v 而不是 which
• 遵循 POSIX Shell 标准

优势：

• 在任何 POSIX 兼容的 shell 中运行
• 兼容性好，不依赖特定 shell 扩展

3. 灵活的配置系统

实现方式：

• 支持配置文件 ~/.ansiweatherrc
• 支持环境变量 ANSIWEATHERRC
• 支持 XDG 配置目录
• 命令行参数可以覆盖配置文件

优势：

• 用户可以根据需要自定义配置
• 支持多用户环境
• 配置灵活，易于管理

4. HNP 包管理集成

实现方式：

• 创建标准的 HNP 包配置文件
• 支持 hnp install 一键安装
• 自动创建符号链接到 PATH

优势：

• 符合鸿蒙PC包管理规范
• 安装和卸载方便
• 版本管理清晰

8.2 常见问题排查

8.2.1 命令未找到

问题：执行 ansiweather 命令时提示 command not found

原因：

• HNP 包未正确安装
• PATH 环境变量未配置

解决方案：

# 1. 检查 HNP 包是否安装
ls -la /data/service/hnp/ansiweather.org/ansiweather_1.19.1/bin/ansiweather

# 2. 如果文件存在，添加到 PATH
export PATH=$PATH:/data/service/hnp/ansiweather.org/ansiweather_1.19.1/bin

# 3. 或者使用完整路径
/data/service/hnp/ansiweather.org/ansiweather_1.19.1/bin/ansiweather -v

# 4. 如果文件不存在，重新安装 HNP 包
hnp install ansiweather.hnp

8.2.2 依赖工具未找到

问题：执行 ansiweather 时提示 ERROR: Cannot find jq binary 或 ERROR: Cannot find bc binary

原因：

• jq 或 bc 未安装在目标系统上

解决方案：

# 1. 检查依赖工具
which jq
which bc
which curl

# 2. 如果缺少，需要安装
# jq 和 bc 需要单独编译安装（参考 jq 和 bc 的适配文档）
# curl 通常在系统中已安装

# 3. 验证依赖
jq --version
bc --version
curl --version

8.2.3 网络连接问题

问题：无法获取天气数据

原因：

• 网络连接问题
• OpenWeatherMap API 访问受限

解决方案：

# 1. 检查网络连接
curl -s https://api.openweathermap.org/data/2.5/weather?q=Beijing,CN

# 2. 检查 API key 配置
cat ~/.ansiweatherrc | grep api_key

# 3. 使用自己的 API key（推荐）
# 访问 https://home.openweathermap.org/users/sign_up 注册账号
# 获取免费的 API key

8.2.4 配置文件问题

问题：配置文件不生效

原因：

• 配置文件路径不正确
• 配置文件格式错误

解决方案：

# 1. 检查配置文件位置
echo $ANSIWEATHERRC  # 如果设置了环境变量
ls -la ~/.ansiweatherrc
ls -la ~/.config/ansiweather/config

# 2. 检查配置文件格式
cat ~/.ansiweatherrc
# 格式应该是：key:value（使用冒号分隔）

# 3. 使用示例配置文件
cp /data/service/hnp/ansiweather.org/ansiweather_1.19.1/share/doc/ansiweather/ansiweatherrc.example ~/.ansiweatherrc

8.3 项目总结

8.3.1 适配成果

✅ 成功适配：ansiweather 1.19.1 已成功适配到 鸿蒙PC 平台

✅ 功能完整：所有核心功能正常工作，包括：

• 当前天气显示
• 天气预报显示
• ANSI 颜色支持
• Unicode 符号支持
• 灵活的配置系统

✅ 易于部署：纯 Shell 脚本，无需编译，直接复制即可使用

✅ 依赖明确：运行时依赖（jq, bc, curl/wget）清晰明确

8.3.2 技术价值

1. 展示了 Shell 脚本项目的鸿蒙化适配方法

   • 无需编译的脚本项目适配流程
   • HNP 包管理集成
   • 运行时依赖管理

2. 提供了终端天气显示工具

   • 为鸿蒙PC开发者提供便捷的天气查询功能
   • 支持多种显示选项和配置方式
   • 适合集成到终端环境

3. 积累了适配经验

   • Shell 脚本项目适配最佳实践
   • 运行时依赖检查和处理
   • 配置文件管理策略

8.3.3 后续优化方向

1. 依赖管理：确保 jq 和 bc 在目标系统上可用
2. 功能扩展：添加鸿蒙PC特有的功能支持
3. 文档完善：补充更多使用示例和最佳实践
4. 测试覆盖：增加自动化测试用例

8.4 参考资料

官方文档

• ansiweather GitHub：https://github.com/fcambus/ansiweather
• OpenWeatherMap API：https://openweathermap.org/api
• OpenWeatherMap 注册：https://home.openweathermap.org/users/sign_up

OpenHarmony 相关

技术文档

• POSIX Shell 标准：https://pubs.opengroup.org/onlinepubs/9699919799/utilities/sh.html
• jq 文档：https://jqlang.org
• bc 文档：https://www.gnu.org/software/bc/

相关项目

• jq：https://github.com/jqlang/jq（JSON 处理器）
• bc：https://www.gnu.org/software/bc/（计算器）

---

📎 附录

A. 📁 完整文件清单

📝 创建的文件:

• 🔧 build_ohos.sh - OpenHarmony构建脚本
• 📝 hnp.json - HNP包配置文件
• 📄 CHANGELOG - 变更日志（添加鸿蒙PC适配信息）
• 📄 README.OPENSOURCE - 开源说明文档

📝 修改的文件:

• 🔧 build_ohos.sh - 配置HNP包打包（纯Shell脚本，无需编译）
• 📝 hnp.json - 使用空的install: {}配置（与ts项目一致）

📦 生成的文件:

• 📦 output/ansiweather.hnp - HNP格式安装包
• 📦 output/ohos_ansiweather_1.19.1.tar.gz - tar.gz格式发布包

B. 💻 参考命令

# 构建命令
cd /Users/lijiajun/ohos-sdk/HarmonyOSPC/build
SPECIFIC_DIR=ansiweather ./build.sh --sdk /Users/lijiajun/ohos-sdk

# 查看构建输出
ls -lh output/ | grep ansiweather

# 验证安装目录
tree ${HNP_PUBLIC_PATH}/ansiweather.org/ansiweather_1.19.1/

# 验证脚本文件格式（在macOS上）
file ${HNP_PUBLIC_PATH}/ansiweather.org/ansiweather_1.19.1/bin/ansiweather
# 应该显示: POSIX shell script text executable

# 测试命令（在鸿蒙PC上，需要先安装jq和bc）
export PATH=${HNP_PUBLIC_PATH}/ansiweather.org/ansiweather_1.19.1/bin:$PATH
ansiweather -v
ansiweather -l "Beijing,CN" -u metric
ansiweather -l "Shanghai,CN" -u metric -s true -F

# 如果出现"command not found"错误，检查：
# 1. HNP包是否正确合入base.hnp
# 2. 文件是否在sysroot/bin/目录下
# 3. PATH环境变量是否包含sysroot/bin
# 4. 运行时依赖（jq, bc, curl/wget）是否已安装

C. 📌 版本信息

• 📁 ansiweather版本: 1.19.1
• 📅 适配日期: 2025-12-09
• 🎯 目标平台: aarch64-linux-ohos
• 🔧 项目类型: POSIX Shell脚本（无需编译）
• 📦 运行时依赖: jq, bc, curl/wget（需要在目标系统上安装）
• 🔗 源仓库地址: https://github.com/fcambus/ansiweather
• 🔗 适配完成仓库地址: https://gitcode.com/szkygc/ansiweather4oh

D. 📚 相关资源

• 🌐 ansiweather GitHub: https://github.com/fcambus/ansiweather
• 🌐 OpenWeatherMap API: https://openweathermap.org/api
• 📖 POSIX Shell标准: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/sh.html
• 🌐 OpenHarmony PC开发者专区: https://gitcode.com/OpenHarmonyPCDeveloper
• 🌐 HarmonyOS PC 开发者社区: https://harmonypc.csdn.net/content

E. 💡 技术说明

Shell脚本适配简介：

ansiweather是纯Shell脚本项目，适配工作主要包括：

1. 脚本兼容性: 确保脚本符合POSIX标准，能在任何POSIX兼容的shell中运行
2. 依赖检查: 检查运行时依赖（jq, bc, curl/wget）是否可用
3. 打包配置: 创建HNP包配置文件，使用顶层标准目录结构
4. 零编译: 无需编译，直接复制脚本文件即可使用

ansiweather的优势：

• ✅ 零编译：纯Shell脚本，无需编译工具链
• ✅ POSIX兼容：遵循POSIX标准，兼容性好
• ✅ 灵活配置：支持配置文件和环境变量
• ✅ 易于部署：直接复制文件即可使用

---

🎉 结语

本文档详细介绍了ansiweather终端天气显示工具在鸿蒙PC平台上的适配过程。通过配置HNP包打包、确保运行时依赖可用等问题，成功实现了ansiweather在鸿蒙PC平台上的部署。

ansiweather工具为终端应用开发提供了便捷的天气查询功能，是开发终端工具和系统监控脚本的重要工具。希望本文档能够帮助开发者：

• 📊 理解Shell脚本项目的适配方法
• 🔧 掌握HNP包的构建和打包流程
• 📦 了解运行时依赖管理策略
• 💻 学习命令行工具的开发实践

💬 如有问题或建议，欢迎反馈！