本指南基于官方文档内容，介绍了在 Ubuntu 24.04.3 LTS 系统上，按照官方步骤搭建 Decidim 本地开发环境，并配置依赖和启动本地服务器的流程。请注意，本文档内容基于提供的资料，不代表最新的或最完整的生产环境配置。
### 依赖环境准备
在开始之前，您需要确保系统安装了以下依赖：
* **Git**: 版本需为 2.34+。
* **PostgreSQL**: 版本需为 17.4+。
* **Ruby**: 版本需为 3.4.7。
* **Node.js**: 版本需为 22.14.x。
* **Npm**: 版本需为 10.9.x。
* **其他依赖**: ImageMagick, LibVips, Chrome 浏览器和 chromedriver（如果需要运行测试）。
**兼容性参考**: 根据提供的资料，Decidim v0.32 版本推荐使用 Ruby 3.4.7 和 Node 22.14.x。
### 步骤详解
**1. 安装 rbenv (Ruby 版本管理)**
首先，更新系统包列表并安装必要的构建工具：
```bash
sudo apt update
sudo apt install -y build-essential curl git libssl-dev zlib1g-dev libffi-dev libyaml-dev
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
rbenv install 3.4.7
rbenv global 3.4.7
```
**2. 安装 PostgreSQL (数据库)**
安装 PostgreSQL 及其开发库，并创建一个用于 Decidim 的用户和数据库：
```bash
sudo apt install -y postgresql libpq-dev
sudo -u postgres psql -c "CREATE USER decidim_app WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'thepassword'"
```
*请务必将示例中的密码 `thepassword` 更改为实际密码并妥善保存。*
**3. 安装 Node.js 和 Yarn**
使用 nvm 安装 Node.js，并全局安装 Yarn：
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source "$HOME/.nvm/nvm.sh"
nvm install 22
npm install -g yarn
```
**4. 安装 Decidim 框架**
安装额外的系统依赖，然后全局安装 decidim gem：
```bash
sudo apt install -y libicu-dev imagemagick libvips libvips-tools
gem install decidim
```
接着，使用 `decidim` 命令创建一个应用程序实例（将 `decidim_application` 替换为您期望的应用名）：
```bash
decidim decidim_application
```
**5. 配置数据库环境变量**
为了配置数据库连接等，推荐使用 `.rbenv-vars` 文件。请在**位于您 `decidim_application` 目录之外的任何文件夹**中创建此文件，以避免泄露密钥：
首先安装 `rbenv-vars`：
```bash
git clone https://github.com/rbenv/rbenv-vars.git "$(rbenv root)"/plugins/rbenv-vars
```
然后创建 `.rbenv-vars` 文件，并填入您的数据库凭证（请替换示例密码）：
```bash
cat << EOF > .rbenv-vars
DATABASE_HOST=localhost
DATABASE_USERNAME=decidim_app
DATABASE_PASSWORD=thepassword
EOF
```
**6. 初始化本地开发应用**
进入新创建的应用目录，并进行版本控制和数据库初始化：
```bash
cd decidim_application
git add .
git commit -m "Initial commit. Generated with Decidim https://decidim.org"
# 创建数据库并运行迁移
bin/rails db:create db:migrate
# 预编译静态资源
bin/rails assets:precompile
# 运行数据库种子数据（包含示例管理员和普通用户）
bin/rails db:seed
```
运行 `bin/rails db:seed` 后，系统会创建默认数据，包括一个管理员账户（邮箱：`admin@example.org`，密码：`decidim123456789`）和一个普通用户账户（邮箱：`user@example.org`，密码：`decidim123456789`）。
**7. 启动本地 Web 服务器**
最后，启动开发服务器：
```bash
bin/dev
```
您可以通过访问 `http://localhost:3000` 来查看正在运行的应用。
**注意**: 种子数据（如示例用户）不会在生产环境中创建。如需在 Demo 或 Staging 环境运行种子数据，请执行 `SEED=true bin/rails assets:precompile db:seed`。